@reachv2/sdk 0.4.0 → 0.5.1

package/dist/resources/billing.d.ts

@@ -0,0 +1,142 @@
+import { RequestMethod } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/** 席位档位套餐（`/api/billing/plans` 返回的 shared.Plan 行） */
+export interface BillingPlan {
+    id: string;
+    name: string;
+    displayName?: string;
+    description?: string | null;
+    kind?: string;
+    seatCount?: number;
+    price?: number;
+    introPrice?: number | null;
+    introPeriods?: number;
+    interval?: string;
+    rail?: string;
+    llmTokensPerMonth?: number;
+    features?: unknown[];
+    active?: boolean;
+    [key: string]: unknown;
+}
+export interface BillingPlansResult {
+    plans: BillingPlan[];
+}
+/** 可购买 Token 包（`/api/billing/token-packs` 精简字段） */
+export interface BillingTokenPack {
+    id: string;
+    name: string;
+    tokens: number;
+    price: number;
+    cryptoAmount?: number;
+    sortOrder?: number;
+    active?: boolean;
+    [key: string]: unknown;
+}
+export interface BillingTokenPacksResult {
+    tokenPacks: BillingTokenPack[];
+}
+/** `/api/billing/prices` 的展示价格项 */
+export interface BillingPrice {
+    id: string;
+    name: string;
+    /** 展示用字符串，如 `$29` / `Free` */
+    price: string;
+    /** 最小货币单位（分） */
+    amount: number;
+    interval: string;
+    kind?: string;
+    seatCount?: number;
+    introPrice?: number | null;
+    introPeriods?: number;
+    features: unknown[];
+}
+export interface BillingPricesResult {
+    prices: Record<string, BillingPrice>;
+}
+/** Token 包购买结果（Stripe Checkout / 人工待开通 pending 单） */
+export interface TokenPackCheckoutResult {
+    id?: string;
+    tenantId?: string;
+    packId?: string | null;
+    packName?: string;
+    tokens?: number;
+    amountUsd?: number;
+    paymentMethod?: string;
+    status?: string;
+    /** 支付通道未配置时为 true（单已落 pending，待运营开通） */
+    manual?: boolean;
+    paymentId?: string;
+    sessionUrl?: string;
+    rail?: string;
+    pack?: Pick<BillingTokenPack, "id" | "name" | "tokens" | "price">;
+    [key: string]: unknown;
+}
+/** 浏览器实例配额概览 */
+export interface BrowserQuotaStatus {
+    /** 套餐基础实例数 */
+    base: number;
+    /** 加购实例数（有效期内 BrowserPack） */
+    pack: number;
+    total: number;
+    used: number;
+    remaining: number;
+    /** 最近一份加购包的到期时间（无加购为 null） */
+    packExpiresAt: string | null;
+    [key: string]: unknown;
+}
+/** 浏览器实例包购买流水（存量只读） */
+export interface BrowserPackPurchase {
+    id: string;
+    tenantId?: string;
+    packId?: string | null;
+    packName?: string;
+    instanceCount?: number;
+    amountUsd?: number;
+    status?: string;
+    periodStart?: string | null;
+    periodEnd?: string | null;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface BrowserPackPurchasesResult {
+    purchases: BrowserPackPurchase[];
+}
+/**
+ * BillingResource — 社媒域计费（Server API `/api/billing/*`）。
+ *
+ * - 公开：`plans` / `token-packs` / `prices`（无需登录）
+ * - JWT：`token-packs/purchase`（`authenticate`）、`portal`
+ * - API Key 或 JWT（只读）：`browser-packs/quota`、`browser-packs/purchases`（`authAny`）
+ *
+ * 注意：`POST /api/billing/checkout` 已退役（恒返回 410 PLATFORM_PLAN_RETIRED），未封装；
+ * 平台套餐新购走 `/api/seats`（不在 SDK 覆盖范围）。
+ */
+export declare class BillingResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 席位档位套餐列表（`{ plans }`，active + orderBy sortOrder） */
+    listPlans(): Promise<BillingPlansResult>;
+    /** 可购买 Token 包列表（`{ tokenPacks }`） */
+    listTokenPacks(): Promise<BillingTokenPacksResult>;
+    /** 套餐展示价格（`{ prices }`，按套餐名索引） */
+    getPrices(): Promise<BillingPricesResult>;
+    /**
+     * 购买 Token 包（Stripe 一次性 Checkout）。
+     * 支付通道未配置时返回 `manual: true` 的 pending 单，待运营手动开通。
+     */
+    purchaseTokenPack(packId: string): Promise<TokenPackCheckoutResult>;
+    /**
+     * Stripe Customer Portal 会话。
+     * 当前 Stripe SDK 未纳入服务端依赖 → 恒 503 `STRIPE_SDK_NOT_AVAILABLE`；
+     * 无有效平台订阅时 404 `No active subscription found`。
+     */
+    getPortal(): Promise<{
+        url?: string;
+        [key: string]: unknown;
+    }>;
+    /** 我的浏览器实例配额概览（基础 / 加购 / 总计 / 已用 / 剩余） */
+    getBrowserQuota(): Promise<BrowserQuotaStatus>;
+    /** 我的浏览器实例包购买流水（最近 50 条，存量只读） */
+    listBrowserPurchases(): Promise<BrowserPackPurchasesResult>;
+}
+export {};

package/dist/resources/billing.js

@@ -0,0 +1,52 @@
+/**
+ * BillingResource — 社媒域计费（Server API `/api/billing/*`）。
+ *
+ * - 公开：`plans` / `token-packs` / `prices`（无需登录）
+ * - JWT：`token-packs/purchase`（`authenticate`）、`portal`
+ * - API Key 或 JWT（只读）：`browser-packs/quota`、`browser-packs/purchases`（`authAny`）
+ *
+ * 注意：`POST /api/billing/checkout` 已退役（恒返回 410 PLATFORM_PLAN_RETIRED），未封装；
+ * 平台套餐新购走 `/api/seats`（不在 SDK 覆盖范围）。
+ */
+export class BillingResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 席位档位套餐列表（`{ plans }`，active + orderBy sortOrder） */
+    listPlans() {
+        return this.request("GET", "/api/billing/plans");
+    }
+    /** 可购买 Token 包列表（`{ tokenPacks }`） */
+    listTokenPacks() {
+        return this.request("GET", "/api/billing/token-packs");
+    }
+    /** 套餐展示价格（`{ prices }`，按套餐名索引） */
+    getPrices() {
+        return this.request("GET", "/api/billing/prices");
+    }
+    /**
+     * 购买 Token 包（Stripe 一次性 Checkout）。
+     * 支付通道未配置时返回 `manual: true` 的 pending 单，待运营手动开通。
+     */
+    purchaseTokenPack(packId) {
+        return this.request("POST", "/api/billing/token-packs/purchase", {
+            packId,
+        });
+    }
+    /**
+     * Stripe Customer Portal 会话。
+     * 当前 Stripe SDK 未纳入服务端依赖 → 恒 503 `STRIPE_SDK_NOT_AVAILABLE`；
+     * 无有效平台订阅时 404 `No active subscription found`。
+     */
+    getPortal() {
+        return this.request("GET", "/api/billing/portal");
+    }
+    /** 我的浏览器实例配额概览（基础 / 加购 / 总计 / 已用 / 剩余） */
+    getBrowserQuota() {
+        return this.request("GET", "/api/billing/browser-packs/quota");
+    }
+    /** 我的浏览器实例包购买流水（最近 50 条，存量只读） */
+    listBrowserPurchases() {
+        return this.request("GET", "/api/billing/browser-packs/purchases");
+    }
+}

package/dist/resources/browser.d.ts

@@ -0,0 +1,21 @@
+import { RequestMethod } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+export interface LiveSetCookiesParams {
+    /** 在线浏览器会话 ID */
+    sessionId: string;
+    /** Cookie 头字符串（`auth_token=...; ct0=...`）或 {name,value,domain,...} 数组 */
+    cookies: string | unknown[];
+    /** 可选平台编码，用于挑选期望的 Cookie 名 */
+    platform?: string;
+}
+/**
+ * Browser 资源 — 浏览器实时会话（/api/browser/live/*）。
+ * 对应 MCP 工具 browser_live_set_cookies。
+ */
+export declare class BrowserResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 向在线会话注入粘贴的 Cookie（免扫码登录；会话轮询登录态后自动保存） */
+    setLiveCookies(params: LiveSetCookiesParams): Promise<any>;
+}
+export {};

package/dist/resources/browser.js

@@ -0,0 +1,13 @@
+/**
+ * Browser 资源 — 浏览器实时会话（/api/browser/live/*）。
+ * 对应 MCP 工具 browser_live_set_cookies。
+ */
+export class BrowserResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 向在线会话注入粘贴的 Cookie（免扫码登录；会话轮询登录态后自动保存） */
+    setLiveCookies(params) {
+        return this.request("POST", "/api/browser/live/set-cookies", params);
+    }
+}

package/dist/resources/lightrag.d.ts

@@ -3,12 +3,21 @@ type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Pro
 /**
  * LightRAG Knowledge Base management.
  *
- * One botId = one LightRAG tenant.  External apps can:
+ * One botId = one namespace in the platform RAG tenant (`reach`).  External apps can:
  * - Manage API keys for direct LightRAG service access
  * - Insert/query/delete documents in the RAG vector store
  *
  * Per-user isolation: pass `namespace` to scope documents/queries to a specific user.
  * Defaults to botId (shared knowledge).
+ *
+ * namespace 必须限定在 Bot 自有空间（2026-10-24 起网关强校验）：
+ *   - `botId`（默认，Bot 共享知识库）
+ *   - `${botId}:<suffix>`（按用户/会话隔离的子空间）
+ *   - 查询额外允许平台只读 `market` / `onchain`；其他值一律 403。
+ *
+ * Platform shared namespaces: Keel RAG 侧维护共享 namespace 白名单（默认 `market` / `onchain`，
+ * 用于跨租户只读的行情 / 链上知识）。查询时可直接作为 `namespace` 传入；
+ * 写入（insertDocument / insertDocuments）到这两个 namespace 会被 Keel 以只读拒绝。
  */
 export declare class LightRAGResource {
     private request;

package/dist/resources/lightrag.js

@@ -1,12 +1,21 @@
 /**
  * LightRAG Knowledge Base management.
  *
- * One botId = one LightRAG tenant.  External apps can:
+ * One botId = one namespace in the platform RAG tenant (`reach`).  External apps can:
  * - Manage API keys for direct LightRAG service access
  * - Insert/query/delete documents in the RAG vector store
  *
  * Per-user isolation: pass `namespace` to scope documents/queries to a specific user.
  * Defaults to botId (shared knowledge).
+ *
+ * namespace 必须限定在 Bot 自有空间（2026-10-24 起网关强校验）：
+ *   - `botId`（默认，Bot 共享知识库）
+ *   - `${botId}:<suffix>`（按用户/会话隔离的子空间）
+ *   - 查询额外允许平台只读 `market` / `onchain`；其他值一律 403。
+ *
+ * Platform shared namespaces: Keel RAG 侧维护共享 namespace 白名单（默认 `market` / `onchain`，
+ * 用于跨租户只读的行情 / 链上知识）。查询时可直接作为 `namespace` 传入；
+ * 写入（insertDocument / insertDocuments）到这两个 namespace 会被 Keel 以只读拒绝。
  */
 export class LightRAGResource {
     constructor(request) {

package/dist/resources/quota.d.ts

@@ -0,0 +1,30 @@
+import { RequestMethod } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/** 单资源配额项 */
+export interface QuotaEntry {
+    /** 本月额度（0 = 未配置/不限） */
+    limit: number;
+    used: number;
+    remaining: number;
+    allowed: boolean;
+}
+/** `/api/quota/summary` 的输出 key（前端契约） */
+export type QuotaResourceKey = "copywriting" | "tts" | "video" | "poster";
+export interface QuotaSummaryResult {
+    /** 当前生效套餐名（无套餐时为 free） */
+    plan: string;
+    quotas: Record<QuotaResourceKey, QuotaEntry>;
+}
+/**
+ * QuotaResource — 社媒域本月配额（Server API `/api/quota/*`）。
+ *
+ * `GET /api/quota/summary` 支持 API Key 或 JWT（`authAny`），按登录主体所属租户统计。
+ * 注意：与网关侧 `dashboard.quota()`（`/api/v1/quota`，crm 域）不是同一端点。
+ */
+export declare class QuotaResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 本月各资源配额用量（copywriting / tts / video / poster） */
+    summary(): Promise<QuotaSummaryResult>;
+}
+export {};

package/dist/resources/quota.js

@@ -0,0 +1,15 @@
+/**
+ * QuotaResource — 社媒域本月配额（Server API `/api/quota/*`）。
+ *
+ * `GET /api/quota/summary` 支持 API Key 或 JWT（`authAny`），按登录主体所属租户统计。
+ * 注意：与网关侧 `dashboard.quota()`（`/api/v1/quota`，crm 域）不是同一端点。
+ */
+export class QuotaResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 本月各资源配额用量（copywriting / tts / video / poster） */
+    summary() {
+        return this.request("GET", "/api/quota/summary");
+    }
+}

package/dist/resources/seo-geo.d.ts

@@ -1,6 +1,32 @@
 import { RequestMethod } from "../types.js";
 import { QueryParams } from "./query.js";
 type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/** 业务类型（P11.7b）：决定生成哪套行业化 JSON-LD 模板；必须显式选择，不做推断 */
+export type BrandBusinessType = "organization" | "local_business" | "software_saas" | "product_ecommerce" | "website";
+/** 品牌档案创建入参（businessInfo 结构随 businessType 变化） */
+export interface BrandProfileInput {
+    name: string;
+    slogan?: string;
+    description?: string;
+    keywords?: string[];
+    competitors?: string[];
+    homepage?: string;
+    author?: string;
+    socialLinks?: Record<string, string>;
+    styleGuide?: string;
+    /** 缺省 organization */
+    businessType?: BrandBusinessType;
+    /**
+     * 行业化结构化资料；缺失必填项允许保存（该模板不会生成），
+     * 非法值 / 未知字段返回 400 INVALID_INPUT。
+     */
+    businessInfo?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/** 品牌档案更新入参（部分字段） */
+export type BrandProfilePatch = Partial<BrandProfileInput> & {
+    status?: "active" | "archived";
+};
 /**
  * SeoGeo 资源 — P-REACH 角色2 SEO/GEO 域：品牌档案 / 渠道集 / 内容矩阵 / GEO 资产。
  * 端点走 Server API（/api/seo-geo/*），与社媒域 MCP seo_geo_* 工具同源。
@@ -13,12 +39,12 @@ export declare class SeoGeoResource {
     catalog(): Promise<any>;
     /** 品牌档案列表（可按 status/q 过滤） */
     listBrands(params?: QueryParams): Promise<any>;
-    /** 创建品牌档案 */
-    createBrand(data: unknown): Promise<any>;
+    /** 创建品牌档案（businessType / businessInfo 决定行业化 JSON-LD 模板） */
+    createBrand(data: BrandProfileInput): Promise<any>;
     /** 品牌档案详情 */
     getBrand(id: string): Promise<any>;
-    /** 更新品牌档案（部分字段） */
-    updateBrand(id: string, patch: unknown): Promise<any>;
+    /** 更新品牌档案（部分字段）；换 businessType 未带 businessInfo 时旧资料会重置 */
+    updateBrand(id: string, patch: BrandProfilePatch): Promise<any>;
     /** 删除品牌档案（被矩阵引用时 409） */
     deleteBrand(id: string): Promise<any>;
     /** 渠道集列表（可按 status/q 过滤） */

package/dist/resources/seo-geo.js

@@ -18,7 +18,7 @@ export class SeoGeoResource {
     listBrands(params = {}) {
         return this.request("GET", `/api/seo-geo/brands${buildQuery(params)}`);
     }
-    /** 创建品牌档案 */
+    /** 创建品牌档案（businessType / businessInfo 决定行业化 JSON-LD 模板） */
     createBrand(data) {
         return this.request("POST", "/api/seo-geo/brands", data);
     }
@@ -26,7 +26,7 @@ export class SeoGeoResource {
     getBrand(id) {
         return this.request("GET", `/api/seo-geo/brands/${encodeURIComponent(id)}`);
     }
-    /** 更新品牌档案（部分字段） */
+    /** 更新品牌档案（部分字段）；换 businessType 未带 businessInfo 时旧资料会重置 */
     updateBrand(id, patch) {
         return this.request("PUT", `/api/seo-geo/brands/${encodeURIComponent(id)}`, patch);
     }

package/dist/resources/shared-billing.d.ts

@@ -0,0 +1,205 @@
+import { RequestMethod } from "../types.js";
+type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Promise<T>;
+/** 订阅关联的套餐摘要 */
+export interface SharedSubscriptionPlanRef {
+    id: string;
+    name: string;
+    displayName?: string;
+    llmTokensPerMonth?: number;
+}
+/** 平台/席位订阅行（`GET /api/shared/billing/subscriptions`） */
+export interface SharedSubscription {
+    id: string;
+    tenantId: string;
+    planId?: string | null;
+    planName: string;
+    scope?: "platform" | "seat" | string;
+    seatNo?: number | null;
+    agentKey?: string;
+    status?: string;
+    rail?: string;
+    autoRenew?: boolean;
+    currentPeriodStart?: string | null;
+    currentPeriodEnd?: string | null;
+    amountUsd?: number | null;
+    plan?: SharedSubscriptionPlanRef;
+    [key: string]: unknown;
+}
+/** 单资源配额（`/subscriptions/current` → quota.resources） */
+export interface SubscriptionQuotaResource {
+    quota: number;
+    used: number;
+    remaining: number | null;
+}
+/** 当前订阅 + 本月用量 + 统一 token 池 */
+export interface SubscriptionUsage {
+    subscription: SharedSubscription | null;
+    quota: null | {
+        plan: {
+            name: string;
+            llmTokensPerMonth: number;
+        };
+        usage: Record<string, {
+            quantity: number;
+            tokensUsed: number;
+        }>;
+        resources: Record<string, SubscriptionQuotaResource>;
+        tokensUsedThisMonth: number;
+        tokensRemaining: number;
+        seats: {
+            active: number;
+            monthlyQuota: number;
+            tokenBalance: number;
+            pool: number;
+        };
+    };
+}
+export interface RecordUsageParams {
+    tenantId: string;
+    /** 资源类型，如 `llm_tokens` / `content:generate` / `tts:synthesize` */
+    resourceType: string;
+    quantity?: number;
+    tokensUsed?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface UsageRecordResult {
+    id: string;
+    tenantId: string;
+    accountId?: string | null;
+    resourceType: string;
+    quantity: number;
+    tokensUsed?: number | null;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface SharedTokenPackPurchaseParams {
+    tenantId: string;
+    packId: string;
+    successUrl?: string;
+    cancelUrl?: string;
+    /** 用站内推广余额全额抵扣本人自购 */
+    usePartnerBalance?: boolean;
+}
+export interface SharedTokenPackPurchaseResult {
+    id?: string;
+    tenantId?: string;
+    packId?: string | null;
+    packName?: string;
+    tokens?: number;
+    amountUsd?: number;
+    paymentMethod?: string;
+    status?: string;
+    /** 支付通道未配置时为 true（pending 单待运营开通） */
+    manual?: boolean;
+    sessionUrl?: string;
+    paymentId?: string;
+    remark?: string;
+    [key: string]: unknown;
+}
+/** 已开放的加密收款通道（`{ enabled, chains }`） */
+export interface CryptoMethodsResult {
+    enabled: boolean;
+    chains: Array<Record<string, unknown>>;
+}
+export interface CryptoOrderParams {
+    tenantId: string;
+    /** 商品类型：plan / seat / seat_add / token_pack / browser_pack */
+    kind: string;
+    targetId: string;
+    chain: string;
+    asset: string;
+    payerWallet?: string;
+    seatCount?: number;
+    taxCountry?: string;
+}
+/** 加密订单对外视图（不含 enginePaymentId / receipt 原文） */
+export interface CryptoOrder {
+    orderId: string;
+    kind: string;
+    targetId: string;
+    targetName?: string;
+    chain: string;
+    chainId?: number | string;
+    assetSymbol: string;
+    assetAddress?: string;
+    decimals?: number;
+    payTo?: string;
+    amountWei?: string;
+    amountDisplay?: string;
+    amountUsd?: number;
+    seatCount?: number;
+    seatKind?: string | null;
+    periodStart?: string | null;
+    periodEnd?: string | null;
+    tax?: {
+        country: string | null;
+        rate: number;
+        amount: number;
+        inclusive: boolean;
+    };
+    pspFee?: number;
+    reserveAmount?: number;
+    netAmount?: number;
+    status: string;
+    txHash?: string | null;
+    creditedWei?: string | null;
+    expiresAt?: string;
+    createdAt?: string;
+    /** confirm 时订单已支付 */
+    alreadyPaid?: boolean;
+    /** confirm 时本次生效结果 */
+    activated?: unknown;
+    duplicate?: boolean;
+    [key: string]: unknown;
+}
+export interface CryptoOrderListResult {
+    orders: CryptoOrder[];
+}
+export interface CryptoOrderConfirmParams {
+    tenantId: string;
+    txHash: string;
+}
+/**
+ * SharedBillingResource — 统一计费（Server API `/api/shared/billing/*`）。
+ *
+ * 鉴权：订阅 / 用量 / 加密收款端点均要求 **账户 JWT**（`requireAuth`）+ 租户成员
+ * （`tenantId` 显式传参，服务端用登录账号校验成员身份）；`plans` / `token-packs` /
+ * `crypto/methods` 公开。
+ *
+ * 未封装：
+ * - `POST /subscriptions`（已退役，恒 410 PLATFORM_PLAN_RETIRED；新购走 `/api/seats`）
+ * - `POST /webhook` / `POST /payments-events`（Stripe/引擎回调，验签即认证，不属于 SDK 调用面）
+ */
+export declare class SharedBillingResource {
+    private request;
+    constructor(request: RequestFn);
+    /** 席位档位套餐列表（**裸数组**，与 `/api/billing/plans` 的 `{ plans }` 不同） */
+    listPlans(): Promise<Array<Record<string, unknown>>>;
+    /** 可购买 Token 包列表（**裸数组**，含 cryptoAmount / price 等全字段） */
+    listTokenPacks(): Promise<Array<Record<string, unknown>>>;
+    /** 租户平台订阅列表（含 plan 摘要，按创建时间倒序） */
+    listSubscriptions(tenantId: string): Promise<SharedSubscription[]>;
+    /** 当前订阅 + 本月用量 + 分资源配额 + 席位/token 池（无套餐且无席位时 subscription/quota 为 null） */
+    getCurrentSubscription(tenantId: string): Promise<SubscriptionUsage>;
+    /** 记录用量（统一账本；`llm_tokens` 的 token 数落在 quantity） */
+    recordUsage(params: RecordUsageParams): Promise<UsageRecordResult>;
+    /**
+     * 购买 Token 包（fiat Stripe Checkout；渠道未配置时落 pending 单并返回 `manual: true`）。
+     * `usePartnerBalance: true` 时用推广余额全额抵扣，成功即 completed。
+     */
+    purchaseTokenPack(params: SharedTokenPackPurchaseParams): Promise<SharedTokenPackPurchaseResult>;
+    /** 已开放的加密收款通道（链 + 稳定币；未开放返回 `enabled: false`） */
+    listCryptoMethods(): Promise<CryptoMethodsResult>;
+    /** 创建加密订单（返回 payTo / amountWei / 过期时间，用户链上转账后用返回的 orderId confirm） */
+    createCryptoOrder(params: CryptoOrderParams): Promise<CryptoOrder>;
+    /** 我的加密订单列表（读取时惰性把超时 pending 单置 expired） */
+    listCryptoOrders(tenantId: string): Promise<CryptoOrderListResult>;
+    /** 加密订单详情 */
+    getCryptoOrder(orderId: string, tenantId: string): Promise<CryptoOrder>;
+    /** 取消待付款订单（仅 pending/expired 可取消，已支付不可） */
+    cancelCryptoOrder(orderId: string, tenantId: string): Promise<CryptoOrder>;
+    /** 提交链上 txHash 换取引擎回执并生效 */
+    confirmCryptoOrder(orderId: string, params: CryptoOrderConfirmParams): Promise<CryptoOrder>;
+}
+export {};

package/dist/resources/shared-billing.js

@@ -0,0 +1,67 @@
+/**
+ * SharedBillingResource — 统一计费（Server API `/api/shared/billing/*`）。
+ *
+ * 鉴权：订阅 / 用量 / 加密收款端点均要求 **账户 JWT**（`requireAuth`）+ 租户成员
+ * （`tenantId` 显式传参，服务端用登录账号校验成员身份）；`plans` / `token-packs` /
+ * `crypto/methods` 公开。
+ *
+ * 未封装：
+ * - `POST /subscriptions`（已退役，恒 410 PLATFORM_PLAN_RETIRED；新购走 `/api/seats`）
+ * - `POST /webhook` / `POST /payments-events`（Stripe/引擎回调，验签即认证，不属于 SDK 调用面）
+ */
+export class SharedBillingResource {
+    constructor(request) {
+        this.request = request;
+    }
+    /** 席位档位套餐列表（**裸数组**，与 `/api/billing/plans` 的 `{ plans }` 不同） */
+    listPlans() {
+        return this.request("GET", "/api/shared/billing/plans");
+    }
+    /** 可购买 Token 包列表（**裸数组**，含 cryptoAmount / price 等全字段） */
+    listTokenPacks() {
+        return this.request("GET", "/api/shared/billing/token-packs");
+    }
+    /** 租户平台订阅列表（含 plan 摘要，按创建时间倒序） */
+    listSubscriptions(tenantId) {
+        return this.request("GET", `/api/shared/billing/subscriptions?tenantId=${encodeURIComponent(tenantId)}`);
+    }
+    /** 当前订阅 + 本月用量 + 分资源配额 + 席位/token 池（无套餐且无席位时 subscription/quota 为 null） */
+    getCurrentSubscription(tenantId) {
+        return this.request("GET", `/api/shared/billing/subscriptions/current?tenantId=${encodeURIComponent(tenantId)}`);
+    }
+    /** 记录用量（统一账本；`llm_tokens` 的 token 数落在 quantity） */
+    recordUsage(params) {
+        return this.request("POST", "/api/shared/billing/usage", params);
+    }
+    /**
+     * 购买 Token 包（fiat Stripe Checkout；渠道未配置时落 pending 单并返回 `manual: true`）。
+     * `usePartnerBalance: true` 时用推广余额全额抵扣，成功即 completed。
+     */
+    purchaseTokenPack(params) {
+        return this.request("POST", "/api/shared/billing/token-packs/purchase", params);
+    }
+    /** 已开放的加密收款通道（链 + 稳定币；未开放返回 `enabled: false`） */
+    listCryptoMethods() {
+        return this.request("GET", "/api/shared/billing/crypto/methods");
+    }
+    /** 创建加密订单（返回 payTo / amountWei / 过期时间，用户链上转账后用返回的 orderId confirm） */
+    createCryptoOrder(params) {
+        return this.request("POST", "/api/shared/billing/crypto/orders", params);
+    }
+    /** 我的加密订单列表（读取时惰性把超时 pending 单置 expired） */
+    listCryptoOrders(tenantId) {
+        return this.request("GET", `/api/shared/billing/crypto/orders?tenantId=${encodeURIComponent(tenantId)}`);
+    }
+    /** 加密订单详情 */
+    getCryptoOrder(orderId, tenantId) {
+        return this.request("GET", `/api/shared/billing/crypto/orders/${encodeURIComponent(orderId)}?tenantId=${encodeURIComponent(tenantId)}`);
+    }
+    /** 取消待付款订单（仅 pending/expired 可取消，已支付不可） */
+    cancelCryptoOrder(orderId, tenantId) {
+        return this.request("POST", `/api/shared/billing/crypto/orders/${encodeURIComponent(orderId)}/cancel`, { tenantId });
+    }
+    /** 提交链上 txHash 换取引擎回执并生效 */
+    confirmCryptoOrder(orderId, params) {
+        return this.request("POST", `/api/shared/billing/crypto/orders/${encodeURIComponent(orderId)}/confirm`, params);
+    }
+}