fix: decode base64-encoded embeddings in recorder (#64)

## Problem

When recording fixtures, the recorder fails to save OpenAI embedding
responses that use base64 encoding. The OpenAI API returns
base64-encoded embeddings when `encoding_format: "base64"` is set (the
default in many SDKs, including Python's `openai` package).

`buildFixtureResponse` checks `Array.isArray(first.embedding)` but the
embedding is a base64 string, not an array. The fixture is saved with a
`proxy_error`:

```json
{
  "response": {
    "error": { "message": "Could not detect response format from upstream", "type": "proxy_error" },
    "status": 200
  }
}
```

## Fix

Extract `encoding_format` from the raw request body and pass it to
`buildFixtureResponse`. When `encoding_format === "base64"` and the
embedding is a string, decode it via `Buffer.from(embedding, "base64")`
→ `Float32Array` → `Array.from(floats)`.

This is forward-safe — only decodes when `encoding_format` explicitly
says `"base64"`, so future encoding formats (e.g. `"int8"`) won't be
misinterpreted.

## Changes

- `recorder.ts`: Extract `encoding_format` from raw request, pass to
`buildFixtureResponse`, decode base64 when detected

Author: jpr5

src/__tests__/recorder.test.ts

@@ -2368,6 +2368,161 @@ describe("buildFixtureResponse format detection", () => {
     expect(fixtureContent.fixtures[0].response.embedding).toEqual([0.1, 0.2, 0.3]);
   });
 
+  it("decodes base64-encoded embeddings when encoding_format is base64", async () => {
+    // Float32Array([0.5, 1.0, -0.25]) encoded as base64
+    const base64Embedding = "AAAAPwAAgD8AAIC+";
+    const { url: upstreamUrl } = await createRawUpstreamWithStatus({
+      object: "list",
+      data: [{ object: "embedding", index: 0, embedding: base64Embedding }],
+      model: "text-embedding-3-small",
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "llmock-record-"));
+    recorder = await createServer([], {
+      port: 0,
+      record: { providers: { openai: upstreamUrl }, fixturePath: tmpDir },
+    });
+
+    const resp = await post(`${recorder.url}/v1/embeddings`, {
+      model: "text-embedding-3-small",
+      input: "base64 embedding test",
+      encoding_format: "base64",
+    });
+
+    expect(resp.status).toBe(200);
+
+    const files = fs.readdirSync(tmpDir);
+    const fixtureFiles = files.filter((f) => f.endsWith(".json"));
+    expect(fixtureFiles).toHaveLength(1);
+
+    const fixtureContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, fixtureFiles[0]), "utf-8"),
+    ) as {
+      fixtures: Array<{
+        response: { embedding?: number[] };
+      }>;
+    };
+    // Should decode base64 → Float32Array → number[]
+    expect(fixtureContent.fixtures[0].response.embedding).toEqual([0.5, 1, -0.25]);
+  });
+
+  it("does not decode base64 embedding when encoding_format is not set", async () => {
+    // Same base64 string but no encoding_format in request — should NOT decode
+    const base64Embedding = "AAAAPwAAgD8AAIC+";
+    const { url: upstreamUrl } = await createRawUpstreamWithStatus({
+      object: "list",
+      data: [{ object: "embedding", index: 0, embedding: base64Embedding }],
+      model: "text-embedding-3-small",
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "llmock-record-"));
+    recorder = await createServer([], {
+      port: 0,
+      record: { providers: { openai: upstreamUrl }, fixturePath: tmpDir },
+    });
+
+    const resp = await post(`${recorder.url}/v1/embeddings`, {
+      model: "text-embedding-3-small",
+      input: "base64 no format test",
+    });
+
+    expect(resp.status).toBe(200);
+
+    const files = fs.readdirSync(tmpDir);
+    const fixtureFiles = files.filter((f) => f.endsWith(".json"));
+    expect(fixtureFiles).toHaveLength(1);
+
+    const fixtureContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, fixtureFiles[0]), "utf-8"),
+    ) as {
+      fixtures: Array<{
+        response: { error?: { type: string } };
+      }>;
+    };
+    // Without encoding_format, base64 string embedding is not an array →
+    // falls through to proxy_error
+    expect(fixtureContent.fixtures[0].response.error?.type).toBe("proxy_error");
+  });
+
+  it("still detects array embeddings when encoding_format is base64", async () => {
+    // Some upstream responses return array format even when base64 was requested
+    const { url: upstreamUrl } = await createRawUpstreamWithStatus({
+      object: "list",
+      data: [{ object: "embedding", index: 0, embedding: [0.5, 1.0, -0.25] }],
+      model: "text-embedding-3-small",
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "llmock-record-"));
+    recorder = await createServer([], {
+      port: 0,
+      record: { providers: { openai: upstreamUrl }, fixturePath: tmpDir },
+    });
+
+    const resp = await post(`${recorder.url}/v1/embeddings`, {
+      model: "text-embedding-3-small",
+      input: "array with base64 format test",
+      encoding_format: "base64",
+    });
+
+    expect(resp.status).toBe(200);
+
+    const files = fs.readdirSync(tmpDir);
+    const fixtureFiles = files.filter((f) => f.endsWith(".json"));
+    expect(fixtureFiles).toHaveLength(1);
+
+    const fixtureContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, fixtureFiles[0]), "utf-8"),
+    ) as {
+      fixtures: Array<{
+        response: { embedding?: number[] };
+      }>;
+    };
+    // Array.isArray check comes first, so array embeddings work regardless of encoding_format
+    expect(fixtureContent.fixtures[0].response.embedding).toEqual([0.5, 1, -0.25]);
+  });
+
+  it("handles truncated base64 embedding gracefully (odd byte count)", async () => {
+    // 2 bytes decodes to 0 float32 elements — produces empty embedding, not a crash
+    const shortBase64 = Buffer.from([0x00, 0x01]).toString("base64");
+    const { url: upstreamUrl } = await createRawUpstreamWithStatus({
+      object: "list",
+      data: [{ object: "embedding", index: 0, embedding: shortBase64 }],
+      model: "text-embedding-3-small",
+      usage: { prompt_tokens: 5, total_tokens: 5 },
+    });
+
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "llmock-record-"));
+    recorder = await createServer([], {
+      port: 0,
+      record: { providers: { openai: upstreamUrl }, fixturePath: tmpDir },
+    });
+
+    const resp = await post(`${recorder.url}/v1/embeddings`, {
+      model: "text-embedding-3-small",
+      input: "truncated base64 test",
+      encoding_format: "base64",
+    });
+
+    expect(resp.status).toBe(200);
+
+    const files = fs.readdirSync(tmpDir);
+    const fixtureFiles = files.filter((f) => f.endsWith(".json"));
+    expect(fixtureFiles).toHaveLength(1);
+
+    const fixtureContent = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, fixtureFiles[0]), "utf-8"),
+    ) as {
+      fixtures: Array<{
+        response: { embedding?: number[] };
+      }>;
+    };
+    // Truncated base64 decodes to empty array rather than crashing
+    expect(fixtureContent.fixtures[0].response.embedding).toEqual([]);
+  });
+
   it("preserves error code field from upstream error response", async () => {
     const { url: upstreamUrl } = await createRawUpstreamWithStatus(
       {

src/recorder.ts

@@ -161,7 +161,13 @@ export async function proxyAndRecord(
       // Not JSON — could be an unknown format
       defaults.logger.warn("Upstream response is not valid JSON — saving as error fixture");
     }
-    fixtureResponse = buildFixtureResponse(parsedResponse, upstreamStatus);
+    let encodingFormat: string | undefined;
+    try {
+      encodingFormat = rawBody ? JSON.parse(rawBody).encoding_format : undefined;
+    } catch {
+      /* not JSON */
+    }
+    fixtureResponse = buildFixtureResponse(parsedResponse, upstreamStatus, encodingFormat);
   }
 
   // Build the match criteria from the original request
@@ -289,7 +295,11 @@ function makeUpstreamRequest(
  * Detect the response format from the parsed upstream JSON and convert
  * it into an llmock FixtureResponse.
  */
-function buildFixtureResponse(parsed: unknown, status: number): FixtureResponse {
+function buildFixtureResponse(
+  parsed: unknown,
+  status: number,
+  encodingFormat?: string,
+): FixtureResponse {
   if (parsed === null || parsed === undefined) {
     // Raw / unparseable response — save as error
     return {
@@ -319,6 +329,15 @@ function buildFixtureResponse(parsed: unknown, status: number): FixtureResponse
     if (Array.isArray(first.embedding)) {
       return { embedding: first.embedding as number[] };
     }
+    if (typeof first.embedding === "string" && encodingFormat === "base64") {
+      try {
+        const buf = Buffer.from(first.embedding, "base64");
+        const floats = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+        return { embedding: Array.from(floats) };
+      } catch {
+        // Corrupted base64 or non-float32 data — fall through to error
+      }
+    }
   }
 
   // Direct embedding: { embedding: [...] }