@tinkerlandai/indiana-sdk 0.9.1 → 0.9.5

package/CHANGELOG.md

@@ -2,8 +2,24 @@
 
 Release facts and artifact evidence: [SDK release ledger](../../docs/sdk-releases.md).
 
+## 0.9.5 — 2026-10-29
+
+- Synchronize JavaScript, React Native, Swift, Kotlin, Python and Go with the current Customer operations, scope checks, response validation and document semantics.
+- Expand Go configuration, Feature and Local Funnel support, and align native content presentation, Customer capabilities and shared renderer resources.
+- Add merchant Server SDK billing records, Merchant Bridge integration and current quantity and prepaid-credit contracts.
+- Validate nested Paywall access decisions in Swift and Kotlin with the same denial and recommendation rules as direct entitlement checks.
+- Make the iOS Push restart-recovery test explicitly retain a failed logout instead of racing a successful background detach.
+- Retain protocol 0.9 as the only supported wire protocol. Missing or older protocol identities have no fallback or compatibility adapter.
+
+## 0.9.2 — 2026-10-29
+
+- Add Python Server-Key APIs for Funnel decisions and recovery, Offering resolution, Feature evaluation and marketing events, with synchronous and asynchronous clients.
+- Support Pika V1 marketing data delivery entirely on the merchant backend, without creating or distributing a Customer Token. Keep payment and entitlements in Pika's existing flow.
+- Keep wire protocol 0.9 and the existing JavaScript, React Native, Swift, Kotlin and Go business behavior.
+
 ## 0.9.1 — 2026-10-29
 
+- Add `showPaywall.onPurchaseIntent` for merchant-owned selection handling, with validated Product and Feature quantities and no SDK quote or payment operation.
 - Return scoped Access/Refresh credential pairs from backend issuance and Guest session resumption. Replace backend renewal with client Refresh Token rotation; backend revocation invalidates both credentials.
 - Automatically refresh in Web, React Native, Swift and Kotlin without resetting Customer state, analytics queues, Funnel Runs or Paywalls. Fence account changes and retain Refresh Tokens after lost responses.
 - Go owns opaque-session lifecycle and authorization policy; PostgreSQL serializes rotation and revocation. Protocol 0.9 requires the matching runtime and SQL migrations and refuses older development protocols.

package/README.md

@@ -1,10 +1,10 @@
 # @tinkerlandai/indiana-sdk
 
-These examples target SDK 0.9.1 and protocol 0.9 at `https://api.tinker.cash`, using a Sandbox App and credentials issued by the production deployment. Sandbox still contains production data; do not reuse credentials from the separate test deployment. Confirm runtime readiness in [environment state](../../docs/development-status.md) before running them.
+This source checkout is SDK 0.9.5, protocol 0.9. These examples use `https://api.tinker.cash`, using a Sandbox App and credentials issued by the production deployment. Sandbox still contains production data; do not reuse credentials from the separate test deployment. Confirm runtime readiness in [environment state](../../docs/development-status.md) before running them.
 
 [简体中文](./README.zh-CN.md)
 
-The Indiana business SDK groups its capabilities as **Identity, Commerce, GrowthBook, Analytics, Delivery (Offering, Paywall, Page, Popup and Banner), and Funnel**, over shared protocol, transport, configuration, rendering and recovery foundations. These responsibilities follow the existing L0–L4 architecture; language packages and entry points implement different subsets. The browser/native client and merchant-server entries share contracts and core behavior while retaining separate credentials and allowed operations. Indianapolis is the backend runtime they call; it is not the merchant's server SDK.
+The Indiana business SDK groups its capabilities as **Identity, Commerce, experimentation engine, Analytics, Delivery (Offering, Paywall, Page, Popup and Banner), and Funnel**, over shared protocol, transport, configuration, rendering and recovery foundations. These responsibilities follow the existing L0–L4 architecture; language packages and entry points implement different subsets. The browser/native client and merchant-server entries share contracts and core behavior while retaining separate credentials and allowed operations. Indianapolis is the backend runtime they call; it is not the merchant's server SDK.
 
 **IAM source scanning, generation, validation and upload belong to the independent build package `@tinkerlandai/indiana-iam`.** This business SDK retains only the runtime release binding used by GB visual changes. See [SDK boundaries](../../docs/sdk-architecture.md) and the [IAM package](../iam/README.md).
 
@@ -12,7 +12,7 @@ The Indiana business SDK groups its capabilities as **Identity, Commerce, Growth
 npm install --save-exact @tinkerlandai/indiana-sdk@0.9.1
 ```
 
-SDK 0.9.1 requires HTTP protocol 0.9. Install a version that matches your runtime; publishing a package does not deploy the server. Publication and accepted environment scope are recorded in the [release ledger](../../docs/sdk-releases.md) and [development status](../../docs/development-status.md).
+This SDK requires HTTP protocol 0.9. Install a version that matches your runtime; publishing a package does not deploy the server. Publication and accepted environment scope are recorded in the [release ledger](../../docs/sdk-releases.md) and [development status](../../docs/development-status.md).
 
 The data/session layer handles public JSON, integrity checks and authenticated operations. The presentation host composes that layer with the packaged screen renderer; the renderer receives supplied data and emits action intents. Client display entry points load presentation lazily. The `/server` entry has no screen presentation dependency and uses a scoped Server Key only on your backend. A local SDK guard never replaces runtime authorization or verified payment completion. Console preview supplies simulated data/session results to the same presentation host.
 
@@ -245,11 +245,17 @@ merchandiseFlags.destroy();
 
 Offering pins the Product Version scope and hierarchy. Paywall pins a published Offering Version and independently chooses its displayed Product subset, groups, ordering, and default selection. `createPaywallStartClient`, `createPaywallSession`, and `showPaywall` use a standalone Paywall Session. After payment, read Entitlements again. Your backend still authorizes requests and consumes usage idempotently.
 
+To render a Paywall while handing purchase selection to your own app, pass `onPurchaseIntent` to `showPaywall`. It receives
+`actionId`, the selected `productVersionId`, a copy of the UI `selection`, and validated `featureQuantities`. That callback
+replaces quote creation for the clicked purchase button; it neither charges nor grants access. Share the identified
+client's `session` with `createPaywallSession` to retain automatic Access/Refresh rotation. Your session endpoint must
+verify the native user before issuing credentials; reset the client and destroy the Paywall when that user changes.
+
 ## Commercial capabilities and current service boundaries
 
 The server implements Customer/Guest identity, Entitlement checks, holdings and ledger reads, usage and balances, Coupons/referral codes, Offering/standalone Paywall, and configured Stripe Sandbox attach, payment-method collection, subscription validation/updates/refunds/Trial, and License allocation. Each operation depends on configured payment accounts, execution mode, Product/Price terms, and its implemented scope. An API's presence does not certify every combination.
 
-In Stripe environments, Indiana executes `autumn` mode; `record_only` returns instructions for the merchant backend to execute. Both record financial and Entitlement facts from verified Stripe evidence. Collecting a payment method does not itself charge, create an Invoice, or grant extra Entitlements. Quotes, confirmations, and reads retain their durable operation IDs; a request ID cannot be reused with different input.
+In Stripe environments, Indiana executes `indiana` mode; `record_only` returns instructions for the merchant backend to execute. Both record financial and Entitlement facts from verified Stripe evidence. Collecting a payment method does not itself charge, create an Invoice, or grant extra Entitlements. Quotes, confirmations, and reads retain their durable operation IDs; a request ID cannot be reused with different input.
 
 This beta does not certify complete commercial or production operation. Remaining service gaps include:
 
@@ -351,6 +357,33 @@ Recovery uses the original Run Token and command identities. Do not turn an unkn
 
 The native renderer shell uses the same pure JavaScript calculation adapter and native Run-command bridge; credentials remain in the native session. A headless Swift/Kotlin session exposes the pending calculation and does not silently calculate it remotely. Wire schemas and the renderer shell are generated together. Installing the package does not migrate a database or deploy a runtime. Browser, provider, capacity and native-store acceptance remain separate.
 
+## Web IAM entries and Funnel page experiments
+
+Install the entry host once, then configure screen-entry or button/link triggers on a Funnel's Entry node in the App page map. Save and publish through the existing Funnel lifecycle. Use the merchant build's verified IAM digest and the same Customer session as other SDK clients:
+
+```ts
+import { createIamFunnelEntries } from "@tinkerlandai/indiana-sdk";
+
+const entries = createIamFunnelEntries({
+  scope: { projectId, environment: "sandbox" },
+  environmentId,
+  baseUrl,
+  appManifestRelease, // digest resolved from this build's IAM release descriptor
+  session: indiana.session,
+  container,
+  onStatus: (status, entryId) => console.log(status, entryId),
+});
+await entries.start();
+// After an uncertain start, reuse the original in-memory request:
+await entries.retry();
+// On host teardown:
+entries.destroy();
+```
+
+The host observes original button behavior, matches unique render/element guards and attempts automatic entries once per pathname visit. GOP selects the Funnel, checks entry publication, suppresses an existing Customer/Funnel Run and enforces the automatic-entry cooldown. The host retains unknown requests in memory; page reload recovery is not included. An IAM binding supplies no Customer credential or business permission.
+
+An opted-in Split (`applyPageExperiment: true`) uses its accepted experiment variation for the merchant page. The entry host automatically shares `appManifestRelease` with `showFunnelRun`; manual hosts pass that option explicitly. `createFunnelPageExperiments({client, appManifestRelease})` is available for hosts without the standard UI. The consumer never rebuckets, reports use against the accepted receipt, and reverts on stop, completion or destruction. A separately installed visual consumer yields ownership of that experiment during the Run. This Web source feature requires matching GOP contracts and the IAM/Funnel database migration; installation alone does not promote runtime support.
+
 ## Funnel-scoped resource requests
 
 Formal Local Runs submit advance signals to Indiana; the canonical executor supplies the original Run/node/visit/receipt when it issues a Coupon or performs commerce. An application consuming a pure Funnel result can bind its Customer client explicitly:
@@ -427,3 +460,26 @@ openButton.addEventListener("click", () => popup.show(), {
 Preparation waits for the first render without opening the dialog or running actions. `show()` reveals the same iframe and is idempotent; destroy and prepare a fresh handle for another presentation. Abort also cancels preparation while it is pending. This does not pre-authorize business operations or guarantee that images have decoded. For low-level ScreenDocument rendering, `/popup` provides `preparePopup(document, options)` with `ready`, `show()` and `destroy()`.
 
 Customer sessions contain `customerId`, `sessionId`, `accessToken`, `refreshToken`, `expiresAt` and `refreshExpiresAt`. Return the pair only to the authenticated merchant user with `Cache-Control: no-store`, then call `indiana.identify(session)`. The SDK refreshes directly with GOP and keeps credentials in memory; account reset fences pending refresh. Your backend uses `revokeCustomerSessions({customerId, sessionId?})` for revocation. Share `indiana.session` through the `session` option of independent Paywall/Funnel clients to preserve one refresh lifecycle.
+
+## Merchant-recorded billing
+
+In a `record_only` App environment, your backend owns Stripe execution and confirms the result. Register its Stripe account ID and submit complete object snapshots with the Server SDK; Indiana does not accept Stripe callbacks or require a Stripe Key/signing secret in this mode. `indiana` mode continues to use verified Stripe callbacks.
+
+```ts
+await server.recordBillingEvent({
+  provider: "stripe",
+  accountId: "acct_your_account",
+  eventId: "your-stable-event-id",
+  type: "invoice.paid",
+  occurredAt: Date.now(),
+  data: completePaidInvoice,
+});
+```
+
+Keep the same event ID, timestamp and data when retrying. Submit all Invoice lines and subscription items; incomplete snapshots are rejected. Existing quote metadata and Price bindings associate the record with the purchase. The receipt identifies merchant provenance with `providerVerified: false`. Customer/Guest clients cannot record billing results.
+
+## Merchant bridge
+
+The source export `createMerchantBridge` consumes the version 2 single-receiver merchant adapter for `record_only`. It uses an explicitly scoped capability declaration, native merchant authentication and typed commands at one fixed POST `/integrations/indiana` for presentation, Customer sessions, commerce reads, purchase execution and operation recovery. Call `reset()` on logout/account switch. Display receipts are separate from purchases; the client never retries a charge or opens Checkout automatically. Server Keys and refund/catalog authority remain on trusted backends. See the [merchant specification](https://tinker.cash/docs/merchant-execution) for the manifest, Console configuration and wire fields. This source export requires publication of a package containing it; it does not certify a deployed merchant integration.
+
+The Server source entry also exports `createMerchantBridgeHandler`, `signMerchantBridgeMessage` and `verifyMerchantBridgeMessage`. Supply a scoped declaration, backend-only signing keys, native `authorize(request, input)` and typed command handlers. Authorize identity, CSRF and original operation ownership/confirmation before effects; handlers own durable idempotency and recovery. Console checks run signed Ping, discovery and available catalog reads only. Declarations and 202 acceptance are not purchase/fulfilment completion. Never expose signing keys to browsers. Bridge versioning does not change Indiana protocol 0.9 or billing-result recording.

package/README.zh-CN.md

@@ -1,10 +1,10 @@
 [English](./README.md)
 
-本页示例面向 SDK 0.9.1 和协议 0.9，使用 `https://api.tinker.cash` 以及生产部署内签发的 Sandbox App／凭据。Sandbox 仍属于生产数据，不能复用独立测试部署的凭据。运行前核对[环境状态](../../docs/development-status.md)，确认服务已就绪。
+当前源码为 SDK 0.9.5、协议 0.9。本页示例使用 `https://api.tinker.cash` 以及生产部署内签发的 Sandbox App／凭据。Sandbox 仍属于生产数据，不能复用独立测试部署的凭据。运行前核对[环境状态](../../docs/development-status.md)，确认服务已就绪。
 
 # @tinkerlandai/indiana-sdk
 
-业务 SDK 按职责分为 **身份、商业、GrowthBook、Analytics、内容交付（Offering、Paywall、Page、Popup、Banner）和 Funnel 六组能力**，共用协议、传输、配置、渲染与恢复等基础设施。分类沿用系统的 L0–L4 归属，各语言包和入口支持的子集不同。客户端与商户服务端共用契约和核心行为，凭据及可执行操作分开。Indianapolis 是它们调用的 SDK 运行服务，不是商户安装的服务端 SDK。
+业务 SDK 按职责分为 **身份、商业、实验引擎、Analytics、内容交付（Offering、Paywall、Page、Popup、Banner）和 Funnel 六组能力**，共用协议、传输、配置、渲染与恢复等基础设施。分类沿用系统的 L0–L4 归属，各语言包和入口支持的子集不同。客户端与商户服务端共用契约和核心行为，凭据及可执行操作分开。Indianapolis 是它们调用的 SDK 运行服务，不是商户安装的服务端 SDK。
 
 **IAM 的源码扫描、生成、校验和上传属于独立构建包 `@tinkerlandai/indiana-iam`。** 普通业务 SDK 只保留 GB visual 应用页面变更所需的运行时 release 绑定。完整定义见 [SDK 边界](../../docs/sdk-architecture.md) 与 [IAM 构建包](../iam/README.md)。
 
@@ -239,11 +239,16 @@ flags.destroy();
 
 Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
 
+仅渲染并将购买选择交给宿主时，向 `showPaywall` 传入 `onPurchaseIntent`。回调接收 `actionId`、选中的
+`productVersionId`、UI `selection` 副本和已校验的 `featureQuantities`；这条路径不创建报价、扣款或发放权益。
+将已识别客户端的 `session` 传给 `createPaywallSession`，以共用 Access/Refresh 自动轮换。宿主会话接口必须先验证
+当前原生用户再签发凭据；退出或切换账号时销毁 Paywall 并重置客户端。
+
 ## Web 商业能力与当前服务边界
 
 当前服务端实现了 Customer／Guest、Entitlement 检查、持有与账本读取、用量和余额、Coupon／推荐码、Offering／独立 Paywall，以及配置后的 Stripe Sandbox attach、支付方式收集、订阅验证／更新／退款／Trial 和 License 分配路径。每个操作仍受已配置的支付账号、执行模式、Product／Price 条款和当前实现范围约束；接口存在不表示任意组合已验收。
 
-Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
+Stripe 环境的 `indiana` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
 
 本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
 
@@ -282,6 +287,14 @@ npm 发布不部署 Web 服务、不应用数据库迁移，也不发布 Swift
 
 完整调用和恢复要求见[统一执行说明](README.md#local-funnel-execution)。
 
+## Web IAM 入口与 Funnel 页面实验
+
+`createIamFunnelEntries({scope, environmentId, baseUrl, appManifestRelease, session: indiana.session, container})` 安装一次后，通过 `start()` 启动监听，即可在 IAM 页面地图配置现有 Funnel Entry 节点的「进入屏幕」和「按钮/链接点击」入口。配置保存到 Funnel 草稿，随 Funnel 一起发布、暂停。`appManifestRelease` 必须来自当前构建的 IAM release descriptor。原页面点击处理继续执行；仅唯一、可验证的页面和元素能够触发。自动入口每次 pathname 访问尝试一次，查询参数、hash 和重新渲染不制造新访问。
+
+服务端选择 Funnel，验证发布状态，并按原 Customer/Funnel 检查进行中的 Run 和自动入口冷却时间。未知响应通过 `retry()` 复用内存中的原请求；入口宿主不提供刷新页面后的恢复。卸载时调用 `destroy()`。IAM 不提供 Customer 凭据或业务权限。
+
+Split 开启 `applyPageExperiment` 后，页面直接使用该 Run 已接受的实验变体，不重新分桶。标准入口宿主自动向 `showFunnelRun` 传入 release；手动宿主传入 `appManifestRelease`，或使用 `createFunnelPageExperiments({client, appManifestRelease})`。停止、完成和销毁会清理效果，实际应用沿用原 receipt 的 GB used 上报。同一实验的独立 visual consumer 在 Funnel 持有分组期间让出控制。这些 Web 源码能力需要配套 GOP 合同和数据库迁移，安装 SDK 不等于运行时已发布。
+
 ## Funnel 资源上下文
 
 正式 Local Run 由服务端执行原业务动作，自动携带原 Run、node、visit 和 receipt。消费纯 Funnel 结果时，使用 `indiana.forFunnel({ funnelId, versionId })` 获取固定上下文的客户端；其领取、Offering/Paywall 解析和购买报价自动携带这一个 Funnel。服务端以可信事实复算指定流程，不扫描其他 Funnel。
@@ -336,3 +349,13 @@ export async function showBanner(
 可传入 `signal: abortController.signal`，在卸载、退出或切换 Customer／App／环境时 `abortController.abort()`，连同仍在等待的准备一起取消并释放资源。预渲染不代替业务鉴权，也不保证图片已完成解码。直接持有已授权 ScreenDocument 的低层接入可使用 `/popup` 的 `preparePopup(document, options)`；句柄立即返回，提供 `ready`、`show()` 和 `destroy()`。
 
 客户会话返回 `customerId`、`sessionId`、`accessToken`、`refreshToken`、`expiresAt`、`refreshExpiresAt`。后端只向当前已验证用户返回这组数据，并设置 `Cache-Control: no-store`；客户端调用 `indiana.identify(session)`。SDK 在内存中保管凭据，直接向 GOP 刷新，切换账号或 reset 后不接纳旧刷新响应。撤销由后端调用 `revokeCustomerSessions({customerId, sessionId?})`。独立 Paywall/Funnel 客户端可通过 `session: indiana.session` 共用刷新生命周期。
+
+## 商户主动记账
+
+`record_only` 环境由商户后端执行支付并确认结果，再通过服务端 SDK 的 `recordBillingEvent({ provider: "stripe", accountId, eventId, type, occurredAt, data })` 提交完整对象快照。`occurredAt` 是毫秒时间戳；重试保留相同事件 ID、时间和数据。发票必须包含全部行，订阅必须包含全部项目，并保留原报价的关联信息与 Price 绑定。Indiana 复用现有订单、订阅和账本，明确记录商户来源；此模式不接收 Stripe 回调，也不需要 Stripe API Key 或 Webhook 签名密钥。Customer/Guest 客户端不能记账。`indiana` 全托管模式继续使用 Stripe 验签回调。
+
+## 商户桥接
+
+源码导出 `createMerchantBridge`，用于 `record_only` 的版本 2 单入口商户适配层。客户端按明确 App/环境/账户的能力声明，使用商户原生登录向固定 POST `/integrations/indiana` 发送有类型的展示、会话、商业状态、购买和操作恢复指令。退出或切账号时调用 `reset()`。展示回传与购买独立，不自动重试扣款或打开 Checkout；Server Key、退款和目录读取权限留在可信后端。能力声明、Console 配置及字段见[商户接入规范](https://tinker.cash/zh-CN/docs/merchant-execution)。此导出需要发布包含它的 SDK 包后才可安装使用，源码存在不代表商户已经部署。
+
+Server 入口源码另导出 `createMerchantBridgeHandler`、`signMerchantBridgeMessage` 和 `verifyMerchantBridgeMessage`。商户提供固定范围的能力声明、服务端签名密钥、原生 `authorize(request, input)` 与指令处理器；原生授权必须在业务写入前核对身份、CSRF、原操作归属与确认，处理器负责持久幂等和恢复。Console 只执行签名 Ping、能力发现及可用的目录读取，不把声明或 202 受理当作购买／权益完成。签名凭据不得交给浏览器。桥接版本不改变 Indiana 协议 0.9 或账单结果回传契约。

package/dist/{ai-usage-DMNKvCiq.d.ts → ai-usage-CUTIHAU0.d.ts}

@@ -1,5 +1,5 @@
 import { LanguageModelV4Usage, LanguageModelV4Middleware } from '@ai-sdk/provider';
-import { F as FoundationApi, A as ApiInput } from './api--Zf0gxfj.js';
+import { F as FoundationApi, A as ApiInput } from './api-BXu6TAoB.js';
 import { z } from 'zod';
 
 declare const tokenCounts: z.ZodObject<{
@@ -98,13 +98,13 @@ declare function createAiPricing(options?: AiPricingOptions): {
         receipt: {
             id: string;
             internal_feature_id: string;
-            kind: "consume" | "reserve" | "confirm" | "refund" | "release" | "expire";
+            kind: "refund" | "consume" | "reserve" | "confirm" | "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: "expired" | "pending" | "confirmed" | "released" | null;
+            reservationStatus: "pending" | "expired" | "confirmed" | "released" | null;
             expiresAt: string | null;
             allocations: ({
                 funding: "prepaid";
@@ -169,13 +169,13 @@ declare function createConfiguredAiPricing(client: Pick<FoundationApi, "readAiPr
         receipt: {
             id: string;
             internal_feature_id: string;
-            kind: "consume" | "reserve" | "confirm" | "refund" | "release" | "expire";
+            kind: "refund" | "consume" | "reserve" | "confirm" | "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: "expired" | "pending" | "confirmed" | "released" | null;
+            reservationStatus: "pending" | "expired" | "confirmed" | "released" | null;
             expiresAt: string | null;
             allocations: ({
                 funding: "prepaid";