@acosmi/sdk-ts 1.4.1 → 1.4.2

package/dist/node/openai-BDodfhsG.d.cts

@@ -0,0 +1,125 @@
+import { P as ProviderAdapter, k as ProviderFormat, a as ModelCapabilities, C as ChatRequest, b as ChatResponse, S as StreamEvent } from './index-DEA6LXw6.cjs';
+
+/**
+ * Anthropic 内容块
+ * 覆盖: text / thinking / redacted_thinking / tool_use / tool_result /
+ *       server_tool_use / mcp_tool_use / mcp_tool_result
+ */
+interface AnthropicContentBlock {
+    type: string;
+    text?: string;
+    /** tool_use / server_tool_use / mcp_tool_use block ID */
+    id?: string;
+    /** tool_use function name */
+    name?: string;
+    /** tool_use arguments (json.RawMessage) */
+    input?: unknown;
+    /** thinking block content */
+    thinking?: string;
+    /** text — web_search 搜索引用 */
+    citations?: unknown;
+    /** thinking — Anthropic 签名 (后续请求必须回传) */
+    signature?: string;
+    /** redacted_thinking — base64 编码的被审查思考内容 */
+    data?: string;
+    /** server_tool_use / mcp_tool_use / mcp_tool_result — 服务端工具来源 */
+    server_name?: string;
+    /** mcp_tool_use — MCP 调用者上下文 */
+    caller?: unknown;
+    /** tool_result / mcp_tool_result — 工具执行结果 */
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+/** Anthropic token 用量 */
+interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/**
+ * Anthropic 原生格式同步响应
+ * POST /managed-models/:id/anthropic 返回此格式 (无 response.Success 包装)
+ */
+interface AnthropicResponse {
+    id: string;
+    /** "message" */
+    type: string;
+    /** "assistant" */
+    role: string;
+    content: AnthropicContentBlock[];
+    model: string;
+    stop_reason: string;
+    stop_sequence?: string | null;
+    usage: AnthropicUsage;
+}
+/** 提取所有 text 类型内容块的文本，拼接返回 */
+declare function anthropicResponseTextContent(r: AnthropicResponse): string;
+/** 提取所有 thinking 类型内容块的文本，拼接返回 */
+declare function anthropicResponseThinkingContent(r: AnthropicResponse): string;
+/** 返回所有 tool_use 类型的内容块 */
+declare function anthropicResponseToolUseBlocks(r: AnthropicResponse): AnthropicContentBlock[];
+
+/** 实现 ProviderAdapter, 用于所有非 Anthropic 厂商 */
+declare class OpenAIAdapter implements ProviderAdapter {
+    format(): ProviderFormat;
+    endpointSuffix(): string;
+    /**
+     * 构建 OpenAI 兼容格式请求体
+     * 不注入 Anthropic betas, 扩展字段 (thinking/effort/speed) 以通用 JSON 传递
+     */
+    buildRequestBody(_caps: ModelCapabilities, req: ChatRequest): Record<string, unknown>;
+    /**
+     * 解析 OpenAI 格式同步响应为 ChatResponse
+     * 兼容 APIResponse 包装 {"code":0,"data":{...}} 和裸 OpenAI JSON 两种格式
+     */
+    parseResponse(bodyInput: Uint8Array | string): ChatResponse;
+    /**
+     * 解析 OpenAI SSE 行
+     * [DONE] 标记流结束
+     */
+    parseStreamLine(eventType: string, data: string): {
+        event: StreamEvent;
+        done: boolean;
+    };
+}
+/**
+ * 把 Anthropic 心智模型的 thinking/effort 翻译成 OpenAI `reasoning_effort` 字段值
+ * 返回空串表示不设置
+ */
+declare function resolveOpenAIReasoningEffort(req: ChatRequest): string;
+/**
+ * 把 outputConfig 翻译成 OpenAI response_format
+ * 返回 null 表示不设置
+ */
+declare function resolveOpenAIResponseFormat(req: ChatRequest): Record<string, unknown> | null;
+/**
+ * 解析 OpenAI 格式响应并转换为 AnthropicResponse
+ * 用于 chatMessagesOpenAI 方法, 使 Hub 层无需感知 provider 差异
+ */
+declare function parseOpenAIResponseToAnthropic(raw: string | Uint8Array): AnthropicResponse;
+/**
+ * 将 OpenAI SSE chunks 转换为 Anthropic 兼容的 StreamEvent
+ * 有状态: 跨 chunk 追踪 block 索引
+ */
+declare class OpenAIStreamConverter {
+    private messageStarted;
+    private thinkingStarted;
+    private thinkingStopped;
+    private textStarted;
+    /** OpenAI tool_call index → Anthropic block index */
+    private toolBlockIndex;
+    private blockIndex;
+    /**
+     * 将一行 OpenAI SSE data 转换为零或多个 Anthropic 格式 StreamEvent
+     * 返回 { events, done }
+     */
+    convert(data: string): {
+        events: StreamEvent[];
+        done: boolean;
+    };
+}
+declare function newOpenAIStreamConverter(): OpenAIStreamConverter;
+
+export { type AnthropicResponse as A, OpenAIAdapter as O, type AnthropicContentBlock as a, type AnthropicUsage as b, anthropicResponseTextContent as c, anthropicResponseThinkingContent as d, anthropicResponseToolUseBlocks as e, OpenAIStreamConverter as f, resolveOpenAIResponseFormat as g, newOpenAIStreamConverter as n, parseOpenAIResponseToAnthropic as p, resolveOpenAIReasoningEffort as r };

package/dist/node/openai-vfUUgdvL.d.ts

@@ -0,0 +1,125 @@
+import { P as ProviderAdapter, k as ProviderFormat, a as ModelCapabilities, C as ChatRequest, b as ChatResponse, S as StreamEvent } from './index-DEA6LXw6.js';
+
+/**
+ * Anthropic 内容块
+ * 覆盖: text / thinking / redacted_thinking / tool_use / tool_result /
+ *       server_tool_use / mcp_tool_use / mcp_tool_result
+ */
+interface AnthropicContentBlock {
+    type: string;
+    text?: string;
+    /** tool_use / server_tool_use / mcp_tool_use block ID */
+    id?: string;
+    /** tool_use function name */
+    name?: string;
+    /** tool_use arguments (json.RawMessage) */
+    input?: unknown;
+    /** thinking block content */
+    thinking?: string;
+    /** text — web_search 搜索引用 */
+    citations?: unknown;
+    /** thinking — Anthropic 签名 (后续请求必须回传) */
+    signature?: string;
+    /** redacted_thinking — base64 编码的被审查思考内容 */
+    data?: string;
+    /** server_tool_use / mcp_tool_use / mcp_tool_result — 服务端工具来源 */
+    server_name?: string;
+    /** mcp_tool_use — MCP 调用者上下文 */
+    caller?: unknown;
+    /** tool_result / mcp_tool_result — 工具执行结果 */
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+/** Anthropic token 用量 */
+interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/**
+ * Anthropic 原生格式同步响应
+ * POST /managed-models/:id/anthropic 返回此格式 (无 response.Success 包装)
+ */
+interface AnthropicResponse {
+    id: string;
+    /** "message" */
+    type: string;
+    /** "assistant" */
+    role: string;
+    content: AnthropicContentBlock[];
+    model: string;
+    stop_reason: string;
+    stop_sequence?: string | null;
+    usage: AnthropicUsage;
+}
+/** 提取所有 text 类型内容块的文本，拼接返回 */
+declare function anthropicResponseTextContent(r: AnthropicResponse): string;
+/** 提取所有 thinking 类型内容块的文本，拼接返回 */
+declare function anthropicResponseThinkingContent(r: AnthropicResponse): string;
+/** 返回所有 tool_use 类型的内容块 */
+declare function anthropicResponseToolUseBlocks(r: AnthropicResponse): AnthropicContentBlock[];
+
+/** 实现 ProviderAdapter, 用于所有非 Anthropic 厂商 */
+declare class OpenAIAdapter implements ProviderAdapter {
+    format(): ProviderFormat;
+    endpointSuffix(): string;
+    /**
+     * 构建 OpenAI 兼容格式请求体
+     * 不注入 Anthropic betas, 扩展字段 (thinking/effort/speed) 以通用 JSON 传递
+     */
+    buildRequestBody(_caps: ModelCapabilities, req: ChatRequest): Record<string, unknown>;
+    /**
+     * 解析 OpenAI 格式同步响应为 ChatResponse
+     * 兼容 APIResponse 包装 {"code":0,"data":{...}} 和裸 OpenAI JSON 两种格式
+     */
+    parseResponse(bodyInput: Uint8Array | string): ChatResponse;
+    /**
+     * 解析 OpenAI SSE 行
+     * [DONE] 标记流结束
+     */
+    parseStreamLine(eventType: string, data: string): {
+        event: StreamEvent;
+        done: boolean;
+    };
+}
+/**
+ * 把 Anthropic 心智模型的 thinking/effort 翻译成 OpenAI `reasoning_effort` 字段值
+ * 返回空串表示不设置
+ */
+declare function resolveOpenAIReasoningEffort(req: ChatRequest): string;
+/**
+ * 把 outputConfig 翻译成 OpenAI response_format
+ * 返回 null 表示不设置
+ */
+declare function resolveOpenAIResponseFormat(req: ChatRequest): Record<string, unknown> | null;
+/**
+ * 解析 OpenAI 格式响应并转换为 AnthropicResponse
+ * 用于 chatMessagesOpenAI 方法, 使 Hub 层无需感知 provider 差异
+ */
+declare function parseOpenAIResponseToAnthropic(raw: string | Uint8Array): AnthropicResponse;
+/**
+ * 将 OpenAI SSE chunks 转换为 Anthropic 兼容的 StreamEvent
+ * 有状态: 跨 chunk 追踪 block 索引
+ */
+declare class OpenAIStreamConverter {
+    private messageStarted;
+    private thinkingStarted;
+    private thinkingStopped;
+    private textStarted;
+    /** OpenAI tool_call index → Anthropic block index */
+    private toolBlockIndex;
+    private blockIndex;
+    /**
+     * 将一行 OpenAI SSE data 转换为零或多个 Anthropic 格式 StreamEvent
+     * 返回 { events, done }
+     */
+    convert(data: string): {
+        events: StreamEvent[];
+        done: boolean;
+    };
+}
+declare function newOpenAIStreamConverter(): OpenAIStreamConverter;
+
+export { type AnthropicResponse as A, OpenAIAdapter as O, type AnthropicContentBlock as a, type AnthropicUsage as b, anthropicResponseTextContent as c, anthropicResponseThinkingContent as d, anthropicResponseToolUseBlocks as e, OpenAIStreamConverter as f, resolveOpenAIResponseFormat as g, newOpenAIStreamConverter as n, parseOpenAIResponseToAnthropic as p, resolveOpenAIReasoningEffort as r };

package/examples/agent-runs-stream.ts

@@ -0,0 +1,118 @@
+// examples/agent-runs-stream.ts — Agent Run Gateway 示例（创建 / 流式 / 本地工具 / 产物）。
+//
+// 演示：
+//   1. 创建一个 agent run (client.agentRuns.create)
+//   2. 流式消费 run 事件 (client.agentRuns.stream)，断线可 durable replay
+//   3. 显式 opt-in 本地只读工具桥：处理 local_tool_request，回传 submitLocalToolResult
+//   4. 下载产物 (downloadArtifact)
+//   5. 处理 usage / settle 事件，从 UI 取消按钮安全调用 cancel
+//
+// 红线：
+//   - 下游产品禁止直连 Nexus 内部 /api/v4/chat/completions 实现智能体循环，必须走
+//     client.agentRuns。
+//   - SDK 不内置任何 CrabDesign/CrabCode 专属文件读取逻辑；local_tool_request 只定义
+//     协议，handler 由下游显式提供，allowedTools 用稳定 ASCII function name。
+//   - 结算只用 provider/ADK 透传的精确 usage；exact !== true 时服务端释放 hold，
+//     不会用估算 token 扣费。
+
+import { Client, allScopes, AgentRunStreamError } from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const client = await Client.create({ serverURL });
+  await client.login('Agent Runs Example', allScopes());
+
+  // 1) 创建 run。create 是 POST 副作用操作，401 不自动 refresh 重放。
+  const run = await client.agentRuns.create({
+    appId: 'crabdesign',
+    mode: 'design',
+    input: 'Create a landing page mockup for a fintech dashboard',
+    activeSkillIds: ['brand-system'],
+    knowledgeBaseIds: ['kb-product'],
+    // 本地只读上下文策略：显式 opt-in，限制可用工具与读取上限。
+    localContextPolicy: {
+      enabled: true,
+      readonly: true,
+      maxBytes: 128_000,
+      allowedTools: ['read_file'],
+    },
+    artifactPolicy: { enabled: true, maxFiles: 10 },
+  });
+  console.log('[run created] runId=', run.runId, 'status=', run.status);
+
+  // 2) 流式消费。stream 支持 durable replay：断线后重连同一 run 会先回放已持久化事件。
+  //    throwOnError:false → 自行消费 error 事件而不是直接抛 AgentRunStreamError。
+  try {
+    for await (const event of client.agentRuns.stream(run.runId, { throwOnError: false })) {
+      switch (event.type) {
+        case 'text_delta':
+          process.stdout.write(event.text);
+          break;
+        case 'reasoning_delta':
+          console.debug('\n[reasoning]', event.text);
+          break;
+        case 'local_tool_request': {
+          // 3) 本地工具桥 — 由下游产品代码拥有，这里只是只读演示实现。
+          const result = await handleLocalTool(event.name, event.input);
+          await client.agentRuns.submitLocalToolResult(run.runId, {
+            requestId: event.requestId,
+            ok: result.ok,
+            content: result.content,
+            error: result.error,
+          });
+          break;
+        }
+        case 'artifact': {
+          // 4) 下载产物 — GET 安全查询，允许单次 401 refresh 重试。
+          const file = await client.agentRuns.downloadArtifact(run.runId, event.artifact.id);
+          console.log('\n[artifact]', file.filename, file.contentType,
+            file.data.byteLength, 'bytes');
+          break;
+        }
+        case 'usage':
+          console.log('\n[usage] totalTokens=', event.usage.totalTokens,
+            'exact=', event.usage.exact);
+          break;
+        case 'settle':
+          console.log('[settle] status=', event.settlement.status,
+            'tokenRemaining=', event.settlement.tokenRemaining);
+          break;
+        case 'error':
+          console.error('\n[error]', event.error.code, event.error.message);
+          break;
+        case 'done':
+          console.log('\n[done] status=', event.status);
+          break;
+      }
+    }
+  } catch (e) {
+    if (e instanceof AgentRunStreamError) {
+      console.error('agent run stream error:', e.code, e.stage, 'retryable=', e.retryable);
+    } else {
+      throw e;
+    }
+  }
+
+  // 5) cancel 可从 UI 取消按钮安全调用（即使 run 已结束也不会抛）。
+  // await client.agentRuns.cancel(run.runId);
+}
+
+// 本地只读工具实现示例。生产环境只暴露受控的只读操作，拒绝越权路径。
+async function handleLocalTool(
+  name: string,
+  input: unknown,
+): Promise<{ ok: boolean; content?: unknown; error?: string }> {
+  if (name !== 'read_file') {
+    return { ok: false, error: `local tool rejected: unsupported tool ${name}` };
+  }
+  // 这里应做路径白名单校验后读取文件；示例仅返回占位内容。
+  return { ok: true, content: { note: 'read-only local context placeholder', input } };
+}
+
+main().catch((err) => {
+  console.error('agent runs example failed:', err);
+  process.exit(1);
+});

package/examples/auth-oauth-flow.ts

@@ -0,0 +1,97 @@
+// examples/auth-oauth-flow.ts — 手动 OAuth 2.1 PKCE 流程示例（CLI / 自定义流程）。
+//
+// 演示：
+//   1. discover  — 拉取 OAuth Authorization Server 元数据 (RFC 8414)
+//   2. register  — RFC 7591 动态客户端注册
+//   3. authorize — 本地 loopback PKCE 授权 (Node only)，拿 authorization code
+//   4. exchangeCode — 用 code + code_verifier 换 token
+//   5. newTokenSet + TokenStore — 持久化 token，后续复用
+//   6. refreshToken — 用 refresh_token 续期
+//
+// 说明：
+//   - 大多数场景直接用 `client.login(appName, scopes)` 即可（内部封装了下面全部步骤）。
+//     本示例演示底层 helper，适用于需要自定义授权流程 / 自管 token 的 CLI。
+//   - authorize 仅在 Node 环境可用（需要本地 HTTP 回调 server）；浏览器侧应自行实现
+//     popup window + redirect handler。
+
+import {
+  discover,
+  register,
+  authorize,
+  exchangeCode,
+  refreshToken,
+  newTokenSet,
+  tokenSetIsExpired,
+  FileTokenStore,
+  allScopes,
+} from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const scopes = allScopes();
+  const store = new FileTokenStore(process.env.ACOSMI_TOKEN_FILE ?? './auth-tokens.json');
+
+  // 0) 已有持久化 token 且未过期 → 直接复用，跳过整个授权流程。
+  const existing = await store.load();
+  if (existing && !tokenSetIsExpired(existing)) {
+    console.log('[token] reusing valid token from store, scope=', existing.scope);
+    return;
+  }
+
+  // 1) discover — OAuth Authorization Server 元数据
+  const meta = await discover(serverURL);
+  console.log('[discover] issuer=', meta.issuer);
+  console.log('[discover] token_endpoint=', meta.token_endpoint);
+
+  // 2) register — 动态注册一个 client，拿到 client_id
+  const reg = await register(meta, 'Auth Flow Example');
+  console.log('[register] client_id=', reg.client_id);
+
+  let tokenSet;
+
+  // 3) refresh-first：store 里有过期 token 但带 refresh_token → 先尝试静默刷新。
+  if (existing && existing.refresh_token) {
+    try {
+      const refreshed = await refreshToken(meta, existing.client_id, existing.refresh_token);
+      tokenSet = newTokenSet(refreshed, existing.client_id, serverURL);
+      console.log('[refresh] token refreshed without re-authorizing');
+    } catch (e) {
+      console.warn('[refresh] failed, falling back to full authorize:',
+        e instanceof Error ? e.message : e);
+    }
+  }
+
+  // 4) 没有可刷新的 token → 走完整 PKCE 授权。
+  if (!tokenSet) {
+    const { result, verifier } = await authorize(meta, reg.client_id, scopes, {
+      handler: (ev) => {
+        if (ev.type === 'auth_url') console.log('[authorize] open in browser:', ev.url);
+        if (ev.type === 'error') console.error('[authorize] error:', ev.err_code, ev.error);
+      },
+    });
+    console.log('[authorize] received authorization code');
+
+    // 5) exchangeCode — code + code_verifier 换 token
+    const tokenResp = await exchangeCode(
+      meta,
+      reg.client_id,
+      result.code,
+      result.redirectURI,
+      verifier,
+    );
+    tokenSet = newTokenSet(tokenResp, reg.client_id, serverURL);
+    console.log('[exchange] access token acquired, scope=', tokenSet.scope);
+  }
+
+  // 6) 持久化 token，供下次启动复用 / Client 直接读取。
+  await store.save(tokenSet);
+  console.log('[store] token persisted; expires_at=', tokenSet.expires_at);
+}
+
+main().catch((err) => {
+  console.error('auth oauth flow example failed:', err);
+  process.exit(1);
+});

package/examples/core-chat.ts

@@ -0,0 +1,85 @@
+// examples/core-chat.ts — Client 基础用法示例（构造 / 配置 / 模型列举 / chat / 流式）。
+//
+// 演示：
+//   1. 构造 Client (serverURL + 可选 FileTokenStore)
+//   2. OAuth 登录 (按业务最小集合申请 scope)
+//   3. 列举托管模型 + 查看配额摘要
+//   4. 同步 chat 调用
+//   5. 流式 chatStreamWithUsage 并聚合 usage / 结算事件
+//
+// 说明：
+//   - SDK 自动按 ManagedModel 的 preferredFormat / supportedFormats 选 Anthropic
+//     或 OpenAI adapter，调用方无需关心。
+//   - 金额 / 余额字段是 string（避免 JS number 精度损失），不要做浮点运算。
+
+import { Client, allScopes, FileTokenStore } from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+
+  // 1) 构造 Client。Client.create 会从 store 异步加载已持久化的 token。
+  //    Node 上不传 store 时默认 ~/.acosmi/tokens.json；这里显式指定一个路径。
+  const client = await Client.create({
+    serverURL,
+    store: new FileTokenStore(process.env.ACOSMI_TOKEN_FILE ?? './core-tokens.json'),
+  });
+
+  // 2) OAuth 登录 — 已有有效 token 时 login 会直接复用，不重复弹浏览器。
+  await client.login('Core Chat Example', allScopes());
+
+  // 3) 列举托管模型 + 配额摘要
+  const models = await client.listModels();
+  console.log('[models]', models.length, 'available');
+  for (const m of models.slice(0, 5)) {
+    console.log('  -', m.modelId, `(provider=${m.provider}, enabled=${m.isEnabled})`);
+  }
+
+  const quota = await client.getQuotaSummary();
+  console.log('[quota] freeTotalEtu=', quota.freeTotalEtu,
+    'paidTotalEtu=', quota.paidTotalEtu);
+
+  // 选一个模型：优先 isDefault，否则取第一个启用的。
+  const model =
+    models.find((m) => m.isDefault && m.isEnabled) ??
+    models.find((m) => m.isEnabled);
+  if (!model) {
+    throw new Error('no enabled model available — 让管理员在网关启用一个模型');
+  }
+  console.log('[selected model]', model.modelId);
+
+  // 4) 同步 chat 调用
+  const resp = await client.chat(model.modelId, {
+    messages: [{ role: 'user', content: '用一句话介绍 TypeScript。' }],
+    max_tokens: 256,
+  });
+  for (const block of resp.content) {
+    if (block.type === 'text' && block.text) {
+      console.log('[chat text]', block.text);
+    }
+  }
+  console.log('[chat usage] input=', resp.usage.input_tokens,
+    'output=', resp.usage.output_tokens);
+
+  // 5) 流式调用 — chatStreamWithUsage 把内容 / sources / 结算事件分流为带标签的迭代项。
+  const stream = client.chatStreamWithUsage(model.modelId, {
+    messages: [{ role: 'user', content: '写一首关于海的两行短诗。' }],
+    max_tokens: 512,
+  });
+  for await (const item of stream) {
+    if (item.kind === 'content' && item.event.event === 'content_block_delta') {
+      process.stdout.write('.'); // 实际项目里在此解析 delta 输出 token
+    } else if (item.kind === 'settle') {
+      console.log('\n[settle] totalTokens=', item.event.totalTokens,
+        'tokenRemaining=', item.event.tokenRemaining);
+    }
+  }
+  console.log('\n[stream] done');
+}
+
+main().catch((err) => {
+  console.error('core chat example failed:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -51,7 +51,8 @@
     "format": "prettier --write \"src/**/*.{ts,json}\"",
     "typecheck": "tsc --noEmit",
     "test:pack": "node scripts/smoke-pack.mjs",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run test:pack"
+    "docs": "typedoc",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run test:pack && npm run docs"
   },
   "engines": {
     "node": ">=18"
@@ -90,6 +91,8 @@
     "eslint": "^8.57.0",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0"
   }