服务端客户端

当前导出与方法

• setupPayment({ customerId, requestId, currency, makeDefault })

  权限billing:write

  创建独立银行卡设置；不产生订阅、权益或用量扣款授权。

  返回 { setup }

• readPaymentSetup({ customerId, setupId })

  权限billing:read

  核对原设置的实际渠道结果，重试不会重复收费。

  返回 { setup }

• listSubscriptions({ customerId?, entityId?, productId?, provider?, status?, cursor?, limit? })

  权限billing:read

  按来源和服务端游标分页查询订阅，保留各渠道合同。

  返回 { subscriptions }

• listPurchases({ customerId?, entityId?, productId?, provider?, status?, cursor?, limit? })

  权限billing:read

  读取已验证购买记录和原币种金额；历史购买不等同于当前权益。

  返回 { purchases }

• listSubscriptionConflicts({ customerId?, status?, cursor?, limit? })

  权限billing:read

  查询互斥主套餐的实际付款冲突和阻挡会员。

  返回 { conflicts }

• retrySubscriptionConflict({ customerId, orderId })

  权限billing:write

  按原订单恢复交付；仍受阻时返回 blocked，不创建第二笔付款。

  返回 { resolution }

• manageSubscriptionTrial({ customerId, requestId, action, reason, ...trialParameters })

  权限billing:write

  启动、延长或结束试用；商店来源返回管理指引，不伪造生效。

  返回 { trial }

• readSubscriptionTrial({ customerId, operationId })

  权限billing:read

  恢复原试用操作，必要时核对 Stripe，保留原激活依据。

  返回 { trial }

• previewSubscriptionBatch({ customerId, requestId, targets })

  权限billing:write

  按真实渠道容器分组报价；ready 为 false 时用原请求继续预览。

  返回 { batch }

• confirmSubscriptionBatch({ customerId, batchId })

  权限billing:write

  接受固定目标；保留成功组并恢复未完成组，partial 不能视为全部完成。

  返回 { batch }

• readSubscriptionBatch({ customerId, batchId })

  权限billing:read

  读取原批次逐组状态；读取不接受报价、不发起新的渠道操作。

  返回 { batch }

• abandonSubscriptionBatch({ customerId, batchId })

  权限billing:write

  仅放弃未接受的批次；已提交的渠道操作继续按原任务恢复。

  返回 { batch }

• verifySubscriptions({ customerId })

  权限billing:read

  只读核对当前 App／环境的客户合同与 Stripe Sandbox。返回一致、差异或证据不足，不收费、不修复、不刷新账本。

  返回 { verification }

• previewRefund({ customerId, requestId, membershipId, purchaseId, lines, entitlementAction })

  权限billing:read

  按原始付款和发票明细冻结退款报价及权益规则。

  返回 { quote }

• refund({ customerId, operationId })

  权限billing:write

  确认原退款操作；重试恢复原渠道尝试。

  返回 { operation }

• readRefund({ customerId, operationId })

  权限billing:read

  读取并恢复已有退款，不重复建立渠道退款。

  返回 { operation }

• readBillingInvoice({ customerId, invoiceId, after, limit })

  权限billing:read

  读取完整已验证明细，按 nextCursor 分页；不会收费。

  返回 { detail }

• readCreditStatement({ customerId, from, to, entityId?, snapshotAt, after, limit })

  权限credits:read

  范围上限 366 天；首屏 snapshotAt/after 为 null，后续沿用原快照和完整游标。

  返回 { statement }

• previewUpdate({ customerId, requestId, membershipId, timing, change })

  权限billing:read

  按明确会员合同固定套餐或席位报价，保留同订阅的其他套餐。

  返回 { quote }

• update({ customerId, operationId })

  权限billing:write

  确认固定报价并恢复原收费尝试；实际已验证付款决定交付。

  返回 { operation }

• readSubscriptionUpdate({ customerId, operationId })

  权限billing:read

  读取变更状态；待付款、下期计划和已生效均保留原操作身份。

  返回 { operation }

• manageBalanceGrant({ customerId, command })

  权限credits:manage

  创建独立周期或一次赠送，按 requestId 与 revision 调整剩余余额、修改到期日或撤销规则。仅服务端 credits:manage；不会修改付款事实。

  返回 { grant }

• listBalanceGrants({ customerId, after, limit })

  权限credits:read

  读取客户及 Entity 的独立赠送规则、可用／预扣／已用余额；分页传回 nextCursor，最多 100 条。

  返回 { grants }

• previewAttach({ customerId, entityId?, requestId, plans, provider, currency, offerId? })

  权限billing:read

  为明确的客户保存固定报价，不发起付款；重试使用原 requestId。当前独立执行支持单套餐 Stripe／免费购买，以及同连接、币种、收费周期的多个付费 Stripe 套餐；多套餐暂不支持试用或席位。

  返回 { quote }

• attach({ customerId, operationId })

  权限billing:write

  客户审阅并接受报价后确认；重试复用 operationId 和原订单，不需要 Funnel。

  返回 { operation }

• restoreNativePurchase({ customerId, requestId, provider, purchaseIntentId, productId, signedTransaction?, purchaseToken? })

  权限billing:write

  按已验证的商店交易恢复同一购买与交付；恢复不会再次赠送额度。

  返回 { restore }

• readAiPricing({ entitlementId })

  权限credits:read

  读取当前功能模型价格和加价配置。

  返回 { configuration }

• readBalanceSource({ customerId, sourceId })

  权限credits:read

  读取套餐当前窗口可用、预扣及已消费余额。

  返回 { balance }

• adjustBalance({ customerId, command })

  权限credits:manage

  按 expectedAvailable 校验后增减或设置套餐余额；同一 requestId 安全重试。

  返回 { balance }

• readUsage({ customerId, query })

  权限credits:read

  读取非消耗型功能的容量和实际占用。

  返回 { usage }

• setUsage({ customerId, command })

  权限credits:manage

  按 expectedRevision 原子同步实际占用，可减小或超过套餐容量。

  返回 { usage }

• readSubscriptionOperation({ customerId, operationId })

  权限billing:read

  恢复已接受操作的付款与交付，不生成新渠道尝试。

  返回 { operation }

• manageBillingLimits({ customerId, command })

  权限billing:write

  可信服务端按当前修订设置客户或 Entity 的用量限制、提醒或 control: overage 超额规则，重试复用 requestId。超额规则包含 allowed、overageLimit、skipOverageBilling 和 UTC 窗口；Entity 覆盖客户规则，删除后恢复继承。付款授权仍由客户本人确认。

  返回 { controls }

• getOrCreateCustomer(input)

  权限customers:write

  用宿主已验证的 externalUserId 查找或创建客户；重试不覆盖现有资料。邮箱不作为身份。可选 fingerprint 为宿主采集的设备标识，只保存按环境加盐的哈希，首次记录后不再替换。也可以只传邮箱预建客户（例如先签约、后注册）；用户注册后带 externalUserId 和相同邮箱调用即就地认领，套餐和余额保留，只补上 ID。只传已验证的邮箱，否则他人可用该邮箱领走预建客户。

  返回 { customer, created }

• getCustomer({ lookup }) / listCustomers(filters)

  权限customers:read

  按明确的 id 或 externalUserId 读取；列表先按当前客户筛选条件过滤再分页。

  返回 Customer response

• updateCustomer({ lookup, revision, requestId, patch })

  权限customers:write

  更新已提供的资料和 attributes；用 removeAttributes 删除属性、tagChanges 增减标签。保存当前 revision 与原 requestId，冲突后重新读取。

  返回 Customer response

• createCustomerSession(customerId)

  权限sessions:create

  为宿主真实登录用户对应的 Indiana 客户签发短期会话。客户 ID 来自可信映射，不来自浏览器参数。

  返回 { customerToken, expiresAt }

• renewCustomerSession(input) / revokeCustomerSessions(input)

  权限sessions:create

  宿主重新验证登录后续期或撤销；撤销需要 sessions:create。reset 只清除 SDK 内存。

  返回 Session response

• createGuestToken()

  服务端生成游客凭证，以 HttpOnly cookie 保存，创建重试复用原凭证。

  返回 gg_gc_ token

• createGuestCustomer(input) / resumeGuestSession(input) / claimGuestCustomer(input)

  权限sessions:create

  游客创建、恢复与登录认领分别需要对应会话或 customers:write 权限。认领的 externalUserId 必须来自真实登录，商店购买前必须完成认证。创建游客可附带 fingerprint；合并到已有客户时，对方没有设备记录才沿用游客的。

  返回 Guest/session response

• checkEntitlement({ customerId, requirement, commerce?, paywallId? })

  权限entitlements:read

  后续源码入口，已发布 npm 0.0.1 不含此方法，需匹配 SDK 构建／发布及服务部署。检查权益并推荐商品，不执行扣量或自动付款。客户 ID 来自宿主已验证的登录。

  返回 { check }

• readHoldings({ customerId })

  权限entitlements:read

  读取当前客户会员与余额；金额保持十进制字符串，已有会员固定合同版本。

  返回 { holdings }

• readLedger({ customerId, query })

  权限credits:read

  全历史筛选后分页；保留完整 nextCursor，改变过滤条件时清空游标。

  返回 { ledger }

• quoteBalance({ customerId, command })

  权限credits:read

  command.operation 为 quote；报价不扣量，不替代原子消费。

  返回 { quote }

• mutateBalance({ customerId, command })

  权限credits:consume

  统一消费、预扣、确认、释放及原价退款。每个动作保留原 idempotencyKey 和输入；退款另外需要 credits:manage。

  返回 { receipt }

• readSeats(input) / manageSeat(input)

  权限customers:read

  读取已购买容量并分配真实成员；分配需要 billing:write，收费容量变更在 Funnel 确认。

  返回 Seat response

• manageUsageEntity(input) / readCreditAnalytics(input) / readUsageAnalytics(input)

  权限credits:manage

  管理可信客户的用量范围；分析读取需要 credits:read，不能用客户端传入的付费客户身份授予权限。

  返回 Usage entity / analytics response

• submitUsageBatch(input) / readUsageBatch(input)

  权限credits:consume

  逐项保持幂等收据并持久处理；进度读取需要 credits:read。

  返回 Batch response

• grantOffer({ customerId, couponId, requestId })

  权限offers:grant

  可信后端发放优惠；服务端校验当前范围、规则与库存，重试复用 requestId。界面领取使用 Funnel 的 claim_offer 节点。

  返回 Offer response

AI 模型计价

• createConfiguredAiPricing(client, { entitlementId })

  权限credits:read

  读取当前 App／环境的当前模型价格与加价配置；保存新配置后重新创建 pricing。已保存报价不重新计价。接入与恢复见 AI Token 指南。

  返回 Promise<AI pricing helper>

• createOpenRouterUsageClient({ openRouter, pricing, client, reasoning, context, persist, mapTokens? }) / trackOpenRouterUsage(input)

  从独立 /openrouter 入口导入，宿主安装 @openrouter/sdk。包装 chat.send 并先保存真实用量和原报价再原子扣款。恢复使用原 generationId、usage、quote 和幂等键，不重跑模型。

  返回 OpenRouter client / persisted usage record

• createAiUsageMiddleware({ pricing, client, modelId, reasoning, context, persist, mapTokens? })

  AI SDK v7 自动采集生成及流式最终 Token。每次模型调用／工具步骤由 context 提供独立持久幂等键；persist 先保存真实用量和原报价，再消费余额。中断不推算 Token，扣款失败显式报错，按原报价重试扣款而不重跑模型。

  返回 LanguageModelV4Middleware

• createAiPricing(options?)

  仅可信服务端使用。从 Models.dev 读取当前模型价格，缓存 15 分钟；可设置默认、提供商、模型加价和自定义模型价格。计量权益必须配置为一微美元，积分池通过固定兑换率换算。

  返回 AI pricing helper

• pricing.quoteTokens({ modelId, tokens })

  提供七类互不重叠的 Token 数量；未使用的池填 0。报价固定价格、上下文阶梯、加价、数量和散列。缺失所需价格明确拒绝；显式免费价格保留真实 Token 的零费用事件。持久化原报价供任务重试。

  返回 Promise<AiTokenQuote>

• pricing.trackTokens(client, { customerId, entitlementId, entityId?, idempotencyKey, quote, properties? })

  权限credits:consume

  校验原报价并用一笔原子余额消费记录 Token 与模型价格。重试保留原报价和幂等键；退款按原消费价格。可手工传入真实用量，或使用 createAiUsageMiddleware 自动采集。

  返回 Promise<Balance mutation response>

• pricing.refreshPrices()

  清除价格缓存，下次报价重新读取。已保存报价、消费和退款保持原价格。

  返回 void

• aiTokenQuoteSchema.parse(value) / aiPriceSnapshotSchema.parse(value)

  校验当前持久化报价和价格快照；不会请求模型或修改余额。

  返回 Validated quote / price snapshot

Funnel 与商店恢复

• createFunnelDecisionClient(options).submit(input) / decide(input) / read(decisionId) / reportUsed(input)

  仅可信后端，具备 sessions:create 与 funnels:run。固定客户、Funnel 和原 requestId；submit 不等待完成，decide 等待最多 30 秒。接收不确定沿用原输入重试；已接受但未完成则 read 原 decisionId。reportUsed 只记录调用方报告，不发券、不收费。

  返回 Decision status / decision / usage report

• createFunnelOrchestrationClient(options).signal(input) / readResults(runId)

  仅后端 sessions:create 与 funnels:run。发送已声明自定义回执，重试保留 eventId 和数据；接收确认不表示已消费。读取已完成任务和已消费回执的结果，自定义回执不能确认付款。

  返回 Receipt acknowledgement / node results

• renewFunnelRun(options, { runId, customerId })

  具备 sessions:create 与 funnels:run 的后端为同一已识别客户续签运行凭证；不延长 runExpiresAt。浏览器不能自行续签或改变客户。

  返回 Renewed run credential

• createPaywallStartClient(options).start({ paywallId, requirement?, ...input })

  后续源码入口，已发布 npm 0.0.1 不含此导出。匹配 SDK／服务后，可信后端持久化原输入和 requestId，携带客户会话及明确付款渠道、币种。requirement 固定到本次运行；保留现有 Paywall 设计与版本。

  返回 FunnelRuntimeResponse

• createFunnelStartClient(options).start(input)

  服务端持久化原 start 输入和 requestId；source 明确选择 Funnel、Paywall 或发布触发点。需要 sessions:create 与 funnels:run。

  返回 FunnelRuntimeResponse

• createNativeReceiptClient(options).recover(command)

  仅当前订单：用后端 Key 加当前客户会话双鉴权提交 native_receipt，长期恢复不依赖 runToken，也不推进旧运行。需要 billing:write 与 funnels:run。

  返回 NativeReceiptResponse