@tokenbuddy/tokenbuddy 1.0.12 → 1.0.14

package/dist/src/terminal-detect.d.ts

@@ -1,29 +1,80 @@
+/**
+ * `detectTerminals()` 的输出单元：描述一个可被 rewrite 的 coding terminal。
+ * `detected=false` 时仍会返回，UI 用其渲染"未安装"标签而不是直接跳过。
+ */
 export interface TerminalCandidate {
+    /** terminal 内部 ID，例：`claude-code` / `claude-desktop` / `openclaw` / `hermes` */
     id: string;
+    /** 人类可读名称，例：`Claude Code CLI` */
     name: string;
+    /** 本机是否检测到该 terminal 的配置文件 */
     detected: boolean;
+    /** 配置文件绝对路径（即使未检测到也会拼出预期路径） */
     configPath: string;
+    /** 检测结果的说明，用于 UI 展示 */
     reason: string;
 }
+/**
+ * 获取当前用户的 home 目录，作为拼装 terminal 配置路径的基准。
+ *
+ * @returns `os.homedir()` 返回的 home 路径
+ */
 export declare function getHomeDir(): string;
 /**
  * Detect which coding terminals are installed on the local system.
+ *
+ * 通过 `~/.claude/settings.json`、`Library/Application Support/Claude/...`、
+ * `~/.openclaw/config.json`、`~/.hermes/settings.json` 等约定路径判断。
+ * Claude Desktop 在非 macOS 平台上 `configPath` 可能为空字符串，
+ * 调用方需以 `detected` 字段为准。
+ *
+ * @returns terminal 候选列表（固定四个 ID 顺序）
  */
 export declare function detectTerminals(): TerminalCandidate[];
 /**
  * Safely rewrite Claude Code settings to route requests through our proxy.
+ *
+ * 写入 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`（占位 `TOKENBUDDY_PROXY`）/
+ * `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL`。失败时仅打印日志，
+ * 不会抛出异常；调用方无需 try/catch。
+ *
+ * @param configPath `~/.claude/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Code 默认模型 ID
  */
 export declare function rewriteClaudeCode(configPath: string, proxyUrl: string, model: string): void;
 /**
  * Safely rewrite Claude Desktop configuration.
+ *
+ * 写入 `deploymentMode = "3p"` 到 Claude 与 Claude-3p 两个目录，
+ * 并在 `configLibrary/<DESKTOP_PROFILE_ID>.json` 写入 TokenBuddy profile。
+ * 最后更新 `_meta.json` 把 `appliedId` 指向该 profile。
+ *
+ * @param configPath Claude Desktop 主配置（`claude_desktop_config.json`）绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Desktop 默认模型 ID
  */
 export declare function rewriteClaudeDesktop(configPath: string, proxyUrl: string, model: string): void;
 /**
  * Rewrite Openclaw settings.
+ *
+ * 写入 `api_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.openclaw/config.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Openclaw 默认模型 ID
  */
 export declare function rewriteOpenclaw(configPath: string, proxyUrl: string, model: string): void;
 /**
  * Rewrite Hermes settings.
+ *
+ * 在 `openai` 块下写入 `base_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.hermes/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Hermes 默认模型 ID
  */
 export declare function rewriteHermes(configPath: string, proxyUrl: string, model: string): void;
 //# sourceMappingURL=terminal-detect.d.ts.map

package/dist/src/terminal-detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-detect.d.ts","sourceRoot":"","sources":["../../src/terminal-detect.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,EAAE,CAuDrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA4B3F;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA0D9F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAmBzF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAsBvF"}
+{"version":3,"file":"terminal-detect.d.ts","sourceRoot":"","sources":["../../src/terminal-detect.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,EAAE,CAuDrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA4B3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA0D9F;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAmBzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAsBvF"}

package/dist/src/terminal-detect.js

@@ -3,11 +3,23 @@ import * as path from "path";
 import * as os from "os";
 const PLACEHOLDER_API_KEY = "TOKENBUDDY_PROXY";
 const DESKTOP_PROFILE_ID = "00000000-0000-4000-8000-000000178210";
+/**
+ * 获取当前用户的 home 目录，作为拼装 terminal 配置路径的基准。
+ *
+ * @returns `os.homedir()` 返回的 home 路径
+ */
 export function getHomeDir() {
     return os.homedir();
 }
 /**
  * Detect which coding terminals are installed on the local system.
+ *
+ * 通过 `~/.claude/settings.json`、`Library/Application Support/Claude/...`、
+ * `~/.openclaw/config.json`、`~/.hermes/settings.json` 等约定路径判断。
+ * Claude Desktop 在非 macOS 平台上 `configPath` 可能为空字符串，
+ * 调用方需以 `detected` 字段为准。
+ *
+ * @returns terminal 候选列表（固定四个 ID 顺序）
  */
 export function detectTerminals() {
     const home = getHomeDir();
@@ -63,6 +75,14 @@ export function detectTerminals() {
 }
 /**
  * Safely rewrite Claude Code settings to route requests through our proxy.
+ *
+ * 写入 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`（占位 `TOKENBUDDY_PROXY`）/
+ * `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL`。失败时仅打印日志，
+ * 不会抛出异常；调用方无需 try/catch。
+ *
+ * @param configPath `~/.claude/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Code 默认模型 ID
  */
 export function rewriteClaudeCode(configPath, proxyUrl, model) {
     try {
@@ -93,6 +113,14 @@ export function rewriteClaudeCode(configPath, proxyUrl, model) {
 }
 /**
  * Safely rewrite Claude Desktop configuration.
+ *
+ * 写入 `deploymentMode = "3p"` 到 Claude 与 Claude-3p 两个目录，
+ * 并在 `configLibrary/<DESKTOP_PROFILE_ID>.json` 写入 TokenBuddy profile。
+ * 最后更新 `_meta.json` 把 `appliedId` 指向该 profile。
+ *
+ * @param configPath Claude Desktop 主配置（`claude_desktop_config.json`）绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Desktop 默认模型 ID
  */
 export function rewriteClaudeDesktop(configPath, proxyUrl, model) {
     try {
@@ -155,6 +183,13 @@ export function rewriteClaudeDesktop(configPath, proxyUrl, model) {
 }
 /**
  * Rewrite Openclaw settings.
+ *
+ * 写入 `api_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.openclaw/config.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Openclaw 默认模型 ID
  */
 export function rewriteOpenclaw(configPath, proxyUrl, model) {
     try {
@@ -180,6 +215,13 @@ export function rewriteOpenclaw(configPath, proxyUrl, model) {
 }
 /**
  * Rewrite Hermes settings.
+ *
+ * 在 `openai` 块下写入 `base_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.hermes/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Hermes 默认模型 ID
  */
 export function rewriteHermes(configPath, proxyUrl, model) {
     try {

package/dist/src/terminal-detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-detect.js","sourceRoot":"","sources":["../../src/terminal-detect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal-detect.js","sourceRoot":"","sources":["../../src/terminal-detect.ts"],"names":[],"mappings":"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"}

package/dist/src/terminal-image.d.ts

@@ -1,22 +1,63 @@
 type TerminalEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * 终端图片的展示方式：
+ * - `inline-iterm`：iTerm2 / WezTerm 等支持的 OSC 1337 内嵌图片
+ * - `inline-kitty`：Kitty 图形协议内嵌图片
+ * - `system-open`：调系统 `open` / `xdg-open` / `cmd /c start` 打开图片
+ * - `manual`：都不可用时让用户手动打开（通常附 fallbackCommand 提示）
+ */
 export type TerminalImageDisplayMethod = "inline-iterm" | "inline-kitty" | "system-open" | "manual";
+/**
+ * `displayTerminalImage()` 的返回：成功/失败 + 用的方法 + 提示消息。
+ * `displayed=false` 时调用方应回退到 `fallbackCommand` 提示用户。
+ */
 export interface TerminalImageDisplayResult {
+    /** 实际使用的展示方法 */
     method: TerminalImageDisplayMethod;
+    /** 是否真的把图片写到终端/打开了 */
     displayed: boolean;
+    /** 人类可读结果描述（给 init / doctor 用） */
     message: string;
+    /** 仅在 `displayed=false` 时存在：建议用户手动执行的命令 */
     fallbackCommand?: string;
 }
+/**
+ * `displayTerminalImage()` / `detectTerminalImageDisplay()` 的可注入依赖。
+ * 全部可选，缺省时使用真实 `process.env` / `process.platform` / `process.stdout`。
+ */
 export interface DisplayTerminalImageOptions {
+    /** 环境变量（默认 `process.env`） */
     env?: TerminalEnv;
+    /** 平台（默认 `process.platform`） */
     platform?: NodeJS.Platform;
+    /** stdout 是否为 TTY（默认 `process.stdout.isTTY`） */
     stdoutIsTTY?: boolean;
+    /** 写入 escape sequence 的方法（默认 `process.stdout.write`） */
     write?: (chunk: string) => void;
+    /** 调起子进程执行 system-open 命令的方法（默认 `child_process.spawn`） */
     runCommand?: (command: string, args: string[]) => Promise<void>;
+    /** 文件存在性检查（默认 `fs.existsSync`） */
     fileExists?: (filePath: string) => boolean;
+    /** 文件读取方法（默认 `fs.readFileSync`） */
     readFile?: (filePath: string) => Buffer;
 }
 type InlineImageProtocol = "iterm" | "kitty";
+/**
+ * 仅检测当前终端是否支持某种内嵌图片协议（Kitty / iTerm2）。
+ * 用于上层在展示前先决策"要不要走内嵌"而不直接写入任何输出。
+ *
+ * @param options 可注入依赖（env / platform / stdoutIsTTY）
+ * @returns 支持的内嵌协议；不支持时返回 `undefined`
+ */
 export declare function detectTerminalImageDisplay(options?: DisplayTerminalImageOptions): InlineImageProtocol | undefined;
+/**
+ * 把本地图片文件展示到终端：优先内嵌（Kitty / iTerm2），其次 system-open，最后 manual。
+ * 不会抛异常；任何错误都会转成 `TerminalImageDisplayResult { displayed: false }`。
+ *
+ * @param filePath 本地图片绝对路径
+ * @param options 可注入依赖
+ * @returns 展示结果（含 method / displayed / message / fallbackCommand）
+ */
 export declare function displayTerminalImage(filePath: string, options?: DisplayTerminalImageOptions): Promise<TerminalImageDisplayResult>;
 export {};
 //# sourceMappingURL=terminal-image.d.ts.map

package/dist/src/terminal-image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-image.d.ts","sourceRoot":"","sources":["../../src/terminal-image.ts"],"names":[],"mappings":"AAIA,KAAK,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEhE,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,cAAc,GACd,aAAa,GACb,QAAQ,CAAC;AAEb,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,0BAA0B,CAAC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED,KAAK,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AA8E7C,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,mBAAmB,GAAG,SAAS,CAKjC;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC,CAmErC"}
+{"version":3,"file":"terminal-image.d.ts","sourceRoot":"","sources":["../../src/terminal-image.ts"],"names":[],"mappings":"AAIA,KAAK,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,cAAc,GACd,aAAa,GACb,QAAQ,CAAC;AAEb;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB;IAChB,MAAM,EAAE,0BAA0B,CAAC;IACnC,sBAAsB;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6BAA6B;IAC7B,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,kCAAkC;IAClC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED,KAAK,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AA8E7C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,mBAAmB,GAAG,SAAS,CAKjC;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC,CAmErC"}

package/dist/src/terminal-image.js

@@ -65,9 +65,24 @@ function openCommandForPlatform(platform, filePath) {
     }
     return undefined;
 }
+/**
+ * 仅检测当前终端是否支持某种内嵌图片协议（Kitty / iTerm2）。
+ * 用于上层在展示前先决策"要不要走内嵌"而不直接写入任何输出。
+ *
+ * @param options 可注入依赖（env / platform / stdoutIsTTY）
+ * @returns 支持的内嵌协议；不支持时返回 `undefined`
+ */
 export function detectTerminalImageDisplay(options = {}) {
     return terminalSupportsInlineImages(options.env || process.env, options.stdoutIsTTY ?? Boolean(process.stdout.isTTY));
 }
+/**
+ * 把本地图片文件展示到终端：优先内嵌（Kitty / iTerm2），其次 system-open，最后 manual。
+ * 不会抛异常；任何错误都会转成 `TerminalImageDisplayResult { displayed: false }`。
+ *
+ * @param filePath 本地图片绝对路径
+ * @param options 可注入依赖
+ * @returns 展示结果（含 method / displayed / message / fallbackCommand）
+ */
 export async function displayTerminalImage(filePath, options = {}) {
     const fileExists = options.fileExists || fs.existsSync;
     const readFile = options.readFile || fs.readFileSync;

package/dist/src/terminal-image.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-image.js","sourceRoot":"","sources":["../../src/terminal-image.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal-image.js","sourceRoot":"","sources":["../../src/terminal-image.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenbuddy/tokenbuddy",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "TokenBuddy Client CLI and Daemon",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/src/buyer-store.ts

@@ -8,6 +8,10 @@ import { createModuleLogger } from "@tokenbuddy/logging";
 
 const logger = createModuleLogger("tb-proxyd");
 
+/**
+ * buyer 端缓存的 seller access token + 余额快照。
+ * v1.2 PR-fix：每次取出都校验 `expiresAt`，避免把过期 token 发给 seller 导致 401。
+ */
 export interface CachedToken {
   token: string;
   balanceMicros: number;
@@ -23,6 +27,10 @@ export interface CachedToken {
   expiresAt?: string;
 }
 
+/**
+ * 持久化的支付方式配置。
+ * `isDefault` 用于 `tb init` / 路由层在没有显式 method 时选默认。
+ */
 export interface PaymentConfig {
   method: string;
   enabled: boolean;
@@ -31,6 +39,9 @@ export interface PaymentConfig {
   updatedAt: string;
 }
 
+/**
+ * 待结算的 purchase 快照（buyer 端在 `/purchase/create` 之后、`/purchase/complete` 之前的临时状态）。
+ */
 export interface PendingPurchaseInput {
   purchaseId: string;
   sellerKey: string;
@@ -42,6 +53,9 @@ export interface PendingPurchaseInput {
   expiresAt?: string;
 }
 
+/**
+ * 完成态 purchase 的账本输入。`paymentReference` 会被 hash 之后落库（不存明文）。
+ */
 export interface PurchaseLedgerInput {
   purchaseId: string;
   sellerKey: string;
@@ -54,6 +68,10 @@ export interface PurchaseLedgerInput {
   completedAt?: string;
 }
 
+/**
+ * `tb doctor` 与审计日志消费的"安全版" purchase 账本条目。
+ * 关键差异：`paymentReference` 已 hash 化为 `paymentReferenceHash`，永不暴露明文。
+ */
 export interface SafePurchaseLedgerEntry {
   purchaseId: string;
   sellerKey: string;
@@ -67,6 +85,10 @@ export interface SafePurchaseLedgerEntry {
   completedAt?: string;
 }
 
+/**
+ * buyer 端单次推理请求的账本输入。
+ * `prompt` / `response` 在落库前会 hash，原始内容永不落盘。
+ */
 export interface InferenceLedgerInput {
   requestId: string;
   sellerKey: string;
@@ -86,6 +108,10 @@ export interface InferenceLedgerInput {
   response?: string;
 }
 
+/**
+ * `tb doctor` 与审计日志消费的"安全版"推理账本条目。
+ * 关键差异：`prompt` / `response` 已 hash 化为 `promptHash` / `responseHash`。
+ */
 export interface SafeInferenceLedgerEntry {
   requestId: string;
   sellerKey: string;
@@ -106,6 +132,10 @@ export interface SafeInferenceLedgerEntry {
   createdAt: string;
 }
 
+/**
+ * seller token 余额快照的入参。
+ * 每次推理后由 `BuyerStore.recordTokenBalance` 调用，作为路由决策的"最近一次真实余额"。
+ */
 export interface TokenBalanceSnapshotInput {
   sellerKey: string;
   token?: string;
@@ -117,6 +147,9 @@ export interface TokenBalanceSnapshotInput {
   expiresAt?: string;
 }
 
+/**
+ * `BuyerStore.summary()` 的返回结构，用于 `tb doctor` 展示 DB 健康度。
+ */
 export interface BuyerStoreSummary {
   journalMode: string;
   paymentsCount: number;
@@ -127,6 +160,10 @@ export interface BuyerStoreSummary {
   daemonRuntimeConfigCount: number;
 }
 
+/**
+ * `tb init` 时记录的 provider 安装快照（用于后续 `tb rollback`）。
+ * `existed` 标记安装前文件是否已存在，避免回滚覆盖用户原始内容。
+ */
 export interface ProviderInstallSnapshot {
   providerId: string;
   files: Array<{
@@ -136,6 +173,10 @@ export interface ProviderInstallSnapshot {
   }>;
 }
 
+/**
+ * provider 维度运行时配置（由 `tb init` / `tb config` 写入）。
+ * 存的是各 provider（如 opencode / cline）需要的 model mapping 等。
+ */
 export interface ProviderRuntimeConfigRecord<T = unknown> {
   providerId: string;
   config: T;
@@ -143,6 +184,10 @@ export interface ProviderRuntimeConfigRecord<T = unknown> {
   updatedAt: string;
 }
 
+/**
+ * 守护进程维度运行时配置（按 `configKey` 命名空间）。
+ * 比如 `seller_routing` / `prewarm` / `inference` 等 daemon 子系统的配置。
+ */
 export interface DaemonRuntimeConfigRecord<T = unknown> {
   configKey: string;
   config: T;
@@ -150,6 +195,10 @@ export interface DaemonRuntimeConfigRecord<T = unknown> {
   updatedAt: string;
 }
 
+/**
+ * `BuyerStore` 构造选项。
+ * 优先用 `dbPath`（绝对路径），否则用 `root`（目录）+ 默认 `buyer-store.db`。
+ */
 export interface BuyerStoreOptions {
   root?: string;
   dbPath?: string;
@@ -177,6 +226,13 @@ function ensureDirForFile(filePath: string): void {
   }
 }
 
+/**
+ * 解析 buyer store 的 DB 路径。
+ * 优先级：`dbPath` → `TOKENBUDDY_BUYER_STORE` env → `~/.tokenbuddy-store/buyer-store.db`。
+ *
+ * @param options 解析选项
+ * @returns DB 文件绝对路径
+ */
 export function resolveBuyerStorePath(options: BuyerStoreOptions = {}): string {
   if (options.dbPath) {
     return options.dbPath;
@@ -185,6 +241,11 @@ export function resolveBuyerStorePath(options: BuyerStoreOptions = {}): string {
   return path.join(root, "buyer-store.db");
 }
 
+/**
+ * buyer 端 SQLite 持久化层。
+ * 维护：支付配置、pending purchase、purchase 账本、inference 账本、provider / daemon runtime config、token 余额快照。
+ * 内部用 SHA256 摘要替代明文敏感字段（prompt / response / paymentReference / token）。
+ */
 export class BuyerStore {
   private db: DatabaseSync;