Mídia profunda — transcribe / analyzeImage

Os dois ports — o módulo não importa SDK nenhum

Cada chamada de rede vira um port injetado: uma única função que devolve um Result. Veja os dois tipos lado a lado — o módulo de tipos só importa z (Zod) e Result:

export type TranscriptionBackend = (
  req: TranscriptionRequest,
) => Promise<Result<TranscriptionResult, Error>>;

export type VisionBackend = (
  req: VisionRequest,
) => Promise<Result<VisionResult, Error>>;

Por que dois tipos idênticos na forma?

Porque a forma é a contratação: "me dê um request validado, eu te devolvo um Result, e eu nunca lanço". Um é produção (fetch sobre um endpoint), o outro é teste (uma fake que devolve um Result fixo). O kernel não sabe nem se importa qual dos dois recebeu — só vê o port.

O kernel inteiro, verbatim

const parsedReq = transcriptionRequestSchema.safeParse(req);
if (!parsedReq.success) {
  return err(new Error(`Invalid transcription request: ${parsedReq.error.message}`));
}

const transcribed = await deps.backend(parsedReq.data);
if (!transcribed.ok) return transcribed;        // falha do backend ⇒ err

const parsed = transcriptionResultSchema.safeParse(transcribed.value);
if (!parsed.success) {
  return err(new Error(`Invalid transcription result: ${parsed.error.message}`)); // saída não confiável
}
return ok(parsed.data);

analyzeImage é a MESMA coisa

analyzeImage (linhas 76–93) é byte-a-byte a mesma forma — validar request → backend → validar result — diferindo só nos schemas (visionRequestSchema / visionResultSchema). Essa simetria é a lição: uma vez firmado o padrão, a próxima ferramenta de mídia é mecânica.

O schema com o refine

z.object({
  audioUrl: z.string().url('audioUrl must be a valid URL').optional(),
  audioBase64: z.string().min(1, 'audioBase64 cannot be empty').optional(),
  mimeType: z.string().min(1).optional(),
}).refine(
  (req) => (req.audioUrl === undefined) !== (req.audioBase64 === undefined),
  { message: 'exactly one of audioUrl or audioBase64 is required' },
);

Dois testes fixam os dois modos de falha

A suíte pina ambos os modos de falha — nenhuma fonte (linhas 50–60) e as duas fontes (62–70) — cada um rejeitado no boundary antes de o backend ser chamado. O teste de "nenhuma fonte" ainda usa uma flag called=false para provar que o backend não foi tocado. Um terceiro teste (72–77) rejeita uma audioUrl que não é URL.

Os dois schemas de resultado

export const transcriptionResultSchema = z.object({
  text: z.string(),                       // era `transcript`; pode ser '' (silêncio)
  provider: z.string().min(1).optional(), // proveniência opcional
});

export const visionResultSchema = z.object({
  analysis: z.string(),                   // continua `analysis`
});

Note: text é z.string() sem .min(1) — string vazia é válida de propósito (silêncio). Já o request de visão exige prompt não-vazio (.min(1)), porque pedir análise sem pergunta não faz sentido.

O mapeamento defensivo de linha

const mapTranscriptionRow = (payload) => {
  const provider = readField(payload, 'provider');
  return {
    text: asString(readField(payload, 'text') ?? readField(payload, 'transcript')), // fallback
    ...(typeof provider === 'string' && provider.length > 0 ? { provider } : {}),
  };
};
const mapVisionRow = (payload) => ({
  analysis: asString(readField(payload, 'analysis') ?? readField(payload, 'content')), // fallback
});

postJson — o muro fail-closed do transporte

O postJson (linhas 139–155) usa tryCatchAsync para envolver tanto a chamada quanto o response.json(), e checa response.ok no meio. As três falhas de transporte — throw de rede, status não-2xx, JSON inparseável — viram err cada uma. O fetch em si é um campo de config injetável (default: o global, linhas 90/117), então os testes injetam um fetch fake e nunca abrem um socket.