@echofiles/echo-pdf 0.4.1 → 0.4.2

package/README.md

@@ -13,6 +13,80 @@
 - CLI
 - HTTP API
 
+## Using echo-pdf as a library
+
+`@echofiles/echo-pdf` 支持直接作为库导入，面向下游复用 `pdf_extract_pages / pdf_ocr_pages / pdf_tables_to_latex / file_ops` 工具实现。
+
+### Public entrypoints（semver 稳定）
+
+- `@echofiles/echo-pdf`：core API（推荐）
+- `@echofiles/echo-pdf/core`：与根入口等价的 core API
+- `@echofiles/echo-pdf/worker`：Worker 路由入口（给 Wrangler/Worker 集成用）
+
+仅以上 `exports` 子路径视为公开 API。`src/*`、`dist/*` 等深路径导入不受兼容性承诺保护，可能在次版本中变动。
+
+### Runtime expectations
+
+- Node.js: `>=20`（与 `package.json#engines` 一致）
+- 需要 ESM `import` 能力与标准 `fetch`（Node 20+ 原生支持）
+- 建议使用支持 package `exports` 的现代 bundler/runtime（Vite、Webpack 5、Rspack、esbuild、Wrangler 等）
+- TypeScript 消费方建议：`module=NodeNext` + `moduleResolution=NodeNext`
+
+### Clean project import smoke
+
+下面这段命令与仓库中的集成测试保持一致，可在全新目录验证 npm 包“可直接 import”：
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+npm init -y
+npm i /path/to/echofiles-echo-pdf-<version>.tgz
+node --input-type=module -e "await import('@echofiles/echo-pdf'); await import('@echofiles/echo-pdf/core'); await import('@echofiles/echo-pdf/worker'); console.log('ok')"
+```
+
+### Example
+
+```ts
+import { callTool, listToolSchemas } from "@echofiles/echo-pdf"
+import configJson from "./echo-pdf.config.json" with { type: "json" }
+
+const fileStore = {
+  async put(input) {
+    const id = crypto.randomUUID()
+    const record = { ...input, id, sizeBytes: input.bytes.byteLength, createdAt: new Date().toISOString() }
+    memory.set(id, record)
+    return record
+  },
+  async get(id) {
+    return memory.get(id) ?? null
+  },
+  async list() {
+    return [...memory.values()]
+  },
+  async delete(id) {
+    return memory.delete(id)
+  },
+}
+
+const memory = new Map()
+const env = {}
+
+console.log(listToolSchemas().map((tool) => tool.name))
+
+const result = await callTool(
+  "pdf_extract_pages",
+  { fileId: "<FILE_ID>", pages: [1], returnMode: "inline" },
+  { config: configJson, env, fileStore }
+)
+console.log(result)
+```
+
+版本策略：
+
+- `exports` 列出的入口及其导出符号按 semver 管理
+- 对公开 API 的破坏性变更只会在 major 版本发布
+- 新增导出、参数扩展（向后兼容）会在 minor/patch 发布
+
 ## 1. 服务地址
 
 请先确定你的线上地址（Worker 域名）。文档里用：
@@ -287,6 +361,7 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 鉴权注意：
 
 - 如果配置了 `authHeader/authEnv` 但未注入对应 secret，服务会返回配置错误（fail-closed），不会默认放行。
+- 仅开发调试场景可显式设置 `ECHO_PDF_ALLOW_MISSING_AUTH_SECRET=1` 临时放行“缺 secret”的请求。
 
 ## 7. 本地开发与测试
 

package/dist/agent-defaults.d.ts

@@ -0,0 +1,3 @@
+import type { EchoPdfConfig } from "./pdf-types.js";
+export declare const resolveProviderAlias: (config: EchoPdfConfig, requestedProvider?: string) => string;
+export declare const resolveModelForProvider: (config: EchoPdfConfig, _providerAlias: string, requestedModel?: string) => string;

package/dist/agent-defaults.js

@@ -0,0 +1,18 @@
+const normalize = (value) => value.trim();
+export const resolveProviderAlias = (config, requestedProvider) => {
+    const raw = normalize(requestedProvider ?? "");
+    if (raw.length === 0)
+        return config.agent.defaultProvider;
+    if (config.providers[raw])
+        return raw;
+    const fromType = Object.entries(config.providers).find(([, provider]) => provider.type === raw)?.[0];
+    if (fromType)
+        return fromType;
+    throw new Error(`Provider "${raw}" not configured`);
+};
+export const resolveModelForProvider = (config, _providerAlias, requestedModel) => {
+    const explicit = normalize(requestedModel ?? "");
+    if (explicit.length > 0)
+        return explicit;
+    return normalize(config.agent.defaultModel ?? "");
+};

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+import type { Env } from "./types.js";
+export interface AuthCheckOptions {
+    readonly authHeader?: string;
+    readonly authEnv?: string;
+    readonly allowMissingSecret?: boolean;
+    readonly misconfiguredCode: string;
+    readonly unauthorizedCode: string;
+    readonly contextName: string;
+}
+export type AuthCheckResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+};
+export declare const checkHeaderAuth: (request: Request, env: Env, options: AuthCheckOptions) => AuthCheckResult;

package/dist/auth.js

@@ -0,0 +1,24 @@
+export const checkHeaderAuth = (request, env, options) => {
+    if (!options.authHeader || !options.authEnv)
+        return { ok: true };
+    const required = env[options.authEnv];
+    if (typeof required !== "string" || required.length === 0) {
+        if (options.allowMissingSecret === true)
+            return { ok: true };
+        return {
+            ok: false,
+            status: 500,
+            code: options.misconfiguredCode,
+            message: `${options.contextName} auth is configured but env "${options.authEnv}" is missing`,
+        };
+    }
+    if (request.headers.get(options.authHeader) !== required) {
+        return {
+            ok: false,
+            status: 401,
+            code: options.unauthorizedCode,
+            message: "Unauthorized",
+        };
+    }
+    return { ok: true };
+};

package/dist/core/index.d.ts

@@ -0,0 +1,50 @@
+export { callTool, listToolSchemas } from "../tool-registry.js";
+export type { ToolRuntimeContext } from "../tool-registry.js";
+export type { ToolSchema } from "../pdf-types.js";
+export type { Env, FileStore, JsonObject } from "../types.js";
+import type { ReturnMode } from "../types.js";
+export interface PdfExtractPagesArgs {
+    readonly fileId?: string;
+    readonly url?: string;
+    readonly base64?: string;
+    readonly filename?: string;
+    readonly pages: ReadonlyArray<number>;
+    readonly renderScale?: number;
+    readonly returnMode?: ReturnMode;
+}
+export interface PdfOcrPagesArgs {
+    readonly fileId?: string;
+    readonly url?: string;
+    readonly base64?: string;
+    readonly filename?: string;
+    readonly pages: ReadonlyArray<number>;
+    readonly renderScale?: number;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly prompt?: string;
+}
+export interface PdfTablesToLatexArgs {
+    readonly fileId?: string;
+    readonly url?: string;
+    readonly base64?: string;
+    readonly filename?: string;
+    readonly pages: ReadonlyArray<number>;
+    readonly renderScale?: number;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly prompt?: string;
+}
+export interface FileOpsArgs {
+    readonly op: "list" | "read" | "delete" | "put";
+    readonly fileId?: string;
+    readonly includeBase64?: boolean;
+    readonly text?: string;
+    readonly filename?: string;
+    readonly mimeType?: string;
+    readonly base64?: string;
+    readonly returnMode?: ReturnMode;
+}
+export declare const pdf_extract_pages: (args: PdfExtractPagesArgs, ctx: import("../tool-registry.js").ToolRuntimeContext) => Promise<unknown>;
+export declare const pdf_ocr_pages: (args: PdfOcrPagesArgs, ctx: import("../tool-registry.js").ToolRuntimeContext) => Promise<unknown>;
+export declare const pdf_tables_to_latex: (args: PdfTablesToLatexArgs, ctx: import("../tool-registry.js").ToolRuntimeContext) => Promise<unknown>;
+export declare const file_ops: (args: FileOpsArgs, ctx: import("../tool-registry.js").ToolRuntimeContext) => Promise<unknown>;

package/dist/core/index.js

@@ -0,0 +1,7 @@
+export { callTool, listToolSchemas } from "../tool-registry.js";
+import { callTool } from "../tool-registry.js";
+const asJsonObject = (value) => value;
+export const pdf_extract_pages = async (args, ctx) => callTool("pdf_extract_pages", asJsonObject(args), ctx);
+export const pdf_ocr_pages = async (args, ctx) => callTool("pdf_ocr_pages", asJsonObject(args), ctx);
+export const pdf_tables_to_latex = async (args, ctx) => callTool("pdf_tables_to_latex", asJsonObject(args), ctx);
+export const file_ops = async (args, ctx) => callTool("file_ops", asJsonObject(args), ctx);

package/dist/file-ops.d.ts

@@ -0,0 +1,11 @@
+import type { FileStore, ReturnMode } from "./types.js";
+export declare const runFileOp: (fileStore: FileStore, input: {
+    readonly op: "list" | "read" | "delete" | "put";
+    readonly fileId?: string;
+    readonly includeBase64?: boolean;
+    readonly text?: string;
+    readonly filename?: string;
+    readonly mimeType?: string;
+    readonly base64?: string;
+    readonly returnMode?: ReturnMode;
+}) => Promise<unknown>;

package/dist/file-ops.js

@@ -0,0 +1,36 @@
+import { fromBase64, normalizeReturnMode, toInlineFilePayload } from "./file-utils.js";
+export const runFileOp = async (fileStore, input) => {
+    if (input.op === "list") {
+        return { files: await fileStore.list() };
+    }
+    if (input.op === "put") {
+        const bytes = input.base64 ? fromBase64(input.base64) : new TextEncoder().encode(input.text ?? "");
+        const meta = await fileStore.put({
+            filename: input.filename ?? `file-${Date.now()}.txt`,
+            mimeType: input.mimeType ?? "text/plain; charset=utf-8",
+            bytes,
+        });
+        const returnMode = normalizeReturnMode(input.returnMode);
+        if (returnMode === "file_id")
+            return { returnMode, file: meta };
+        if (returnMode === "url")
+            return { returnMode, file: meta, url: `/api/files/get?fileId=${encodeURIComponent(meta.id)}` };
+        const stored = await fileStore.get(meta.id);
+        if (!stored)
+            throw new Error(`File not found after put: ${meta.id}`);
+        return {
+            returnMode,
+            ...toInlineFilePayload(stored, true),
+        };
+    }
+    if (!input.fileId) {
+        throw new Error("fileId is required");
+    }
+    if (input.op === "delete") {
+        return { deleted: await fileStore.delete(input.fileId), fileId: input.fileId };
+    }
+    const file = await fileStore.get(input.fileId);
+    if (!file)
+        throw new Error(`File not found: ${input.fileId}`);
+    return toInlineFilePayload(file, Boolean(input.includeBase64));
+};

package/dist/file-store-do.d.ts

@@ -0,0 +1,36 @@
+import type { StoragePolicy } from "./pdf-types.js";
+import type { DurableObjectNamespace, DurableObjectState, StoredFileMeta, StoredFileRecord } from "./types.js";
+interface StoreStats {
+    readonly fileCount: number;
+    readonly totalBytes: number;
+}
+export declare class FileStoreDO {
+    private readonly state;
+    constructor(state: DurableObjectState);
+    fetch(request: Request): Promise<Response>;
+}
+export declare class DurableObjectFileStore {
+    private readonly namespace;
+    private readonly policy;
+    constructor(namespace: DurableObjectNamespace, policy: StoragePolicy);
+    private stub;
+    put(input: {
+        readonly filename: string;
+        readonly mimeType: string;
+        readonly bytes: Uint8Array;
+    }): Promise<StoredFileMeta>;
+    get(fileId: string): Promise<StoredFileRecord | null>;
+    list(): Promise<ReadonlyArray<StoredFileMeta>>;
+    delete(fileId: string): Promise<boolean>;
+    stats(): Promise<{
+        policy: StoragePolicy;
+        stats: StoreStats;
+    }>;
+    cleanup(): Promise<{
+        policy: StoragePolicy;
+        deletedExpired: number;
+        deletedEvicted: number;
+        stats: StoreStats;
+    }>;
+}
+export {};

package/dist/file-store-do.js

@@ -0,0 +1,298 @@
+import { fromBase64, toBase64 } from "./file-utils.js";
+const json = (data, status = 200) => new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+});
+const readJson = async (request) => {
+    try {
+        const body = await request.json();
+        if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+            return body;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+};
+const defaultPolicy = () => ({
+    maxFileBytes: 1_200_000,
+    maxTotalBytes: 52_428_800,
+    ttlHours: 24,
+    cleanupBatchSize: 50,
+});
+const parsePolicy = (input) => {
+    const raw = typeof input === "object" && input !== null && !Array.isArray(input)
+        ? input
+        : {};
+    const fallback = defaultPolicy();
+    const maxFileBytes = Number(raw.maxFileBytes ?? fallback.maxFileBytes);
+    const maxTotalBytes = Number(raw.maxTotalBytes ?? fallback.maxTotalBytes);
+    const ttlHours = Number(raw.ttlHours ?? fallback.ttlHours);
+    const cleanupBatchSize = Number(raw.cleanupBatchSize ?? fallback.cleanupBatchSize);
+    return {
+        maxFileBytes: Number.isFinite(maxFileBytes) && maxFileBytes > 0 ? Math.floor(maxFileBytes) : fallback.maxFileBytes,
+        maxTotalBytes: Number.isFinite(maxTotalBytes) && maxTotalBytes > 0 ? Math.floor(maxTotalBytes) : fallback.maxTotalBytes,
+        ttlHours: Number.isFinite(ttlHours) && ttlHours > 0 ? ttlHours : fallback.ttlHours,
+        cleanupBatchSize: Number.isFinite(cleanupBatchSize) && cleanupBatchSize > 0 ? Math.floor(cleanupBatchSize) : fallback.cleanupBatchSize,
+    };
+};
+const toMeta = (value) => ({
+    id: value.id,
+    filename: value.filename,
+    mimeType: value.mimeType,
+    sizeBytes: value.sizeBytes,
+    createdAt: value.createdAt,
+});
+const listStoredValues = async (state) => {
+    const listed = await state.storage.list({ prefix: "file:" });
+    return [...listed.values()];
+};
+const computeStats = (files) => ({
+    fileCount: files.length,
+    totalBytes: files.reduce((sum, file) => sum + file.sizeBytes, 0),
+});
+const isExpired = (createdAt, ttlHours) => {
+    const createdMs = Date.parse(createdAt);
+    if (!Number.isFinite(createdMs))
+        return false;
+    return Date.now() - createdMs > ttlHours * 60 * 60 * 1000;
+};
+const deleteFiles = async (state, files) => {
+    let deleted = 0;
+    for (const file of files) {
+        const ok = await state.storage.delete(`file:${file.id}`);
+        if (ok)
+            deleted += 1;
+    }
+    return deleted;
+};
+export class FileStoreDO {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === "POST" && url.pathname === "/put") {
+            const body = await readJson(request);
+            const policy = parsePolicy(body.policy);
+            const filename = typeof body.filename === "string" ? body.filename : `file-${Date.now()}`;
+            const mimeType = typeof body.mimeType === "string" ? body.mimeType : "application/octet-stream";
+            const bytesBase64 = typeof body.bytesBase64 === "string" ? body.bytesBase64 : "";
+            const bytes = fromBase64(bytesBase64);
+            if (bytes.byteLength > policy.maxFileBytes) {
+                return json({
+                    error: `file too large: ${bytes.byteLength} bytes exceeds maxFileBytes ${policy.maxFileBytes}`,
+                    code: "FILE_TOO_LARGE",
+                    policy,
+                }, 413);
+            }
+            let files = await listStoredValues(this.state);
+            const expired = files.filter((file) => isExpired(file.createdAt, policy.ttlHours));
+            if (expired.length > 0) {
+                await deleteFiles(this.state, expired);
+                files = await listStoredValues(this.state);
+            }
+            let stats = computeStats(files);
+            const projected = stats.totalBytes + bytes.byteLength;
+            if (projected > policy.maxTotalBytes) {
+                const needFree = projected - policy.maxTotalBytes;
+                const candidates = [...files]
+                    .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+                    .slice(0, policy.cleanupBatchSize);
+                let freed = 0;
+                const evictList = [];
+                for (const file of candidates) {
+                    evictList.push(file);
+                    freed += file.sizeBytes;
+                    if (freed >= needFree)
+                        break;
+                }
+                if (evictList.length > 0) {
+                    await deleteFiles(this.state, evictList);
+                    files = await listStoredValues(this.state);
+                    stats = computeStats(files);
+                }
+            }
+            if (stats.totalBytes + bytes.byteLength > policy.maxTotalBytes) {
+                return json({
+                    error: `storage quota exceeded: total ${stats.totalBytes} + incoming ${bytes.byteLength} > maxTotalBytes ${policy.maxTotalBytes}`,
+                    code: "STORAGE_QUOTA_EXCEEDED",
+                    policy,
+                    stats,
+                }, 507);
+            }
+            const id = crypto.randomUUID();
+            const value = {
+                id,
+                filename,
+                mimeType,
+                sizeBytes: bytes.byteLength,
+                createdAt: new Date().toISOString(),
+                bytesBase64,
+            };
+            await this.state.storage.put(`file:${id}`, value);
+            return json({ file: toMeta(value), policy });
+        }
+        if (request.method === "GET" && url.pathname === "/get") {
+            const fileId = url.searchParams.get("fileId");
+            if (!fileId)
+                return json({ error: "Missing fileId" }, 400);
+            const value = await this.state.storage.get(`file:${fileId}`);
+            if (!value)
+                return json({ file: null });
+            return json({ file: value });
+        }
+        if (request.method === "GET" && url.pathname === "/list") {
+            const listed = await this.state.storage.list({ prefix: "file:" });
+            const files = [...listed.values()].map(toMeta);
+            return json({ files });
+        }
+        if (request.method === "POST" && url.pathname === "/delete") {
+            const body = await readJson(request);
+            const fileId = typeof body.fileId === "string" ? body.fileId : "";
+            if (!fileId)
+                return json({ error: "Missing fileId" }, 400);
+            const key = `file:${fileId}`;
+            const existing = await this.state.storage.get(key);
+            if (!existing)
+                return json({ deleted: false });
+            await this.state.storage.delete(key);
+            return json({ deleted: true });
+        }
+        if (request.method === "GET" && url.pathname === "/stats") {
+            let policyInput;
+            const encoded = url.searchParams.get("policy");
+            if (encoded) {
+                try {
+                    policyInput = JSON.parse(encoded);
+                }
+                catch {
+                    policyInput = undefined;
+                }
+            }
+            const policy = parsePolicy(policyInput);
+            const files = await listStoredValues(this.state);
+            const stats = computeStats(files);
+            return json({ policy, stats });
+        }
+        if (request.method === "POST" && url.pathname === "/cleanup") {
+            const body = await readJson(request);
+            const policy = parsePolicy(body.policy);
+            const files = await listStoredValues(this.state);
+            const expired = files.filter((file) => isExpired(file.createdAt, policy.ttlHours));
+            const deletedExpired = await deleteFiles(this.state, expired);
+            const afterExpired = await listStoredValues(this.state);
+            let stats = computeStats(afterExpired);
+            let deletedEvicted = 0;
+            if (stats.totalBytes > policy.maxTotalBytes) {
+                const sorted = [...afterExpired].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+                const evictList = [];
+                for (const file of sorted) {
+                    evictList.push(file);
+                    const projected = stats.totalBytes - evictList.reduce((sum, item) => sum + item.sizeBytes, 0);
+                    if (projected <= policy.maxTotalBytes)
+                        break;
+                    if (evictList.length >= policy.cleanupBatchSize)
+                        break;
+                }
+                deletedEvicted = await deleteFiles(this.state, evictList);
+                stats = computeStats(await listStoredValues(this.state));
+            }
+            return json({
+                policy,
+                deletedExpired,
+                deletedEvicted,
+                stats,
+            });
+        }
+        return json({ error: "Not found" }, 404);
+    }
+}
+export class DurableObjectFileStore {
+    namespace;
+    policy;
+    constructor(namespace, policy) {
+        this.namespace = namespace;
+        this.policy = policy;
+    }
+    stub() {
+        return this.namespace.get(this.namespace.idFromName("echo-pdf-file-store"));
+    }
+    async put(input) {
+        const response = await this.stub().fetch("https://do/put", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                filename: input.filename,
+                mimeType: input.mimeType,
+                bytesBase64: toBase64(input.bytes),
+                policy: this.policy,
+            }),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.file) {
+            const details = payload;
+            const error = new Error(payload.error ?? "DO put failed");
+            error.status = response.status;
+            error.code = typeof details.code === "string" ? details.code : undefined;
+            error.details = { policy: details.policy, stats: details.stats };
+            throw error;
+        }
+        return payload.file;
+    }
+    async get(fileId) {
+        const response = await this.stub().fetch(`https://do/get?fileId=${encodeURIComponent(fileId)}`);
+        const payload = (await response.json());
+        if (!response.ok)
+            throw new Error("DO get failed");
+        if (!payload.file)
+            return null;
+        return {
+            id: payload.file.id,
+            filename: payload.file.filename,
+            mimeType: payload.file.mimeType,
+            sizeBytes: payload.file.sizeBytes,
+            createdAt: payload.file.createdAt,
+            bytes: fromBase64(payload.file.bytesBase64),
+        };
+    }
+    async list() {
+        const response = await this.stub().fetch("https://do/list");
+        const payload = (await response.json());
+        if (!response.ok)
+            throw new Error("DO list failed");
+        return payload.files ?? [];
+    }
+    async delete(fileId) {
+        const response = await this.stub().fetch("https://do/delete", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ fileId }),
+        });
+        const payload = (await response.json());
+        if (!response.ok)
+            throw new Error("DO delete failed");
+        return payload.deleted === true;
+    }
+    async stats() {
+        const policyEncoded = encodeURIComponent(JSON.stringify(this.policy));
+        const response = await this.stub().fetch(`https://do/stats?policy=${policyEncoded}`);
+        const payload = (await response.json());
+        if (!response.ok)
+            throw new Error("DO stats failed");
+        return payload;
+    }
+    async cleanup() {
+        const response = await this.stub().fetch("https://do/cleanup", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ policy: this.policy }),
+        });
+        const payload = (await response.json());
+        if (!response.ok)
+            throw new Error("DO cleanup failed");
+        return payload;
+    }
+}

package/dist/file-utils.d.ts

@@ -0,0 +1,6 @@
+import type { ReturnMode, StoredFileRecord } from "./types.js";
+export declare const fromBase64: (value: string) => Uint8Array;
+export declare const toBase64: (bytes: Uint8Array) => string;
+export declare const toDataUrl: (bytes: Uint8Array, mimeType: string) => string;
+export declare const normalizeReturnMode: (value: unknown) => ReturnMode;
+export declare const toInlineFilePayload: (file: StoredFileRecord, includeBase64: boolean) => Record<string, unknown>;

package/dist/file-utils.js

@@ -0,0 +1,36 @@
+export const fromBase64 = (value) => {
+    const raw = atob(value.replace(/^data:.*;base64,/, ""));
+    const out = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++) {
+        out[i] = raw.charCodeAt(i);
+    }
+    return out;
+};
+export const toBase64 = (bytes) => {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+};
+export const toDataUrl = (bytes, mimeType) => `data:${mimeType};base64,${toBase64(bytes)}`;
+export const normalizeReturnMode = (value) => {
+    if (value === "file_id" || value === "url" || value === "inline") {
+        return value;
+    }
+    return "inline";
+};
+export const toInlineFilePayload = (file, includeBase64) => ({
+    file: {
+        id: file.id,
+        filename: file.filename,
+        mimeType: file.mimeType,
+        sizeBytes: file.sizeBytes,
+        createdAt: file.createdAt,
+    },
+    dataUrl: file.mimeType.startsWith("image/") ? toDataUrl(file.bytes, file.mimeType) : undefined,
+    base64: includeBase64 ? toBase64(file.bytes) : undefined,
+    text: file.mimeType.startsWith("text/") ? new TextDecoder().decode(file.bytes) : undefined,
+});

package/dist/http-error.d.ts

@@ -0,0 +1,9 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export declare const badRequest: (code: string, message: string, details?: unknown) => HttpError;
+export declare const notFound: (code: string, message: string, details?: unknown) => HttpError;
+export declare const unprocessable: (code: string, message: string, details?: unknown) => HttpError;

package/dist/http-error.js

@@ -0,0 +1,14 @@
+export class HttpError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+export const badRequest = (code, message, details) => new HttpError(400, code, message, details);
+export const notFound = (code, message, details) => new HttpError(404, code, message, details);
+export const unprocessable = (code, message, details) => new HttpError(422, code, message, details);

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./core/index.js";