videobook 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,44 @@ and the package uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-24
+
+### Added
+
+- Opt-in local provider HAR diagnostics with Settings, MCP and CLI controls, concurrent book attribution and retention limits.
+  Captured SDK calls are named by their apicity catalog dot path, such as
+  `api.v1.jobs.createTask`, so `apicity har report` attributes them to their
+  endpoints.
+- The Request payload panel of a queued, generating or failed cell downloads
+  the attempt's scrubbed captures as one HAR file, or shows "Capture off" with
+  a link to Settings. `inspect_generation_request` reports whether an asset has
+  a capture, with its path and outcome; the new `get_generation_har` tool
+  returns the HAR for an asset or attempt id.
+- `videobook har list` and `videobook har export --out <dir|file.tar.gz>`,
+  both with `--since`, `--failures` and `--provider`. Export re-runs the
+  `@apicity/har` scrubber on every capture and refuses, naming the file, when
+  scrubbing would change it. Otherwise it writes the captures with an index
+  and a manifest and prints the `apicity har report` hand-off.
+
+### Changed
+
+- Upgrade all Apicity dependencies to 0.18.0.
+
+## [0.2.5] - 2026-10-24
+
+### Added
+
+- Thirteen fal video endpoints: Kling 4 text, frame, reference and editing;
+  HeyGen Video text, image and reference generation; HeyGen Avatar 3/4/5
+  stock digital twins, Avatar 4 image animation, and Video Agent v2/v3.
+- HeyGen Video text and reference models appear in the ranked pickers.
+  Kling 4 appears in the unranked group. Digital twins accept spoken scripts
+  with stock avatar and voice defaults; Avatar 4 image animation defaults to Ivy.
+
+### Changed
+
+- Upgrade all Apicity packages to 0.17.1 and refresh generated model documentation.
+
 ## [0.2.4] - 2026-10-23
 
 ### Added

package/README.md

@@ -65,6 +65,9 @@ videobook gc-books             # reclaim catalog storage in every book
 videobook doctor               # check Node, binaries, native modules and keys
 videobook config               # show where each provider key comes from
 videobook config set FAL_API_KEY op://Private/FAL_API_KEY/password
+videobook config set har_capture failures   # opt in to provider HAR capture
+videobook har list --failures  # captured provider calls, newest first
+videobook har export --out captures.tar.gz  # scrub-checked captures for apicity
 videobook setup 1password --op-vault Private
 videobook --version
 ```
@@ -104,10 +107,11 @@ run while a server owns the library.
 Installed data lives in `~/.videobook`:
 
 - `books/`, the library of books
-- `app-state.json`, connected X and Dropbox accounts
+- `app-state.json`, connected X and Dropbox accounts and the HAR capture setting
 - `.env`, provider keys, also editable from Settings in the web UI
+- `har/`, opt-in provider HAR captures (off by default) with an `index.jsonl`
 
-`VIDEOBOOK_HOME` or `--home` moves all three. `VIDEOBOOK_LIBRARY_DIR`,
+`VIDEOBOOK_HOME` or `--home` moves all four. `VIDEOBOOK_LIBRARY_DIR`,
 `VIDEOBOOK_APP_STATE_PATH` and `VIDEOBOOK_ENV_PATH` move one each; `--home`
 overrides any of them inherited from your shell. Set `VIDEOBOOK_HOME` and
 `VIDEOBOOK_ENV_PATH` in the environment, not in `.env`, because they decide

package/dist/archive-b2.js

@@ -1,4 +1,4 @@
-import { createB2 } from "@apicity/b2";
+import { createB2 } from "./usage-providers.js";
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { open, readFile, stat } from "node:fs/promises";

package/dist/cli/args.js

@@ -7,9 +7,10 @@ export class CliUsageError extends Error {
     }
 }
 const LOG_LEVELS = new Set(["silent", "error", "warn", "info", "debug"]);
-const COMMANDS = new Set(["serve", "mcp", "run", "tools", "gc-books", "doctor", "setup", "config", "version", "help"]);
+const COMMANDS = new Set(["serve", "mcp", "run", "tools", "gc-books", "doctor", "setup", "config", "har", "version", "help"]);
 const CONFIG_ACTIONS = new Set(["list", "get", "set", "unset"]);
-const POSITIONAL_COMMANDS = new Set(["run", "setup", "config"]);
+const HAR_ACTIONS = new Set(["list", "export"]);
+const POSITIONAL_COMMANDS = new Set(["run", "setup", "config", "har"]);
 const DEFAULT_RUN_TIMEOUT_SECONDS = 600;
 const GLOBAL_OPTIONS = {
     port: { type: "string" },
@@ -28,6 +29,7 @@ const COMMAND_OPTIONS = {
     doctor: { json: { type: "boolean" } },
     setup: { "op-vault": { type: "string" }, "op-token": { type: "string" }, "no-verify": { type: "boolean" }, remove: { type: "boolean" } },
     config: { json: { type: "boolean" } },
+    har: { out: { type: "string" }, since: { type: "string" }, failures: { type: "boolean" }, provider: { type: "string" }, json: { type: "boolean" } },
 };
 function splitCommand(argv) {
     const [first, ...rest] = argv;
@@ -147,6 +149,35 @@ function buildConfig(values, positionals, flags) {
         flags: { ...flags, json: values.json === true },
     };
 }
+function buildHar(values, positionals, flags) {
+    const [action, ...extra] = positionals;
+    if (!action || !HAR_ACTIONS.has(action) || extra.length > 0) {
+        throw new CliUsageError("Usage: videobook har list [--since <date>] [--failures] [--provider <p>] [--json] | har export --out <dir|file.tar.gz> [--since <date>] [--failures] [--provider <p>]");
+    }
+    const out = stringValue(values.out);
+    if (action === "export" && out === undefined)
+        throw new CliUsageError("har export needs --out <dir|file.tar.gz>");
+    if (action === "list" && out !== undefined)
+        throw new CliUsageError("--out applies to har export only");
+    const since = stringValue(values.since);
+    if (since !== undefined && !Number.isFinite(Date.parse(since)))
+        throw new CliUsageError(`--since needs an ISO date or time, got "${since}".`);
+    const providers = typeof values.provider === "string"
+        ? values.provider.split(",").map((provider) => provider.trim()).filter(Boolean)
+        : [];
+    return {
+        command: "har",
+        action: action,
+        flags: {
+            ...flags,
+            ...(out === undefined ? {} : { out }),
+            ...(since === undefined ? {} : { since }),
+            failures: values.failures === true,
+            providers,
+            json: values.json === true,
+        },
+    };
+}
 function buildCommand(command, values, positionals) {
     const flags = globalFlags(values);
     switch (command) {
@@ -164,6 +195,8 @@ function buildCommand(command, values, positionals) {
             return buildSetup(values, positionals, flags);
         case "config":
             return buildConfig(values, positionals, flags);
+        case "har":
+            return buildHar(values, positionals, flags);
         default:
             return { command, flags };
     }
@@ -215,6 +248,8 @@ export function helpText() {
         "  gc-books           Reclaim catalog storage in every book",
         "  doctor             Check Node, media binaries, native modules and keys",
         "  config [action]    list | get <KEY> | set <KEY> <VALUE> | unset <KEY> in the data-home .env",
+        "  har list           List provider HAR captures, newest first",
+        "  har export         Copy scrub-checked captures and a manifest to share with apicity (--out)",
         "  setup 1password    Read keys from a 1Password vault (--op-vault, --op-token)",
         "  version            Print versions",
         "  help               Print this help",
@@ -228,7 +263,11 @@ export function helpText() {
         "  --open             serve: open the web UI in a browser",
         "  --no-wait          run: do not wait for queued jobs",
         "  --timeout <s>      run: seconds to wait for jobs (default 600)",
-        "  --json             doctor, config: print machine-readable results",
+        "  --json             doctor, config, har: print machine-readable results",
+        "  --out <path>       har export: a new directory, or a .tar.gz/.tgz file",
+        "  --since <date>     har: only calls at or after this ISO date or time",
+        "  --failures         har: only failed calls",
+        "  --provider <p>     har: only these providers, comma separated",
         "  --op-vault <name>  setup 1password: vault whose items are named after the keys",
         "  --op-token <tok>   setup 1password: service-account token, best as env:VAR",
         "  --no-verify        setup 1password: skip the op item list check",

package/dist/cli/config-command.js

@@ -1,3 +1,4 @@
+import { readHarSettings, writeHarSettings, harDirectory } from "../har-settings.js";
 import { hasControlCharacters, readEnvValues, updateEnvFile } from "../env-file.js";
 import { MANAGED_ENV_KEYS, getDefaultSecretStore, isSecretEnvKey, maskEnvValue, } from "../env-secrets.js";
 import { OP_TOKEN_SETTING, OP_VAULT_SETTING, isOpReference, vaultReference } from "../one-password.js";
@@ -83,10 +84,25 @@ async function unsetKey(key, envPath) {
     return 0;
 }
 export async function runConfigCommand(command) {
+    if (command.key === "har_capture") {
+        try {
+            const current = await readHarSettings();
+            const settings = command.action === "set" || command.action === "unset"
+                ? await writeHarSettings({ ...await readHarSettings(undefined, {}), mode: command.action === "unset" ? "off" : command.value })
+                : current;
+            process.stdout.write(`${JSON.stringify({ harCapture: settings, dir: harDirectory(), overridden: Boolean(process.env.VIDEOBOOK_HAR_CAPTURE?.trim()) })}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
     const envPath = getDefaultSecretStore().envPath();
     if (command.action === "list") {
         const file = readEnvValues(envPath);
-        printRows(CONFIG_KEYS.map((key) => configRow(key, file)), file, command.flags.json, envPath);
+        const har = await readHarSettings();
+        printRows([...CONFIG_KEYS.map((key) => configRow(key, file)), { key: "har_capture", source: process.env.VIDEOBOOK_HAR_CAPTURE?.trim() ? "environment" : "app state", value: har.mode }], file, command.flags.json, envPath);
         return 0;
     }
     const key = command.key ?? "";

package/dist/cli/doctor-command.js

@@ -1,3 +1,4 @@
+import { harDirectory, readHarSettings } from "../har-settings.js";
 import { execFile } from "node:child_process";
 import { access, constants, readdir } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -72,6 +73,19 @@ async function dataHomeCheck() {
         });
     }
 }
+async function harCaptureCheck() {
+    const settings = await readHarSettings();
+    const dir = harDirectory();
+    let writable = true;
+    try {
+        await access(await nearestExisting(dir), constants.W_OK);
+    }
+    catch {
+        writable = false;
+    }
+    return check({ id: "har-capture", label: "HAR capture", status: writable || settings.mode === "off" ? "ok" : "warn",
+        detail: `${settings.mode}; ${dir}; writable: ${writable ? "yes" : "no"}`, required: false });
+}
 async function libraryCheck() {
     const libraryDir = bookManager.rootDir;
     try {
@@ -255,6 +269,7 @@ async function collectDoctorChecks() {
     return [
         nodeCheck(),
         await dataHomeCheck(),
+        await harCaptureCheck(),
         await libraryCheck(),
         await binaryCheck("ffmpeg", "ffmpeg", FFMPEG, bundledPath("ffmpeg-static"), "VIDEOBOOK_FFMPEG_PATH"),
         await binaryCheck("ffprobe", "ffprobe", FFPROBE, bundledFfprobe(), "VIDEOBOOK_FFPROBE_PATH"),

package/dist/cli/har-command.js

@@ -0,0 +1,86 @@
+import { dirname, resolve } from "node:path";
+import { exportHarCaptures, selectHarRows } from "../har-export.js";
+import { readHarIndex } from "../har-index.js";
+import { harDirectory } from "../har-settings.js";
+const LISTED_SKIPS = 10;
+function selection(flags) {
+    return {
+        since: flags.since === undefined ? null : Date.parse(flags.since),
+        failures: flags.failures,
+        providers: flags.providers,
+    };
+}
+async function listCaptures(flags) {
+    const dir = harDirectory();
+    const rows = selectHarRows(await readHarIndex(dir), selection(flags)).sort((a, b) => b.ts.localeCompare(a.ts));
+    if (flags.json) {
+        process.stdout.write(`${JSON.stringify({ dir, captures: rows }, null, 2)}\n`);
+        return 0;
+    }
+    const lines = rows.map((row) => [row.ts, row.provider, row.endpoint, row.outcome, row.status ?? "-", row.file].join("\t"));
+    process.stdout.write(`${["ts\tprovider\tendpoint\toutcome\tstatus\tfile", ...lines].join("\n")}\n`);
+    if (rows.length === 0)
+        process.stderr.write(`No matching captures in ${dir}\n`);
+    return 0;
+}
+function outcomeSummary(outcomes) {
+    return Object.entries(outcomes).filter(([, count]) => count > 0).map(([outcome, count]) => `${outcome} ${count}`).join(", ");
+}
+function shellPath(path) {
+    return /^[\w./:@%+=,-]+$/u.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`;
+}
+function handoff(out, archive, manifest) {
+    const target = shellPath(archive ? out.replace(/\.(?:tar\.gz|tgz)$/iu, "") : out);
+    return [
+        `Exported ${manifest.files} capture${manifest.files === 1 ? "" : "s"} (${manifest.dateRange.first} to ${manifest.dateRange.last}) to ${out}`,
+        ...manifest.providers.map((provider) => `  ${provider.provider}: ${provider.calls} (${outcomeSummary(provider.outcomes)})`),
+        `Every file passed the @apicity/har ${manifest.apicity.har} scrub check. The captures still contain prompts and media URLs; review them before sharing.`,
+        "",
+        "Hand-off to an apicity maintainer:",
+        ...(archive ? [`  tar -xzf ${shellPath(out)} -C ${shellPath(dirname(out))}`] : []),
+        `  apicity har report ${target} > report.md`,
+        "  apicity har scrub --check <capture.har>",
+        "  pnpm run har:promote -- <capture.har> --name <provider>/<test-name> --dry-run   (in the apicity repository, for a successful call)",
+        "",
+    ].join("\n");
+}
+function skippedWarning(skipped) {
+    if (skipped.length === 0)
+        return "";
+    const listed = skipped.slice(0, LISTED_SKIPS).map((file) => `  ${file}\n`).join("");
+    const more = skipped.length > LISTED_SKIPS ? `  and ${skipped.length - LISTED_SKIPS} more\n` : "";
+    return `Skipped ${skipped.length} indexed capture${skipped.length === 1 ? "" : "s"} that are missing or unreadable:\n${listed}${more}`;
+}
+async function exportCaptures(flags) {
+    const dir = harDirectory();
+    const out = resolve(process.cwd(), flags.out ?? "");
+    const result = await exportHarCaptures({ dir, out, ...selection(flags) });
+    switch (result.status) {
+        case "out-inside-captures":
+            process.stderr.write(`--out must be outside the capture directory ${dir}\n`);
+            return 2;
+        case "out-exists":
+            process.stderr.write(`${out} already exists; choose a new file or an empty directory\n`);
+            return 1;
+        case "needs-scrub":
+            process.stderr.write([
+                "Refusing to export: @apicity/har scrubHar would change these captures:",
+                ...result.files.map((file) => `  ${file}`),
+                "A scrub rule is missing upstream. Report it to apicity instead of editing the captures. Nothing was written.",
+                "",
+            ].join("\n"));
+            return 1;
+        case "empty":
+            process.stderr.write(`${skippedWarning(result.skipped)}No captures in ${dir} match the filters. Nothing was written.\n`);
+            return 1;
+        case "exported":
+            process.stderr.write(skippedWarning(result.skipped));
+            process.stdout.write(flags.json
+                ? `${JSON.stringify({ out: result.out, archive: result.archive, manifest: result.manifest, skipped: result.skipped }, null, 2)}\n`
+                : handoff(result.out, result.archive, result.manifest));
+            return 0;
+    }
+}
+export async function runHarCommand(command) {
+    return command.action === "export" ? exportCaptures(command.flags) : listCaptures(command.flags);
+}

package/dist/cli/main.js

@@ -54,6 +54,10 @@ async function runCommand(parsed) {
             const { runConfigCommand } = await import("./config-command.js");
             return runConfigCommand(parsed);
         }
+        case "har": {
+            const { runHarCommand } = await import("./har-command.js");
+            return runHarCommand(parsed);
+        }
     }
 }
 async function loadDotenv() {
@@ -77,7 +81,15 @@ async function main(argv) {
         redirectConsoleToStderr();
     if (parsed.command !== "setup" && parsed.command !== "config")
         await loadDotenv();
-    return runCommand(parsed);
+    try {
+        return await runCommand(parsed);
+    }
+    finally {
+        if (parsed.command === "run" || parsed.command === "mcp") {
+            const { flushHarCaptures } = await import("../har-capture.js");
+            await flushHarCaptures();
+        }
+    }
 }
 function flushed(stream) {
     return new Promise((resolveFlush) => stream.write("", () => resolveFlush()));

package/dist/command-reference.js

@@ -90,10 +90,14 @@ export function renderGenerationModels() {
 
 Generated by \`npm run docs:commands\` from the media catalog (\`server/src/media/catalog.ts\`). Call \`generate_image\`, \`generate_video\` or \`generate_audio\` with one of these model ids; \`list_generation_models\` returns the same list with every option, enum, range and default read from the apicity schemas.
 
-Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.17.0, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
+Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.17.1, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
 
 Configured frontier models appear first; other models retain their existing order in a separate group. Providers without credentials are marked unavailable. Saved selections and defaults stay unchanged. Catalog variants on a frontier board are included even if previously hidden; non-frontier hidden variants remain hidden. A model version or lite variant never inherits another endpoint's score.
 
+Kling 4 supports text, frames, references and video editing; it appears in the unranked group. Multi-shot requests use the sum of shot durations for billing. HeyGen Video text-to-video and reference-to-video use their exact frontier rankings; image-to-video remains unranked. HeyGen Video endpoint IDs start with \`fal:heygen/heygen-video/\`.
+
+HeyGen Avatar 3 and 4 digital twins are text-to-video with a stock avatar (Abigail Office Front) and voice (Ivy); the prompt is the spoken script. Avatar 5 uses the SDK defaults Abigail Sofa Front and Warm Pro Narrator. Avatar 4 image-to-video animates an image with the script and defaults to Ivy. Connected audio overrides speech synthesis. Video Agent v2 and v3 accept a production prompt. HeyGen lipsync, translation, filler-word removal, HeyGen Voice TTS and Ideogram vector endpoints are outside this catalog addition.
+
 Top-10 coverage policy: every registry endpoint must map exactly to a catalog entry or appear in the known gaps below. Models with no provider endpoint in the registry: ${unmapped.join(", ")}. Catalog gaps do not imply provider API support is missing; adding those endpoints is separate work.
 
 | Known endpoint gap | Reason |

package/dist/content-store.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { B2Error, createB2 } from "@apicity/b2";
+import { createB2 } from "./usage-providers.js";
+import { B2Error } from "@apicity/b2";
 function createB2ContentStore(config) {
     const provider = createB2({
         accessKeyId: config.accessKeyId,

package/dist/diagnostics.js

@@ -4,7 +4,7 @@ const EVENTS = [
     "book-open", "book-open-slow", "book-catalog-gc", "provider-poll-failed",
     "ace-server-exited", "scheduled-post-failed", "scheduled-post-rearm-failed",
     "generation-record-failed", "generation-update-failed", "generation-list-failed",
-    "provider-task-record-failed",
+    "provider-task-record-failed", "har-capture-failed",
     "prompt-record-failed",
     "waveform-empty", "waveform-failed", "heartbeat-failed", "subtitle-cache-failed",
     "subtitle-translation-failed", "overlay-skipped", "kie-upload-fallback",

package/dist/env-secrets.js

@@ -48,6 +48,7 @@ export const MANAGED_ENV_KEYS = [
     "B2_ARCHIVE_PREFIX",
 ];
 const NON_SECRET_ENV_KEYS = new Set([
+    "VIDEOBOOK_HAR_CAPTURE",
     "B2_REGION",
     "B2_BUCKET",
     "B2_ENDPOINT",

package/dist/generation-har.js

@@ -0,0 +1,106 @@
+import { scrubHar } from "@apicity/har";
+import { captureFileExists, captureFilePath, readCaptureFile, readHarIndex } from "./har-index.js";
+import { harDirectory } from "./har-settings.js";
+import { readProviderTaskRecord } from "./provider-task-record.js";
+function bookIdOf(engine) {
+    try {
+        return engine.book.get().bookId;
+    }
+    catch {
+        return null;
+    }
+}
+export async function captureKeys(engine, ids) {
+    const known = new Set([...ids].filter((id) => typeof id === "string" && id.length > 0));
+    const taskIds = new Set();
+    for (const id of known) {
+        const task = await readProviderTaskRecord(engine, id).catch(() => null);
+        if (task && task.taskId !== "queued")
+            taskIds.add(task.taskId);
+    }
+    return { bookId: bookIdOf(engine), ids: known, taskIds };
+}
+export async function generationCaptureKeys(engine, generationId) {
+    let generation = null;
+    try {
+        generation = engine.generations.read(generationId);
+    }
+    catch {
+        generation = null;
+    }
+    const row = generation?.ok ? generation.value : null;
+    return captureKeys(engine, [generationId, row?.providerArtifactId, row?.outputArtifactId]);
+}
+function matchesCapture(row, keys) {
+    const context = row.context ?? {};
+    if (keys.bookId && typeof context.bookId === "string" && context.bookId !== keys.bookId)
+        return false;
+    return [context.artifactId, context.attemptId].some((id) => typeof id === "string" && keys.ids.has(id))
+        || (typeof context.providerTaskId === "string" && keys.taskIds.has(context.providerTaskId));
+}
+function chronological(a, b) {
+    return a.ts.localeCompare(b.ts) || a.callId.localeCompare(b.callId);
+}
+async function attemptCaptureRows(keys, rows, dir = harDirectory()) {
+    const matched = (rows ?? await readHarIndex(dir)).filter((row) => matchesCapture(row, keys)).sort(chronological);
+    const present = await Promise.all(matched.map((row) => captureFileExists(dir, row.file)));
+    return matched.filter((_row, index) => present[index]);
+}
+export async function generationHarStatus(keys, mode, rows, dir = harDirectory()) {
+    const captures = await attemptCaptureRows(keys, rows, dir);
+    const primary = [...captures].reverse().find((row) => row.outcome !== "ok") ?? captures.at(-1);
+    return {
+        mode,
+        hasCapture: captures.length > 0,
+        captures: captures.length,
+        path: primary ? captureFilePath(dir, primary.file) : null,
+        outcome: primary?.outcome ?? null,
+    };
+}
+function combineCaptures(captures, generationId) {
+    const [first] = captures;
+    if (!first || captures.length === 1)
+        return first?.har ?? null;
+    const pages = captures.map(({ row, har }) => ({
+        startedDateTime: har.log._apicity?.startedAt ?? row.ts,
+        id: har.log._apicity?.callId ?? row.callId,
+        title: `${row.provider} ${row.endpoint} (${row.outcome})`,
+        pageTimings: {},
+        ...(har.log._apicity ? { _apicity: har.log._apicity } : {}),
+    }));
+    return {
+        log: {
+            version: "1.2",
+            creator: first.har.log.creator,
+            comment: `videobook generation ${generationId}: ${captures.length} captured apicity calls, one page each`,
+            pages,
+            entries: captures.flatMap(({ row, har }) => har.log.entries.map((entry) => ({
+                ...entry,
+                pageref: har.log._apicity?.callId ?? row.callId,
+            }))),
+        },
+    };
+}
+export async function generationHar(keys, generationId, dir = harDirectory()) {
+    const loaded = [];
+    for (const row of await attemptCaptureRows(keys, undefined, dir)) {
+        const capture = await readCaptureFile(dir, row.file);
+        if (capture)
+            loaded.push({ row, path: capture.path, har: scrubHar(capture.har) });
+    }
+    const har = combineCaptures(loaded, generationId);
+    if (!har)
+        return null;
+    return {
+        captures: loaded.map(({ row, path }) => ({
+            path,
+            ts: row.ts,
+            callId: row.callId,
+            provider: row.provider,
+            endpoint: row.endpoint,
+            outcome: row.outcome,
+            status: row.status ?? null,
+        })),
+        har,
+    };
+}

package/dist/har-capture.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHarCapture } from "@apicity/har";
+import { currentBookContext } from "./book-context.js";
+import { harDirectory, readHarSettings } from "./har-settings.js";
+import { logger } from "./logger.js";
+const pending = new Set();
+let maintenance = Promise.resolve();
+export async function maintainHarCaptures(operation) {
+    if (pending.size)
+        return false;
+    const next = maintenance.then(operation);
+    maintenance = next.catch(() => undefined);
+    await next;
+    return true;
+}
+export async function flushHarCaptures() {
+    while (pending.size)
+        await Promise.all([...pending]);
+}
+function captureInput(value, seen = new WeakSet()) {
+    if (value instanceof Blob)
+        return { _file: { size: value.size, contentType: value.type } };
+    if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+        const bytes = value instanceof ArrayBuffer ? new Uint8Array(value) : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return { _apicity_placeholder: { bytes: bytes.byteLength, sha256: createHash("sha256").update(bytes).digest("hex") } };
+    }
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (value instanceof FormData)
+        return Object.fromEntries(Array.from(value.entries(), ([key, entry]) => [key, captureInput(entry, seen)]));
+    if (Array.isArray(value))
+        return value.map((entry) => captureInput(entry, seen));
+    if (Object.getPrototypeOf(value) !== Object.prototype)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, key === "otp" ? "***" : captureInput(entry, seen)]));
+}
+export async function withHarCapture(meta, operation, base = globalThis.fetch, context = {}) {
+    for (;;) {
+        const barrier = maintenance;
+        await barrier;
+        if (barrier === maintenance)
+            break;
+    }
+    let finish;
+    const finished = new Promise((resolve) => { finish = resolve; });
+    pending.add(finished);
+    try {
+        return await runCapture(meta, operation, base, context);
+    }
+    finally {
+        finish();
+        pending.delete(finished);
+    }
+}
+async function runCapture(meta, operation, base, context) {
+    const settings = await readHarSettings();
+    if (settings.mode === "off")
+        return operation(base);
+    let input;
+    try {
+        input = captureInput(meta.input);
+    }
+    catch (error) {
+        logger.warn("har-capture-failed", { error });
+        return operation(base);
+    }
+    const book = currentBookContext();
+    const capture = createHarCapture({
+        dir: harDirectory(),
+        mode: settings.mode,
+        context: {
+            bookId: book?.bookId,
+            operation: book?.operation,
+            artifactId: book?.artifactId,
+            attemptId: book?.attemptId ?? book?.artifactId,
+            providerTaskId: book?.providerTaskId,
+            runId: book?.runId,
+            model: book?.model,
+            ...context,
+        },
+        onError: (error) => logger.warn("har-capture-failed", { error }),
+    });
+    const host = { fetch: base };
+    capture.install(host);
+    let finish;
+    const finished = new Promise((resolve) => { finish = resolve; });
+    const done = finished.then(() => capture.close());
+    pending.add(done);
+    void done.finally(() => pending.delete(done));
+    try {
+        return await capture.call({ ...meta, input }, () => operation(host.fetch));
+    }
+    finally {
+        finish();
+    }
+}
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
+function endpointDotPath(path) {
+    return (path.length > 1 && HTTP_METHODS.has(path[0] ?? "") ? path.slice(1) : path).join(".");
+}
+const providerCalls = new WeakMap();
+export function withProviderCall(provider, meta, operation) {
+    const state = providerCalls.get(provider);
+    if (!state)
+        return operation(provider);
+    return withHarCapture(meta, (fetch) => state.transports.run(fetch, () => operation(state.original)), state.base);
+}
+export function capturedProvider(provider, factory, base = globalThis.fetch) {
+    const transports = new AsyncLocalStorage();
+    const original = factory((input, init) => {
+        const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        signal?.throwIfAborted();
+        return (transports.getStore() ?? base)(input, init);
+    });
+    function wrap(target, path) {
+        return new Proxy(target, {
+            apply(fn, receiver, args) {
+                return withHarCapture({ provider, endpoint: endpointDotPath(path), input: args.length === 1 ? args[0] : args }, (fetch) => transports.run(fetch, () => Reflect.apply(fn, receiver, args)), base);
+            },
+            get(object, property, receiver) {
+                const value = Reflect.get(object, property, receiver);
+                if (typeof target === "function" && ["bind", "call", "apply"].includes(String(property)) && typeof value === "function")
+                    return value.bind(receiver);
+                if (typeof property !== "string" || ["presign", "schema", "example", "examples"].includes(property))
+                    return value;
+                const next = [...path, property];
+                if (typeof value === "function")
+                    return wrap(value, next);
+                if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype)
+                    return wrap(value, next);
+                return value;
+            },
+        });
+    }
+    const providerClient = wrap(original, []);
+    providerCalls.set(providerClient, { original, base, transports });
+    return providerClient;
+}