@reachv2/sdk 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @reachv2/sdk
 
-Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4），现统一为 **34 个资源类 / 267 个资源方法**。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源（含商户入驻与商户控制台、通道/群发、邮件通道、效果追踪、SEO/GEO、内容规则与数据源）。
+Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer SDK（crm 域，18 资源）与 aiops-saas SDK（social 域，5 资源）合并而来（P2.4），现统一为 **37 个资源类 / 287 个资源方法**。一个客户端覆盖客服 / 销售引导、社群维护与社媒运营全部资源（含商户入驻与商户控制台、通道/群发、邮件通道、计费与配额、效果追踪、SEO/GEO、内容规则与数据源）。
 
 - 运行时：Node.js >= 18（ESM）
 - 类型：完整 TypeScript 类型定义（自带 `dist/index.d.ts`）
@@ -8,7 +8,7 @@ Reach（reach.codes）统一平台的官方 TypeScript SDK —— 由 aiservicer
 
 ## 文档
 
-- **[API Reference](docs/API-REFERENCE.md)**（P2.6，v0.3.0 补 P-REACH 四域）：全部 27 个资源类 + `ReachClient` 共 **203 个资源方法**（另含 `ReachClient.setToken` / `request`）的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
+- **[API Reference](docs/API-REFERENCE.md)**（P2.6，v0.3.0 补 P-REACH 四域，v0.4.0 补商户/通道，v0.5.0 补计费/配额）：全部 37 个资源类 + `ReachClient` 共 **287 个资源方法**（另含 `ReachClient.setToken` / `request`）的签名 / 端点 / 参数 / 返回类型 / 错误 / 示例，与 `sdk/src` 源码一一对应。
 
 ## 安装
 
@@ -143,7 +143,7 @@ const client = new ReachClient({
 
 | 资源 | 主要能力 | API 域 |
 |------|----------|--------|
-| `client.agents` | **统一 Agent 入口**（AgentApi）：调用方 agent（list/get/capabilities/chat/prepareTransaction）+ AgentX 链上市场/订阅/状态/用量/发布/技能 + 市场 run/clone | 双域 |
+| `client.agents` | **统一 Agent 入口**（AgentApi）：调用方 agent（list/get/capabilities/chat/prepareTransaction）+ 市场搜索（listMarketplace → `/api/agents/marketplace/search`）+ 市场 run/clone | 双域 |
 | `client.project` | 项目 CRUD、列表 | Gateway |
 | `client.bot` | Bot（客服/销售/交易/自定义）CRUD、启停、统计 | Gateway |
 | `client.knowledge` | 知识文档 CRUD、推荐 | Gateway |
@@ -151,7 +151,7 @@ const client = new ReachClient({
 | `client.conversation` | 对话记录与消息 | Gateway |
 | `client.transaction` | 交易意图解析/构造/模拟、协议/合约/calldata 查询 | Gateway |
 | `client.chat` | 服务端对话（含 function calling tools、A2A 编排） | Server |
-| `client.lightrag` | RAG Key 管理 + 文档 CRUD + 查询（per-user namespace） | Gateway |
+| `client.lightrag` | RAG Key 管理 + 文档 CRUD + 查询（per-user namespace；平台共享 namespace `market` / `onchain` 只读可查） | Gateway |
 | `client.scheduledTasks` | 主 agent 定时任务管理 | Server |
 | `client.internal` | 企业内 Agent：企业级共享知识库 + 监控连接器/事件（`internal` bot） | Server |
 | `client.abis` | 商户租户合约 ABI 管理：list/add/remove（交易 agent 上传 ABI 后即可按函数构造链上调用） | Server |
@@ -189,11 +189,24 @@ const client = new ReachClient({
 > 或接受商户邀请（`client.auth.acceptMerchantInvite(token)`），再 `setToken(返回的 accessToken)`。
 > 商户域直接返回 db 行（多为 snake_case），与网关 `/api/v1` 的 camelCase 不同。
 
+### 计费 / 配额 — P1（v0.5.0 新增）
+
+| 资源 | 主要能力 | API 域 |
+|------|----------|--------|
+| `client.billing` | **社媒域计费（BillingResource）**：套餐 / Token 包 / 价格（公开）、Token 包购买（Stripe Checkout，未配置时落 pending）、Customer Portal、浏览器实例配额与购买流水（7 方法） | Server |
+| `client.sharedBilling` | **统一计费（SharedBillingResource）**：订阅列表 / 当前订阅与本月用量、用量记账、Token 包购买（支持推广余额抵扣）、加密收款（通道 / 下单 / 列表 / 详情 / 取消 / 确认）（12 方法） | Server |
+| `client.quota` | **社媒域本月配额（QuotaResource）**：`copywriting` / `tts` / `video` / `poster` 的 limit / used / remaining / allowed（1 方法） | Server |
+
+> 两个计费资源路径不同：`client.billing` → `/api/billing/*`（社媒域），`client.sharedBilling` → `/api/shared/billing/*`（统一账本）。
+> 订阅 / 用量 / 加密收款需 **账户 JWT + 租户成员**，`tenantId` 显式传参；`plans` / `token-packs` / `prices` / `crypto/methods` 公开。
+> 已退役端点未封装：`POST /api/billing/checkout` 与 `POST /api/shared/billing/subscriptions` 恒 410（新购走 `/api/seats`）；
+> `webhook` / `payments-events` 为服务端验签回调，不属于 SDK 调用面。
+
 > crm 客服指标（原 `client.analytics`）与社媒运营看板（原 `client.dashboard`）已统一为 `client.dashboard`（DashboardApi）；AgentX（原 `client.agentx`）与社媒 Agent 市场已统一为 `client.agents`（AgentApi）。
 
 ## 统一入口说明
 
-- **AgentApi（`client.agents`）**：唯一 Agent 入口（P2.4.3）。吸收 S agent（网关 `/api/v1/agents/*`：list/get/capabilities/chat/prepareTransaction）、S agentx（server `/api/agentx/*` + `/api/merchant/*`：市场/计划/订阅/状态/用量/上下文/发布/技能）与 A agents（server `/api/agents/*`：run/clone，marketplace→listMarketplace）。统一 Agent 资源模型见 REACH_MERGE_PLAN A.2.3/A.2.5。
+- **AgentApi（`client.agents`）**：唯一 Agent 入口（P2.4.3）。吸收 S agent（网关 `/api/v1/agents/*`：list/get/capabilities/chat/prepareTransaction）、市场（server `/api/agents/marketplace/search`：listMarketplace）与 A agents（server `/api/agents/*`：run/clone）。`/api/agentx/*` 服务端未挂载，相关方法已于 v0.4.0 移除。统一 Agent 资源模型见 REACH_MERGE_PLAN A.2.3/A.2.5。
 - **DashboardApi（`client.dashboard`）**：唯一看板入口（P2.4.4）。crm 域（`global` / `dashboard(projectId)` / `botMetrics` / `summaryByUser`）+ social 域（`overview` / `quota` / `trend`）。
 
 ## Function Calling（工具回调）
@@ -214,7 +227,7 @@ npm test          # node --test，覆盖 test/*.test.mjs
 | 测试文件 | 覆盖 |
 |----------|------|
 | `test/client.test.mjs` | ReachClient 核心行为：构造校验（`MISSING_AUTH`）、认证 Header、双 base 路由、body 序列化、错误语义 |
-| `test/resources.test.mjs` | **全量** 34 资源类 267 方法的 method / path / body 断言（要求每个方法至少被一条用例覆盖） |
+| `test/resources.test.mjs` | **全量** 37 资源类 287 方法的 method / path / body 断言（要求每个方法至少被一条用例覆盖） |
 | `test/smoke.test.mjs` | 导出面 + 资源方法面快照 |
 
 > 测试跑 **`dist/` 产物**，改完 `src/` 必须先 `npm run build`。

package/dist/client.d.ts

@@ -33,6 +33,9 @@ import { TeamResource } from "./resources/team.js";
 import { MerchantResource } from "./resources/merchant.js";
 import { ChannelAdminResource } from "./resources/channel-admin.js";
 import { EmailChannelResource } from "./resources/email-channel.js";
+import { BillingResource } from "./resources/billing.js";
+import { SharedBillingResource } from "./resources/shared-billing.js";
+import { QuotaResource } from "./resources/quota.js";
 export declare class ReachClient {
     private apiKey?;
     private token?;
@@ -73,6 +76,9 @@ export declare class ReachClient {
     merchant: MerchantResource;
     channelAdmin: ChannelAdminResource;
     emailChannel: EmailChannelResource;
+    billing: BillingResource;
+    sharedBilling: SharedBillingResource;
+    quota: QuotaResource;
     constructor(config: ReachClientConfig);
     /** Set token after wallet login */
     setToken(token: string): void;

package/dist/client.js

@@ -33,6 +33,9 @@ import { TeamResource } from "./resources/team.js";
 import { MerchantResource } from "./resources/merchant.js";
 import { ChannelAdminResource } from "./resources/channel-admin.js";
 import { EmailChannelResource } from "./resources/email-channel.js";
+import { BillingResource } from "./resources/billing.js";
+import { SharedBillingResource } from "./resources/shared-billing.js";
+import { QuotaResource } from "./resources/quota.js";
 export class ReachClient {
     constructor(config) {
         if (!config.apiKey && !config.token) {
@@ -78,6 +81,9 @@ export class ReachClient {
         this.merchant = new MerchantResource(this.requestServer.bind(this));
         this.channelAdmin = new ChannelAdminResource(this.requestServer.bind(this));
         this.emailChannel = new EmailChannelResource(this.requestServer.bind(this));
+        this.billing = new BillingResource(this.requestServer.bind(this));
+        this.sharedBilling = new SharedBillingResource(this.requestServer.bind(this));
+        this.quota = new QuotaResource(this.requestServer.bind(this));
     }
     /** Set token after wallet login */
     setToken(token) {

package/dist/index.d.ts

@@ -34,7 +34,13 @@ export { TeamResource } from "./resources/team.js";
 export { MerchantResource } from "./resources/merchant.js";
 export { ChannelAdminResource } from "./resources/channel-admin.js";
 export { EmailChannelResource } from "./resources/email-channel.js";
+export { BillingResource } from "./resources/billing.js";
+export { SharedBillingResource } from "./resources/shared-billing.js";
+export { QuotaResource } from "./resources/quota.js";
 export type { ReachClientConfig, BotType, AgentType, BotStatus, ChannelType, ChannelStatus, KnowledgeStatus, Pagination, PaginatedResponse, Project, ProjectCreateParams, ProjectUpdateParams, TransactionBotConfig, Bot, BotStats, BotCreateParams, BotUpdateParams, KnowledgeDoc, KnowledgeRecommendation, Channel, ChannelConfigureParams, Conversation, Message, ChatParams, ChatResponse, ChatToolDefinition, ChatToolFunction, DashboardData, BotMetrics, TxIntent, TxStep, PreparedTransaction, ContractInfo, ContractMethod, SimulationResult, DecodedCalldata, ProtocolSummary, ProtocolRegistryEntry, ChainDeployment, ProtocolAction, ParamHint, WalletNonce, WalletLoginParams, AuthAccount, AuthResult, MfaRequiredResult, CaptchaResponse, CaptchaAnswer, AgentXAgent, AgentXAgentDetail, AgentXMarketplaceResult, AgentXSubscriptionPlans, AgentXSubscriptionCheck, AgentXAgentContext, AgentXPublishParams, AgentXPublishResult, AgentXSkill, AgentXSkillCreateParams, AgentXAgentStatus, AgentXAgentUsage, AgentXSubscriptionDetail, AgentXSubscriptionList, ServerChatParams, ServerChatResponse, ChatUsage, ChatUsageSummary, AgentSummary, AgentListResult, AgentListParams, AgentChainInfo, AgentActionType, AgentCapabilities, AgentChatParams, AgentChatResult, LightRAGKeyInfo, LightRAGDocumentParams, LightRAGQueryParams, LightRAGQueryResult, LightRAGBatchItem, LightRAGBatchError, LightRAGBatchResult, GlobalAnalytics, AdminDashboard, AdminMerchant, AdminMerchantDetail, AdminBillingRecord, AdminCreateBillingParams, LlmSettings, LlmUpdateParams, ConversationTask, ConversationTaskStatus, ConversationSession, ConversationCapabilities, ConversationMessage, OrchestrationTaskParams, OrchestrateParams, OrchestratedTaskResult, OrchestrateResult, ScheduledTask, ScheduledTaskStatus, ScheduledTaskTriggerType, MonitorConnectorKind, EnterpriseDoc, MonitorConnector, MonitorEvent, MerchantAbi, MerchantAbiCreateParams, SimpleResult, TenantType, TenantMemberRole, TenantMemberStatus, Tenant, TenantMemberInfo, TenantInvite, PublicInviteInfo, InviteAcceptResult, MemberRoleUpdateResult, TransferOwnerResult, TeamMemberItem, TeamInviteResult, HealthInfo, MerchantOnboardParams, MerchantAuthResult, MerchantInviteInfo, EmailCodeSendResult, EmailCodeLoginParams, AccountMeResult, MerchantDashboardStats, MerchantTicket, MerchantTicketUpdateParams, MerchantProject, MerchantBot, MerchantProjectCreateParams, MerchantBotCreateParams, MerchantLlmConfig, MerchantLlmConfigInput, MerchantChain, MerchantChainAddParams, MerchantChainList, MerchantTeamRole, MerchantTeamMember, MerchantTeamResult, MerchantTeamMemberAddParams, MerchantTeamInviteParams, MerchantTeamInviteResult, ChannelActionResult, SendTextParams, TelegramSendFileParams, DiscordDmParams, DiscordDmOptInParams, MerchantGroupList, EmailMailbox, EmailMailboxCreateParams, EmailThreadList, } from "./types.js";
 export type { ApiKeyInfo, ApiKeyCreated } from "./resources/api-key.js";
 export type { SocialAccountCreateParams } from "./resources/accounts.js";
 export type { EmailSendParams, EmailPollParams, EmailInboundParams, } from "./resources/email-channel.js";
+export type { BillingPlan, BillingPlansResult, BillingTokenPack, BillingTokenPacksResult, BillingPrice, BillingPricesResult, TokenPackCheckoutResult, BrowserQuotaStatus, BrowserPackPurchase, BrowserPackPurchasesResult, } from "./resources/billing.js";
+export type { SharedSubscriptionPlanRef, SharedSubscription, SubscriptionQuotaResource, SubscriptionUsage, RecordUsageParams, UsageRecordResult, SharedTokenPackPurchaseParams, SharedTokenPackPurchaseResult, CryptoMethodsResult, CryptoOrderParams, CryptoOrder, CryptoOrderListResult, CryptoOrderConfirmParams, } from "./resources/shared-billing.js";
+export type { QuotaEntry, QuotaResourceKey, QuotaSummaryResult, } from "./resources/quota.js";

package/dist/index.js

@@ -34,3 +34,6 @@ export { TeamResource } from "./resources/team.js";
 export { MerchantResource } from "./resources/merchant.js";
 export { ChannelAdminResource } from "./resources/channel-admin.js";
 export { EmailChannelResource } from "./resources/email-channel.js";
+export { BillingResource } from "./resources/billing.js";
+export { SharedBillingResource } from "./resources/shared-billing.js";
+export { QuotaResource } from "./resources/quota.js";

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/lightrag.d.ts

@@ -9,6 +9,10 @@ type RequestFn = <T>(method: RequestMethod, path: string, body?: unknown) => Pro
  *
  * Per-user isolation: pass `namespace` to scope documents/queries to a specific user.
  * Defaults to botId (shared knowledge).
+ *
+ * Platform shared namespaces: Keel RAG 侧维护共享 namespace 白名单（默认 `market` / `onchain`，
+ * 用于跨租户只读的行情 / 链上知识）。查询时可直接作为 `namespace` 传入；
+ * 写入（insertDocument / insertDocuments）到这两个 namespace 会被 Keel 以只读拒绝。
  */
 export declare class LightRAGResource {
     private request;

package/dist/resources/lightrag.js

@@ -7,6 +7,10 @@
  *
  * Per-user isolation: pass `namespace` to scope documents/queries to a specific user.
  * Defaults to botId (shared knowledge).
+ *
+ * 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/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);
+    }
+}

package/dist/types.d.ts

@@ -570,13 +570,13 @@ export interface LightRAGKeyInfo {
 export interface LightRAGDocumentParams {
     text: string;
     file_name?: string;
-    /** Per-user namespace within a bot (defaults to botId = shared) */
+    /** Per-user namespace within a bot (defaults to botId = shared). 平台共享 namespace `market` / `onchain` 只读（仅 query 可用） */
     namespace?: string;
 }
 export interface LightRAGQueryParams {
     query: string;
     mode?: "mix" | "local" | "global" | "hybrid" | "naive";
-    /** Per-user namespace within a bot (defaults to botId = shared) */
+    /** Per-user namespace within a bot (defaults to botId = shared). 平台共享 namespace `market` / `onchain` 只读可查 */
     namespace?: string;
 }
 export interface LightRAGQueryResult {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reachv2/sdk",
-  "version": "0.4.0",
-  "description": "Reach unified REST API client library for TypeScript — crm 域（AgentApi/Project/Bot/Knowledge/Channel/Conversation/Transaction/Auth/Chat/ApiKey/LightRAG/Orchestration/ScheduledTasks/Internal/Abis/Admin）+ social 域（Content/Tts/Accounts/ContentPlans 内容计划/PublishPlans 发布计划/BrowserTemplates 流程模板/AiMedia 视频脚本/Effect 效果追踪/SeoGeo SEO-GEO 矩阵/ContentRules 内容规则引擎/DataSources 数据源）+ 商户域（Merchant 控制台/ChannelAdmin 通道与群发/EmailChannel 邮件通道）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
+  "version": "0.5.0",
+  "description": "Reach unified REST API client library for TypeScript — crm 域（AgentApi/Project/Bot/Knowledge/Channel/Conversation/Transaction/Auth/Chat/ApiKey/LightRAG/Orchestration/ScheduledTasks/Internal/Abis/Admin）+ social 域（Content/Tts/Accounts/ContentPlans 内容计划/PublishPlans 发布计划/BrowserTemplates 流程模板/AiMedia 视频脚本/Effect 效果追踪/SeoGeo SEO-GEO 矩阵/ContentRules 内容规则引擎/DataSources 数据源）+ 商户域（Merchant 控制台/ChannelAdmin 通道与群发/EmailChannel 邮件通道）+ 计费与配额（Billing 社媒计费/SharedBilling 统一订阅与加密收款/Quota 社媒配额）+ 统一 DashboardApi（crm/social 看板）+ 统一租户成员模型（Tenants/Team/Health，G-1~G-3）",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",