@tinkerlandai/indiana-sdk 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Release facts and artifact evidence: [SDK release ledger](../../docs/sdk-releases.md). Earlier personal-package versions are preserved in [@houzhen888/groove-grow history](../../docs/sdk-changelog-groove-grow.md). The two packages have independent version histories.
+
+## 0.0.1 — 2026-10-13
+
+- First organizational Beta under `@tinkerlandai/indiana-sdk`, replacing personal-package imports. Publish with the `beta` tag and pin `0.0.1` when installing.
+- Include browser, server, popup, OpenRouter and native-shell ESM entries. Private contracts remain bundled into the SDK.
+- Add browser/server `createFeatureClient` with scoped cached configuration and synchronous GrowthBook evaluation. Generic decisions return immutable `value` JSON with live validity `state`; trusted inputs use `attributes`.
+- Replace customer `metadata` / `tags` inputs with `attributes`, `removeAttributes` and incremental `tagChanges`. No obsolete-format compatibility reader is included.
+- Refine Funnel decision recovery and host resume/close behavior. Include current subscription, native-receipt and prepaid Feature quantity contracts, with the matching generated native host.
+- Include GrowthBook MIT attribution and synchronize installation examples and downloadable archives.
+
+Upgrade imports and the matching server/database deployment together. This npm release does not deploy Grow or publish the separate Swift/Kotlin packages. Installed-artifact and offline checks do not certify real payments, native stores or deployed behavior. Browser validation was explicitly omitted at the user's request.

package/README.md

@@ -1,3 +1,307 @@
-# Temporary Holding Version
+# @tinkerlandai/indiana-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Indiana 的框架无关 Web / TypeScript SDK。组织包首版为 `0.0.1`，以 `beta` 标签分发；升级前确认服务端与数据库迁移匹配。不提供旧接口或数据格式兼容，变更见 [Changelog](CHANGELOG.md)。
+
+```sh
+npm install @tinkerlandai/indiana-sdk@0.0.1
+```
+
+安装请固定 `0.0.1`。新组织包与旧个人包 `@houzhen888/groove-grow` 的版本空间独立，不能按版本号大小判断升级关系。完整发布记录与核对时间见 [发布总账](../../docs/sdk-releases.md)，本版范围与验收边界见本文末尾。
+
+服务端 Key、Customer Token 与控制台登录的区别、逐请求查库校验、权限及撤销轮换，见 [服务端鉴权](../../docs/server-authentication.md)。安装与发布状态见 [自助接入](../../docs/sdk-selfserve.md)。
+
+一个包提供浏览器、可信后端与渲染入口，不依赖 React、Next.js 或 Supabase 客户端。内部 contracts 在打包时内联，接入方不需要安装私有工作区包。
+
+| 入口                                     | 用途                                                           |
+| ---------------------------------------- | -------------------------------------------------------------- |
+| `@tinkerlandai/indiana-sdk`              | 当前客户读取、Funnel 控制器与统一展示宿主                      |
+| `@tinkerlandai/indiana-sdk/server`       | 客户管理、Session 签发、账本写入与可信 Funnel 启动             |
+| `@tinkerlandai/indiana-sdk/openrouter`   | 可选 OpenRouter 用量集成，宿主需安装对应 peer dependency       |
+| `@tinkerlandai/indiana-sdk/popup`        | 纯屏幕渲染、清洗和编辑预览                                     |
+| `@tinkerlandai/indiana-sdk/native-shell` | 供 Grow 托管的原生 Funnel 壳生成纯设计资源，不含客户或运行凭据 |
+
+## 可信后端与客户身份
+
+```ts
+import { createGrooveServer } from "@tinkerlandai/indiana-sdk/server";
+const groove = createGrooveServer({
+  baseUrl: process.env.GROOVE_BASE_URL!,
+  apiKey: process.env.GROOVE_SECRET_KEY!,
+  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
+});
+const user = await requireSignedInUser(request);
+const { customer } = await groove.getOrCreateCustomer({
+  externalUserId: user.id,
+});
+const { customerToken } = await groove.createCustomerSession(customer.id);
+```
+
+Secret Key 只放在可信后端。浏览器提供的客户 ID 不能作为登录证明；客户 Token 仅交给该已登录用户，SDK 只在内存持有。每个 App／环境单独配置权限与允许来源。切换账号时关闭并销毁旧运行，丢弃旧客户凭据；迟到响应不能更新新身份。
+
+## 统一 Funnel
+
+```ts
+import { createFunnelStartClient } from "@tinkerlandai/indiana-sdk/server";
+const funnels = createFunnelStartClient({
+  baseUrl: process.env.GROOVE_BASE_URL!,
+  apiKey: process.env.GROOVE_SECRET_KEY!,
+  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
+});
+// 宿主在首次调用前持久保存整个 start 输入；响应丢失后原样重试。
+const result = await funnels.start({ ...retainedStartInput, customerToken });
+```
+
+`retainedStartInput` 包含 `source`、`requestId`，以及明确的 `commerce`、`locale`、`parameters`。`source` 选择 `funnel/id`、`paywall/id` 或已发布的 `trigger/key`。服务端 Key 需要 `sessions:create` 与 `funnels:run`。每个运行都属于一个客户：已登录用户用 `createCustomerSession` 的 `customerToken`；未登录访客先 `createGuestCustomer`，再用 `resumeGuestSession` 取得游客 `customerToken`。浏览器只接收这一运行的 `runToken`。独立 Paywall 使用系统维护的 Funnel。
+
+```ts
+import {
+  createFunnelRunController,
+  showFunnelRun,
+} from "@tinkerlandai/indiana-sdk";
+const client = createFunnelRunController({
+  baseUrl,
+  scope: { projectId, environment: "sandbox" },
+  runToken,
+});
+const handle = await showFunnelRun(container, {
+  client,
+  onAuthenticate: async () => obtainCurrentUserCustomerToken(),
+  onCheckout: ({ url }) => window.location.assign(url),
+  onOpenUrl: ({ url }) => window.location.assign(url),
+  onError: reportError,
+});
+```
+
+宿主实现登录与 Token 获取；取消认证返回 `null`。付款回跳后展示同一运行，服务端读取验证后的支付事实。点击、导航和宿主回调不能确认付款。
+
+控制器提供 `get`、`submit`、`retry`、`resume`、`identify`、`link`、`subscribe` 和 `reset`。变更命令包含当前 `nodeId`、`revision` 与稳定 `requestId`。超时保留 `pendingCommand`，先 `retry` 原命令；服务端已经持有中断命令时使用其 `pendingRequest.requestId` 恢复。原命令回执不能倒退新的观测状态。
+
+每个屏幕分别选择弹窗、面板、全屏或嵌入。屏幕按钮只产生出口，认证、领券、收费和会员变更由相应节点执行。账户、积分、会员和账单是屏幕中的客户组件；刷新、分页、过滤及预览只读。`destroy` 清理界面，`close` 才提交关闭命令。
+
+## JSON 决策与 Feature（当前源码）
+
+本版的通用 JSON 决策需要匹配的数据库迁移和 Workflow 部署。旧个人包 `@houzhen888/groove-grow@0.0.7` 使用发布时的旧契约；发布事实见 [发布总账](../../docs/sdk-releases.md)。
+
+```ts
+import { createFunnelDecisionClient } from "@tinkerlandai/indiana-sdk/server";
+const decisions = createFunnelDecisionClient({
+  baseUrl,
+  scope,
+  apiKey,
+  funnelId,
+});
+const decision = await decisions.decide({
+  requestId: retainedRequestId,
+  customerId,
+  attributes: {
+    tags: ["ad"],
+    isNeverPaid: true,
+    country: "US",
+    channel: "ads",
+  },
+});
+```
+
+可信后端提交完整 `attributes` JSON，业务可以自行提供付费历史、渠道等属性。结果的 `value` 是规则输出的任意 JSON；首次成功提交的结果（包括 null、false、0 或零优惠对象）固定在当前 allocationScopeId，后续属性变化不会重新计算。`state` 分别表示 active、expired 或 inactive；它随有效期和活动状态变化，value 保持不变。新的分配活动须显式更换 allocationScopeId。parameters、answers、results 是 Funnel 保留的上下文命名空间。
+
+每个新 requestId 保存查询日志，重试保留原 ID。查询不发券、不执行支付。采用后可选调用 `reportUsed({ eventId, decisionId, occurredAt, reference })`；它只记录调用方报告。超时后的 `FunnelDecisionTimeoutError` 保留 decisionId，可通过 read 继续读取。
+
+```ts
+const features = decisions.features({
+  attributes: { id: customerId, country: "US" },
+});
+await features.init(); // 下载当前 App/环境/Funnel 的配置
+const value = features.getFeatureValue("discount", { starter: 0 }); // 同步、本地判断
+features.setAttributes({ id: customerId, country: "JP" }); // 完整替换属性
+await features.refresh(); // 显式获取新的资源配置
+```
+
+`createFeatureClient` 在浏览器与服务端入口均可用，自行提供 load 可复用安全下发的配置。Secret Key 仅用于后端。init/refresh 后，每次 evalFeature/getFeatureValue 不联网；expiresAt 到达时间表边界后必须刷新。实验曝光和 Feature 使用由可选回调报告；持久化粘性分桶需提供对应存储回调和初始分配，后端 Funnel 使用原子数据库存储。
+
+需要异步接收时调用 `submit(input)`，它返回已持久接受的当前状态，不等待求值或轮询。`submit`／`decide` 首次提交的响应丢失、网络错误或服务暂时不可用时，会抛出 `DECISION_ACCEPTANCE_UNKNOWN`，其 `requestId` 是原逻辑请求编号；沿用原编号与原输入重试。请求已接受后，HTTP 结果等待最多八秒，读取卡住或暂时失败仍返回原 requestId／decisionId 的 pending 状态，不取消后台执行。
+
+交互运行的 `runExpiresAt` 和 `credentialExpiresAt` 分别表示业务期限和凭证期限。可信后端使用 `renewFunnelRun` 续签同一已识别客户的运行，业务期限不变。等待指令和客户端须使用同一当前协议。
+
+## Funnel 服务端回执
+
+`createFunnelOrchestrationClient` 来自 `/server` 入口，使用 App/环境的 Secret Key。`signal({ runId, nodeId, eventName, eventId, data })` 为已声明的自定义等待节点提交回执，重试沿用同一事件 ID 与数据；`readResults(runId)` 读取已完成任务和已消费回执的结果。浏览器不能发送这些回执，自定义事件不能代替验证付款事实。
+
+回执可以早于等待节点抵达，但收到确认不代表已经消费。条件和后续任务以 `nodeId.field` 引用声明结果。仅查询优惠的调用方可以继续使用上面的查询接口，不需要增加回执等待。
+
+本版包含 `createFunnelOrchestrationClient` 的 `signal` / `readResults` 接口。外部任务可复用已启用的 Sandbox 通知端点，提供签名请求、冻结输入和持久重试预算。接收器必须按 Action Receipt ID 去重；网络调用允许至少一次投递。配置、协议、数据库变更与验收边界见[编排说明](../../docs/funnel-orchestration-2026-10-10.md)。接口存在不代表宿主通知已经配置或验收。
+
+## 当前持有与账本
+
+### 原生订单恢复
+
+Swift／Kotlin 宿主的 `recoverNativeOrders` 通过应用自有 HTTPS 后端提交当前客户会话及受保护的订单绑定。后端使用 `createNativeReceiptClient`，服务器密钥始终留在后端：
+
+```ts
+import { createNativeReceiptClient } from "@tinkerlandai/indiana-sdk/server";
+const receipts = createNativeReceiptClient({
+  baseUrl: process.env.GROOVE_BASE_URL!,
+  apiKey: process.env.GROOVE_SECRET_KEY!,
+  scope: { projectId: process.env.GROOVE_PROJECT_ID!, environment: "sandbox" },
+});
+// 先校验应用自身登录会话及当前客户身份；重试保留原 requestId 和输入。
+const result = await receipts.recover(retainedCurrentReceiptInput);
+```
+
+该操作为 `/api/v1/funnels` 的 `native_receipt`，需要 `billing:write` 与 `funnels:run` 以及当前 `gg_ct_` 客户会话。它不依赖 run token，不复活或推进已结束、关闭或过期流程。Apple 只 finish 返回的 `nativeCompletion.transactionIds`；Google 的 acknowledge/consume 在服务端持久交付后完成。完整输入、宿主 relay、固定 SKU 席位及商店优惠边界见[当前原生接入](../../docs/native-commercial-current.md)。
+
+```ts
+import { createGroove } from "@tinkerlandai/indiana-sdk";
+const grow = createGroove({
+  baseUrl,
+  scope: { projectId, environment: "sandbox" },
+});
+grow.identify(customerToken);
+const { holdings } = await grow.readHoldings();
+const { ledger } = await grow.readLedger({
+  type: null,
+  from: null,
+  to: null,
+  after: null,
+  limit: 50,
+});
+const { quote } = await grow.quoteBalance({
+  operation: "quote",
+  entitlementId,
+  quantity: "1",
+  properties: {},
+});
+```
+
+浏览器请求不传客户 ID。持有需要 `entitlements:read`，账本和报价需要 `credits:read`。账本过滤作用于全部历史，之后分页；下一页原样传回 `nextCursor`，保留微秒、记录 ID 与类型。数量、余额和计价保留十进制字符串；报价不扣款。
+
+```ts
+const { receipt } = await groove.mutateBalance({
+  customerId: verifiedCustomer.id,
+  command: {
+    operation: "consume",
+    entitlementId,
+    quantity: "1",
+    properties: {},
+    idempotencyKey: `job:${job.id}`,
+  },
+});
+```
+
+后端使用 `consume`、`reserve`、`confirm`、`release`、`refund`。每次重试保留原输入和幂等键，确认、释放与退款引用原操作 ID。写入需要 `credits:consume`；退款另外需要 `credits:manage`。当前余额执行仅开放明确的 Sandbox 范围。
+
+## 积分、用量与计费
+
+以下接口需要与 SDK 协议匹配的 Grow 部署。SDK 包验证与发布不会自动升级既有宿主；数据库、Stripe、原生商店和部署各自的验收结果以对应回执为准。
+
+### 周期积分、消费分析与批量用量
+
+接口与验收边界见 [积分能力补齐](../../docs/credit-expansion.md)。在可信服务端使用：
+
+```ts
+const { entity } = await grow.manageUsageEntity({
+  customerId,
+  command: { action: "upsert", externalId: "workspace-a", name: "Workspace A" },
+});
+const requestId = crypto.randomUUID(); // 保存这个逻辑批次的身份，重试时复用
+const { batchId } = await grow.submitUsageBatch({
+  requestId,
+  items: [
+    {
+      customerId,
+      command: {
+        operation: "consume",
+        entitlementId,
+        entityId: entity.id,
+        quantity: "1",
+        properties: { model: "alpha" },
+        idempotencyKey: "generation-001",
+      },
+    },
+  ],
+});
+const { batch } = await grow.readUsageBatch({ batchId, after: -1, limit: 100 });
+// queued 只表示等待执行；逐条检查 accepted / rejected / failed 及 receipt。
+// 后续页使用 batch.nextAfter；整个批次没有跨功能事务语义。
+const { analytics } = await grow.readCreditAnalytics({
+  customerId,
+  query: {
+    range: {
+      kind: "absolute",
+      from: "2026-10-01T00:00:00Z",
+      to: "2026-10-08T00:00:00Z",
+    },
+    timezone: "UTC",
+    filterBy: [],
+    interval: "day",
+    groupBy: "properties.model",
+    entitlementId: null,
+    after: null,
+    limit: 100,
+  },
+});
+```
+
+`manageUsageEntity` 需要 `credits:manage`；批量提交需要 `credits:consume`，读取和分析需要 `credits:read`。批次最多 1,000 条，入队后返回 HTTP 202，每条事件保留独立消费凭据。相同 `requestId` 的重试必须保留完整输入；修改内容会冲突。分析保留 `entitlementId` 与 `resourceId`，不同计量单位不能直接相加，`charged` 等字段是积分数量。
+
+批量消费可指定 `command.occurredAt`；只允许当前 UTC 月内且不晚于服务器当前时间的事件。该时间用于事件归属，不回溯重算已结算账期或过去套餐的额度与费率。相对分析范围可用 `last_days` 或客户的 `billing_cycles`；读取后续页时，将 `range` 固定为返回的 `analytics.from` / `analytics.to`（`kind: "absolute"`），并传入 `analytics.nextCursor`，避免相对日期窗口在分页时移动。小时分桶使用 UTC，其余分桶使用查询的 IANA 时区。
+
+服务端 AI SDK v7 的自动 Token 采集用 `createAiUsageMiddleware`，必须提供每次上游调用的持久幂等键与 usage/quote 存储回调。生成和流式最终用量均使用原报价一次扣减；失败恢复直接重放扣款，避免重跑模型。`readBillingInvoice`、`readCreditStatement` 提供分页逐项账单和精确来源／退款明细。接入代码、时间范围与当前边界见 [积分接入](../../docs/credits-integration.md)。后续协议扩展须单独发布并匹配服务端部署。
+
+### 余额规则、状态同步与 AI 配置
+
+Server SDK 的 `readBalanceSource` / `adjustBalance` 在读取精确可用余额后以 `expectedAvailable` 增减或 `set_remaining`；保留预扣、已消费及付款依据。独立 `manageBalanceGrant` 的创建／更新使用当前 `rollover`、`nextResetAt` 字段，`amount: null` 表示无限额度，不能与结转组合。没有旧输入兼容。
+
+非消耗型的实际状态也通过当前客户的 `readHoldings()` 返回（`entitlements:read`）：每行必含可空 `usage`；非消耗型的 `usage` 含实际占用、总容量、带符号剩余量及修订号，其他类型为 null。无限容量的 capacity / remaining 为 null，超容量的 remaining 为负；available 始终非负。指定 Entity 只计算其独立非消耗型容量。
+
+非消耗型 metered 权益使用绝对状态同步，读取需要 `credits:read`，设置需要 `credits:manage`：
+
+```ts
+const { usage } = await grow.readUsage({
+  customerId,
+  query: { entitlementId, entityId: null },
+});
+await grow.setUsage({
+  customerId,
+  command: {
+    entitlementId,
+    entityId: null,
+    quantity: "12",
+    expectedRevision: usage.revision,
+    idempotencyKey: durableSyncId,
+    properties: {},
+  },
+});
+```
+
+`createConfiguredAiPricing(grow, { entitlementId })` 从已发布权益读取控制台 AI 模型／加价配置，入口为 `@tinkerlandai/indiana-sdk/server`。支持负加价和显式免费价格，免费调用保留真实 Token 的零金额事件。`createOpenRouterUsageClient` 从独立入口 `@tinkerlandai/indiana-sdk/openrouter` 导入，包装当前 `@openrouter/sdk` 的 `chat.send`，自动捕获生成／流式 Token，先持久保存 usage／原报价，再原子扣款；需要宿主提供 `context`、`persist` 和明确的推理计价方式。只有使用该入口的应用需要安装可选 peer dependency `@openrouter/sdk`；普通服务端入口的类型不引用它。示例及缺失价格、取消流、并发冲突和恢复语义见 [当前接入](../../docs/credits-integration.md)。
+
+### 新购订阅选择优惠券
+
+先通过 `redeemCoupon` 或发放获得持券，再用 `listOffers` 查询；将所选持券的 `id` 传入 `previewAttach.offerId`，不是 Coupon 定义 ID。仅新购 Stripe Checkout 支持此输入，首次结账最多一张券；已有订阅使用现有订阅优惠操作。
+
+```ts
+const { quote } = await groove.previewAttach({
+  requestId: crypto.randomUUID(),
+  plans: [{ productVersionId }],
+  provider: "stripe",
+  currency: "USD",
+  offerId: selectedOffer.id,
+});
+// 向客户展示 quote.discount 的条款、amountMinor 和逐套餐 allocations。
+// quote.catalogAmountMinor 是原价，自动税额在原生 Checkout 中确认。
+const { operation } = await groove.attach({ operationId: quote.operationId });
+```
+
+报价固定客户、环境、商品版本、币种和持券；修改选择必须使用新的 requestId 重新报价。接受时重新核对资格及持券占用，重复确认恢复原订单。只有原生支付验证才能产生核销和付费权益。
+
+## 0.0.1 范围与验收边界
+
+本版包含下列 Web／TypeScript 接口及行为。原生配套包、数据库与服务部署按各自回执判断：
+
+- 宿主句柄也支持 `handle.resume(originalRequestId)`，可在原命令已经完成后回读同一回执；无参数时恢复当前服务端待处理请求。`close()` 等待正在提交的命令完成，再持久化关闭，提交失败会继续向宿主抛出错误。 旧个人包 `0.0.7` 不代表具备相同语义。
+- 本版包含独立商店路径的 Web 契约；Swift／Kotlin 配套包另行发布：`previewAttach`／`previewUpdate` 固定订阅操作后，Swift／Kotlin 的 `purchaseSubscription`／`switchSubscription` 获取实际商店报价并购买；`restorePurchases` 扫描当前购买，通过 `POST /api/v1/subscriptions/native/restore` 恢复，不要求本地保留原订单绑定。后端仍须校验当前客户会话；商店购买链与账户关联决定归属，客户端的意图或客户 ID 不能转移购买。独立恢复要求 `billing:write`，已知 Funnel 订单的回执恢复仍使用上面的协议。候选迁移、本地替身验证与真实验收边界见[第八批记录](../../docs/subscription-core-phase8.md)。
+- 本版的预付 Feature 数量接口：`previewAttach` 的每个 plan 可传 `featureQuantities: { [entitlementVersionId]: quantity }`；`previewUpdate` 使用 `change: { type: "quantity", entitlementVersionId, quantity }`，再通过同一 `update` 确认。Swift／Kotlin 对应 `previewQuantityUpdate`。增加数量可立即付款生效，减少数量使用 `renewal`；重试保留原 requestId。服务端根据不可变套餐条款和实际计费项交付额度。此项支持 Stripe，Apple／Google 仍使用固定已发布 SKU，不能传可变数量替换商店价格。详见[第九批记录](../../docs/subscription-core-phase9.md)。
+- 本版客户资料使用 `attributes`，属性删除使用 `removeAttributes`，标签增减使用 `tagChanges`；旧个人包 `0.0.7` 保留原 `metadata` / `tags` 契约，不能向旧包传入当前新字段。
+- 本版浏览器和服务端提供 `createFeatureClient` 与 Feature 评估契约，见[实施记录](../../docs/experiments-growthbook-port-plan-2026-10-11.md)。该导出不在旧个人包 `0.0.7` 的类型入口中。
+
+发布产物和检查结果见 [发布总账](../../docs/sdk-releases.md)。本次按用户要求跳过浏览器验证；真实 Auth/RLS、Stripe、原生商店与部署验收未执行，npm 发布不代表这些验收已通过。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# GrowthBook core
+
+MIT core port from growthbook/growthbook at ed29827a453ae6b9eba181bdf4e9280d4b670817. No enterprise-licensed code is included.
+
+Copyright (c) 2025 GrowthBook, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ai-usage-CzA11PV5.d.ts

@@ -0,0 +1,235 @@
+import { LanguageModelV4Usage, LanguageModelV4Middleware } from '@ai-sdk/provider';
+import { F as FoundationApi, A as ApiInput } from './api-DDlcUvTv.js';
+import { z } from 'zod';
+
+declare const tokenCounts: z.ZodObject<{
+    input: z.ZodNumber;
+    output: z.ZodNumber;
+    cache_read: z.ZodNumber;
+    cache_write: z.ZodNumber;
+    reasoning: z.ZodNumber;
+    input_audio: z.ZodNumber;
+    output_audio: z.ZodNumber;
+}, z.core.$strict>;
+declare const aiPriceSnapshotSchema: z.ZodObject<{
+    modelId: z.ZodString;
+    source: z.ZodEnum<{
+        "models.dev": "models.dev";
+        custom: "custom";
+    }>;
+    fetchedAt: z.ZodISODateTime;
+    rates: z.ZodObject<{
+        input: z.ZodString;
+        output: z.ZodString;
+        cache_read: z.ZodOptional<z.ZodString>;
+        cache_write: z.ZodOptional<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodString>;
+        input_audio: z.ZodOptional<z.ZodString>;
+        output_audio: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    contextTier: z.ZodNumber;
+    markupPercent: z.ZodNumber;
+}, z.core.$strict>;
+declare const aiTokenQuoteSchema: z.ZodObject<{
+    pricing: z.ZodObject<{
+        modelId: z.ZodString;
+        source: z.ZodEnum<{
+            "models.dev": "models.dev";
+            custom: "custom";
+        }>;
+        fetchedAt: z.ZodISODateTime;
+        rates: z.ZodObject<{
+            input: z.ZodString;
+            output: z.ZodString;
+            cache_read: z.ZodOptional<z.ZodString>;
+            cache_write: z.ZodOptional<z.ZodString>;
+            reasoning: z.ZodOptional<z.ZodString>;
+            input_audio: z.ZodOptional<z.ZodString>;
+            output_audio: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        contextTier: z.ZodNumber;
+        markupPercent: z.ZodNumber;
+    }, z.core.$strict>;
+    tokens: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cache_read: z.ZodNumber;
+        cache_write: z.ZodNumber;
+        reasoning: z.ZodNumber;
+        input_audio: z.ZodNumber;
+        output_audio: z.ZodNumber;
+    }, z.core.$strict>;
+    quantity: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    digest: z.ZodString;
+}, z.core.$strict>;
+type AiTokenQuote = z.infer<typeof aiTokenQuoteSchema>;
+type AiTokenUsage = z.infer<typeof tokenCounts>;
+type AiPricingOptions = {
+    defaultMarkup?: number;
+    providerMarkups?: Record<string, number>;
+    modelMarkups?: Record<string, number>;
+    customModels?: Record<string, z.infer<typeof aiPriceSnapshotSchema>["rates"]>;
+    fetch?: typeof fetch;
+};
+/** Fetch automatic model prices on a trusted backend. Quotes can be saved with a job and reused verbatim on retries. */
+declare function createAiPricing(options?: AiPricingOptions): {
+    /** Explicit refresh affects future quotes only, including their immutable timestamps and digest. */
+    refreshPrices(): void;
+    quoteTokens(input: {
+        modelId: string;
+        tokens: AiTokenUsage;
+    }): Promise<AiTokenQuote>;
+    /** All pools become one atomic balance operation. The metered entitlement unit must be one micro USD. */
+    trackTokens(client: Pick<FoundationApi, "mutateBalance">, input: {
+        customerId: string;
+        entitlementId: string;
+        entityId?: string;
+        idempotencyKey: string;
+        quote: AiTokenQuote;
+        properties?: Record<string, string>;
+        providerCostUsd?: string;
+        generationId?: string;
+    }): Promise<{
+        requestId: string;
+        scope: {
+            projectId: string;
+            environment: "sandbox" | "live";
+        };
+        receipt: {
+            id: string;
+            entitlementId: string;
+            kind: "confirm" | "consume" | "reserve" | "refund" | "release" | "expire";
+            originalId: string | null;
+            quantity: string;
+            accepted: boolean;
+            reason: "expired" | "unavailable" | "insufficient_balance" | "limit_exceeded" | "awaiting_topup" | "authorization_required" | "payment_blocked" | "cash_budget_exceeded" | null;
+            createdAt: string;
+            reservationStatus: "pending" | "expired" | "confirmed" | "released" | null;
+            expiresAt: string | null;
+            allocations: ({
+                funding: "prepaid";
+                sourceId: string;
+                units: string;
+                amount: string;
+                pricing: {
+                    creditVersionId: string | null;
+                    meteredVersionId: string;
+                    dimension: string;
+                    counterKey: string;
+                    cycleStart: string;
+                    unitCost: string;
+                    units: string;
+                    amount: string;
+                    tier: number | null;
+                }[];
+            } | {
+                funding: "unbilled";
+                units: string;
+            } | {
+                funding: "postpaid";
+                invoiceLineId: string | null;
+                units: string;
+                authorizationId: string;
+            })[];
+            requestedQuantity?: string | undefined;
+            overageBehavior?: "cap" | "overflow" | undefined;
+        };
+    }>;
+};
+/** Read one published configuration for new provider calls. Saved quotes keep their original rules. */
+declare function createConfiguredAiPricing(client: Pick<FoundationApi, "readAiPricing">, input: ApiInput<"readAiPricing">, options?: Pick<AiPricingOptions, "fetch">): Promise<{
+    /** Explicit refresh affects future quotes only, including their immutable timestamps and digest. */
+    refreshPrices(): void;
+    quoteTokens(input: {
+        modelId: string;
+        tokens: AiTokenUsage;
+    }): Promise<AiTokenQuote>;
+    /** All pools become one atomic balance operation. The metered entitlement unit must be one micro USD. */
+    trackTokens(client: Pick<FoundationApi, "mutateBalance">, input: {
+        customerId: string;
+        entitlementId: string;
+        entityId?: string;
+        idempotencyKey: string;
+        quote: AiTokenQuote;
+        properties?: Record<string, string>;
+        providerCostUsd?: string;
+        generationId?: string;
+    }): Promise<{
+        requestId: string;
+        scope: {
+            projectId: string;
+            environment: "sandbox" | "live";
+        };
+        receipt: {
+            id: string;
+            entitlementId: string;
+            kind: "confirm" | "consume" | "reserve" | "refund" | "release" | "expire";
+            originalId: string | null;
+            quantity: string;
+            accepted: boolean;
+            reason: "expired" | "unavailable" | "insufficient_balance" | "limit_exceeded" | "awaiting_topup" | "authorization_required" | "payment_blocked" | "cash_budget_exceeded" | null;
+            createdAt: string;
+            reservationStatus: "pending" | "expired" | "confirmed" | "released" | null;
+            expiresAt: string | null;
+            allocations: ({
+                funding: "prepaid";
+                sourceId: string;
+                units: string;
+                amount: string;
+                pricing: {
+                    creditVersionId: string | null;
+                    meteredVersionId: string;
+                    dimension: string;
+                    counterKey: string;
+                    cycleStart: string;
+                    unitCost: string;
+                    units: string;
+                    amount: string;
+                    tier: number | null;
+                }[];
+            } | {
+                funding: "unbilled";
+                units: string;
+            } | {
+                funding: "postpaid";
+                invoiceLineId: string | null;
+                units: string;
+                authorizationId: string;
+            })[];
+            requestedQuantity?: string | undefined;
+            overageBehavior?: "cap" | "overflow" | undefined;
+        };
+    }>;
+}>;
+
+type AiUsageContext = {
+    customerId: string;
+    entitlementId: string;
+    entityId?: string;
+    idempotencyKey: string;
+    properties?: Record<string, string>;
+};
+type AiUsageRecord = {
+    context: AiUsageContext;
+    modelId: string;
+    usage: LanguageModelV4Usage | null;
+    tokens: AiTokenUsage | null;
+    quote: AiTokenQuote | null;
+    receipt: Awaited<ReturnType<FoundationApi["mutateBalance"]>> | null;
+    phase: "captured" | "quoted" | "settled" | "incomplete";
+};
+type AiUsageMiddlewareOptions = {
+    pricing: ReturnType<typeof createAiPricing>;
+    client: Pick<FoundationApi, "mutateBalance">;
+    modelId: string;
+    /** Allocate a durable, unique ID per provider call, including each tool step. */
+    context: () => AiUsageContext | Promise<AiUsageContext>;
+    /** Save raw usage before pricing, and the frozen quote before a balance request. */
+    persist: (record: AiUsageRecord) => Promise<void>;
+    reasoning: "output" | "separate";
+    mapTokens?: (usage: LanguageModelV4Usage) => AiTokenUsage;
+};
+/** Current AI SDK v7 / LanguageModelV4 only. Never suppress a failed financial settlement. */
+declare function createAiUsageMiddleware(options: AiUsageMiddlewareOptions): LanguageModelV4Middleware;
+
+export { type AiUsageContext as A, type AiTokenUsage as a, type AiTokenQuote as b, createAiPricing as c, type AiPricingOptions as d, type AiUsageMiddlewareOptions as e, type AiUsageRecord as f, aiPriceSnapshotSchema as g, aiTokenQuoteSchema as h, createAiUsageMiddleware as i, createConfiguredAiPricing as j };