@echofiles/echo-pdf 0.4.0 → 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 域名）。文档里用：
@@ -144,6 +218,7 @@ echo-pdf setup add cursor
 echo-pdf setup add cline
 echo-pdf setup add windsurf
 echo-pdf setup add json
+echo-pdf setup add claude-desktop --mode stdio
 ```
 
 `setup add` 输出的是配置片段，把它合并到对应客户端的 MCP 配置文件。
@@ -283,6 +358,11 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `ECHO_PDF_MCP_KEY`（可选，启用 MCP 鉴权）
 - `ECHO_PDF_WORKER_NAME`（CLI 默认 URL 推导）
 
+鉴权注意：
+
+- 如果配置了 `authHeader/authEnv` 但未注入对应 secret，服务会返回配置错误（fail-closed），不会默认放行。
+- 仅开发调试场景可显式设置 `ECHO_PDF_ALLOW_MISSING_AUTH_SECRET=1` 临时放行“缺 secret”的请求。
+
 ## 7. 本地开发与测试
 
 安装与开发：

package/bin/echo-pdf.js

@@ -4,6 +4,8 @@ import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
+import { downloadFile, postJson, uploadFile, withUploadedLocalFile } from "./lib/http.js"
+import { runMcpStdio } from "./lib/mcp-stdio.js"
 
 const CONFIG_DIR = path.join(os.homedir(), ".config", "echo-pdf-cli")
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json")
@@ -163,25 +165,6 @@ const buildProviderApiKeys = (config, profileName) => {
   return providerApiKeys
 }
 
-const postJson = async (url, payload, extraHeaders = {}) => {
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", ...extraHeaders },
-    body: JSON.stringify(payload),
-  })
-  const text = await response.text()
-  let data
-  try {
-    data = JSON.parse(text)
-  } catch {
-    data = { raw: text }
-  }
-  if (!response.ok) {
-    throw new Error(`${response.status} ${JSON.stringify(data)}`)
-  }
-  return data
-}
-
 const print = (data) => {
   process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
 }
@@ -209,57 +192,6 @@ const buildMcpRequest = (id, method, params = {}) => ({
   params,
 })
 
-const uploadFile = async (serviceUrl, filePath) => {
-  const absPath = path.resolve(process.cwd(), filePath)
-  const bytes = fs.readFileSync(absPath)
-  const filename = path.basename(absPath)
-  const form = new FormData()
-  form.append("file", new Blob([bytes]), filename)
-  const response = await fetch(`${serviceUrl}/api/files/upload`, { method: "POST", body: form })
-  const text = await response.text()
-  let data
-  try {
-    data = JSON.parse(text)
-  } catch {
-    data = { raw: text }
-  }
-  if (!response.ok) {
-    throw new Error(`${response.status} ${JSON.stringify(data)}`)
-  }
-  return data
-}
-
-const downloadFile = async (serviceUrl, fileId, outputPath) => {
-  const response = await fetch(`${serviceUrl}/api/files/get?fileId=${encodeURIComponent(fileId)}&download=1`)
-  if (!response.ok) {
-    const text = await response.text()
-    throw new Error(`${response.status} ${text}`)
-  }
-  const bytes = Buffer.from(await response.arrayBuffer())
-  const absOut = path.resolve(process.cwd(), outputPath)
-  fs.mkdirSync(path.dirname(absOut), { recursive: true })
-  fs.writeFileSync(absOut, bytes)
-  return absOut
-}
-
-const withUploadedLocalFile = async (serviceUrl, tool, args) => {
-  const nextArgs = { ...(args || {}) }
-  if (tool.startsWith("pdf_")) {
-    const localPath = typeof nextArgs.path === "string"
-      ? nextArgs.path
-      : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
-    if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
-      const upload = await uploadFile(serviceUrl, localPath)
-      const fileId = upload?.file?.id
-      if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
-      nextArgs.fileId = fileId
-      delete nextArgs.path
-      delete nextArgs.filePath
-    }
-  }
-  return nextArgs
-}
-
 const runDevServer = (port, host) => {
   const wranglerBin = path.resolve(__dirname, "../node_modules/.bin/wrangler")
   const wranglerArgs = ["dev", "--port", String(port), "--ip", host]
@@ -276,100 +208,13 @@ const runDevServer = (port, host) => {
   })
 }
 
-const mcpReadLoop = (onMessage, onError) => {
-  let buffer = Buffer.alloc(0)
-  let expectedLength = null
-  process.stdin.on("data", (chunk) => {
-    buffer = Buffer.concat([buffer, chunk])
-    while (true) {
-      if (expectedLength === null) {
-        const headerEnd = buffer.indexOf("\r\n\r\n")
-        if (headerEnd === -1) break
-        const headerRaw = buffer.slice(0, headerEnd).toString("utf-8")
-        const lines = headerRaw.split("\r\n")
-        const cl = lines.find((line) => line.toLowerCase().startsWith("content-length:"))
-        if (!cl) {
-          onError(new Error("Missing Content-Length"))
-          buffer = buffer.slice(headerEnd + 4)
-          continue
-        }
-        expectedLength = Number(cl.split(":")[1]?.trim() || "0")
-        buffer = buffer.slice(headerEnd + 4)
-      }
-      if (!Number.isFinite(expectedLength) || expectedLength < 0) {
-        onError(new Error("Invalid Content-Length"))
-        expectedLength = null
-        continue
-      }
-      if (buffer.length < expectedLength) break
-      const body = buffer.slice(0, expectedLength).toString("utf-8")
-      buffer = buffer.slice(expectedLength)
-      expectedLength = null
-      try {
-        const maybePromise = onMessage(JSON.parse(body))
-        if (maybePromise && typeof maybePromise.then === "function") {
-          maybePromise.catch(onError)
-        }
-      } catch (error) {
-        onError(error)
-      }
-    }
-  })
-}
-
-const mcpWrite = (obj) => {
-  const body = Buffer.from(JSON.stringify(obj))
-  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`)
-  process.stdout.write(header)
-  process.stdout.write(body)
-}
-
-const runMcpStdio = async () => {
+const runMcpStdioCommand = async () => {
   const config = loadConfig()
-  const serviceUrl = config.serviceUrl
-  const headers = buildMcpHeaders()
-  mcpReadLoop(async (msg) => {
-    const method = msg?.method
-    const id = Object.hasOwn(msg || {}, "id") ? msg.id : null
-    if (msg?.jsonrpc !== "2.0" || typeof method !== "string") {
-      mcpWrite({ jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } })
-      return
-    }
-    if (method === "notifications/initialized") return
-    if (method === "initialize" || method === "tools/list") {
-      const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
-      mcpWrite(data)
-      return
-    }
-    if (method === "tools/call") {
-      try {
-        const tool = String(msg?.params?.name || "")
-        const args = (msg?.params?.arguments && typeof msg.params.arguments === "object")
-          ? msg.params.arguments
-          : {}
-        const preparedArgs = await withUploadedLocalFile(serviceUrl, tool, args)
-        const payload = {
-          ...msg,
-          params: {
-            ...(msg.params || {}),
-            arguments: preparedArgs,
-          },
-        }
-        const data = await postJson(`${serviceUrl}/mcp`, payload, headers)
-        mcpWrite(data)
-      } catch (error) {
-        mcpWrite({
-          jsonrpc: "2.0",
-          id,
-          error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
-        })
-      }
-      return
-    }
-    const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
-    mcpWrite(data)
-  }, (error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  await runMcpStdio({
+    serviceUrl: config.serviceUrl,
+    headers: buildMcpHeaders(),
+    postJson,
+    withUploadedLocalFile,
   })
 }
 
@@ -793,7 +638,7 @@ const main = async () => {
   }
 
   if (command === "mcp" && subcommand === "stdio") {
-    await runMcpStdio()
+    await runMcpStdioCommand()
     return
   }
 

package/bin/lib/http.js

@@ -0,0 +1,72 @@
+import fs from "node:fs"
+import path from "node:path"
+
+export const postJson = async (url, payload, extraHeaders = {}) => {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...extraHeaders },
+    body: JSON.stringify(payload),
+  })
+  const text = await response.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  if (!response.ok) {
+    throw new Error(`${response.status} ${JSON.stringify(data)}`)
+  }
+  return data
+}
+
+export const uploadFile = async (serviceUrl, filePath) => {
+  const absPath = path.resolve(process.cwd(), filePath)
+  const bytes = fs.readFileSync(absPath)
+  const filename = path.basename(absPath)
+  const form = new FormData()
+  form.append("file", new Blob([bytes]), filename)
+  const response = await fetch(`${serviceUrl}/api/files/upload`, { method: "POST", body: form })
+  const text = await response.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  if (!response.ok) {
+    throw new Error(`${response.status} ${JSON.stringify(data)}`)
+  }
+  return data
+}
+
+export const downloadFile = async (serviceUrl, fileId, outputPath) => {
+  const response = await fetch(`${serviceUrl}/api/files/get?fileId=${encodeURIComponent(fileId)}&download=1`)
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  const bytes = Buffer.from(await response.arrayBuffer())
+  const absOut = path.resolve(process.cwd(), outputPath)
+  fs.mkdirSync(path.dirname(absOut), { recursive: true })
+  fs.writeFileSync(absOut, bytes)
+  return absOut
+}
+
+export const withUploadedLocalFile = async (serviceUrl, tool, args) => {
+  const nextArgs = { ...(args || {}) }
+  if (tool.startsWith("pdf_")) {
+    const localPath = typeof nextArgs.path === "string"
+      ? nextArgs.path
+      : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
+    if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
+      const upload = await uploadFile(serviceUrl, localPath)
+      const fileId = upload?.file?.id
+      if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
+      nextArgs.fileId = fileId
+      delete nextArgs.path
+      delete nextArgs.filePath
+    }
+  }
+  return nextArgs
+}

package/bin/lib/mcp-stdio.js

@@ -0,0 +1,99 @@
+const mcpReadLoop = (onMessage, onError) => {
+  let buffer = Buffer.alloc(0)
+  let expectedLength = null
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk])
+    while (true) {
+      if (expectedLength === null) {
+        const headerEnd = buffer.indexOf("\r\n\r\n")
+        if (headerEnd === -1) break
+        const headerRaw = buffer.slice(0, headerEnd).toString("utf-8")
+        const lines = headerRaw.split("\r\n")
+        const cl = lines.find((line) => line.toLowerCase().startsWith("content-length:"))
+        if (!cl) {
+          onError(new Error("Missing Content-Length"))
+          buffer = buffer.slice(headerEnd + 4)
+          continue
+        }
+        expectedLength = Number(cl.split(":")[1]?.trim() || "0")
+        buffer = buffer.slice(headerEnd + 4)
+      }
+      if (!Number.isFinite(expectedLength) || expectedLength < 0) {
+        onError(new Error("Invalid Content-Length"))
+        expectedLength = null
+        continue
+      }
+      if (buffer.length < expectedLength) break
+      const body = buffer.slice(0, expectedLength).toString("utf-8")
+      buffer = buffer.slice(expectedLength)
+      expectedLength = null
+      try {
+        const maybePromise = onMessage(JSON.parse(body))
+        if (maybePromise && typeof maybePromise.then === "function") {
+          maybePromise.catch(onError)
+        }
+      } catch (error) {
+        onError(error)
+      }
+    }
+  })
+}
+
+const mcpWrite = (obj) => {
+  const body = Buffer.from(JSON.stringify(obj))
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`)
+  process.stdout.write(header)
+  process.stdout.write(body)
+}
+
+export const runMcpStdio = async (deps) => {
+  const {
+    serviceUrl,
+    headers,
+    postJson,
+    withUploadedLocalFile,
+  } = deps
+  mcpReadLoop(async (msg) => {
+    const method = msg?.method
+    const id = Object.hasOwn(msg || {}, "id") ? msg.id : null
+    if (msg?.jsonrpc !== "2.0" || typeof method !== "string") {
+      mcpWrite({ jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } })
+      return
+    }
+    if (method === "notifications/initialized") return
+    if (method === "initialize" || method === "tools/list") {
+      const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+      mcpWrite(data)
+      return
+    }
+    if (method === "tools/call") {
+      try {
+        const tool = String(msg?.params?.name || "")
+        const args = (msg?.params?.arguments && typeof msg.params.arguments === "object")
+          ? msg.params.arguments
+          : {}
+        const preparedArgs = await withUploadedLocalFile(serviceUrl, tool, args)
+        const payload = {
+          ...msg,
+          params: {
+            ...(msg.params || {}),
+            arguments: preparedArgs,
+          },
+        }
+        const data = await postJson(`${serviceUrl}/mcp`, payload, headers)
+        mcpWrite(data)
+      } catch (error) {
+        mcpWrite({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+        })
+      }
+      return
+    }
+    const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+    mcpWrite(data)
+  }, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  })
+}

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));
+};