@tinkerlandai/indiana-sdk 0.8.5 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Release facts and artifact evidence: [SDK release ledger](../../docs/sdk-releases.md).
 
+## 0.9.1 — 2026-10-29
+
+- 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.
+
 ## 0.8.5 — 2026-10-27
 
 - Add direct browser script loading through `/sdk.js`, sharing the npm browser APIs and page/visual experiment factories without requiring a bundler. Website deployment distributes this entry independently of npm publication.

package/README.md

@@ -1,6 +1,6 @@
 # @tinkerlandai/indiana-sdk
 
-These examples use SDK 0.8.4 with `https://api.dev.tinker.cash` and test App credentials (protocol 0.8). Check [environment state](../../docs/development-status.md) before switching. The SDK default remains the production API, so set `baseUrl` explicitly for these examples.
+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.
 
 [简体中文](./README.zh-CN.md)
 
@@ -9,10 +9,10 @@ The Indiana business SDK groups its capabilities as **Identity, Commerce, Growth
 **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).
 
 ```sh
-npm install --save-exact @tinkerlandai/indiana-sdk@0.8.4
+npm install --save-exact @tinkerlandai/indiana-sdk@0.9.1
 ```
 
-SDK 0.8.4 requires HTTP protocol 0.8. 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).
+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).
 
 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.
 
@@ -21,7 +21,7 @@ The data/session layer handles public JSON, integrity checks and authenticated o
 The classic-script entry reuses the npm browser implementation, with no bundler:
 
 ```html
-<script src="https://dev.tinker.cash/sdk.js"></script>
+<script src="https://tinker.cash/sdk.js"></script>
 <script type="module">
   const {
     createIndiana,
@@ -32,11 +32,11 @@ The classic-script entry reuses the npm browser implementation, with no bundler:
     mountContent,
   } = await Indiana.ready;
   const client = createIndiana({
-    baseUrl: "https://api.dev.tinker.cash",
+    baseUrl: "https://api.tinker.cash",
     scope: { projectId: "<APP_UUID>", environment: "sandbox" },
   });
-  // Obtain customerToken from your authenticated backend session endpoint.
-  // client.identify(customerToken);
+  // Obtain the complete session pair from your authenticated backend.
+  // client.identify(session);
   // await client.readHoldings();
   // client.track("page_viewed", { page: location.pathname });
   // await client.flush();
@@ -82,32 +82,9 @@ The canonical repository policy, including production/test domain roles, package
 
 Omitting `baseUrl` selects `https://api.tinker.cash`. This applies to Customer/Server, Funnel, Feature, Paywall, page and visual clients. `createConfigurationSync` also defaults its optional `origin` to that address. Swift `IndianaConfiguration(scope: ...)` and Kotlin `IndianaConfiguration(scope = ...)` uses the same default and shared release version. Explicit `baseURL` / `baseUrl` still overrides it. Funnel and Paywall shells and renderers are packaged locally; their executable code is not downloaded from that API origin.
 
-Both `beta` and `latest` versions published with this default use the production API address. Tags select package versions, not deployments. Our test apps must explicitly set `baseUrl: "https://api.dev.tinker.cash"` and configuration-sync `origin` to the same address. `dev.tinker.cash` is the test main site/Admin, not the Go API entry. The API hosts forward through Vercel to their respective Go Indianapolis services; routing and business readiness have separate acceptance.
+Both `beta` and `latest` versions published with this default use the production API address. Tags select package versions, not deployments. The separate test API at `https://api.dev.tinker.cash` requires its own credentials and a client matching its deployed protocol; it is outside this production 0.9 rollout.
 
-For our own testing, always require a test-service address instead of relying on the production default:
-
-Set `INDIANA_TEST_BASE_URL=https://api.dev.tinker.cash` and use the native Cloud SQL test App/Key. A production Key or a retained Supabase Key cannot authenticate against that test environment.
-
-```ts
-const testBaseUrl = process.env.INDIANA_TEST_BASE_URL;
-if (!testBaseUrl) throw new Error("Set INDIANA_TEST_BASE_URL explicitly");
-
-const scope = { projectId: testProjectId, environment: "sandbox" as const };
-const server = createIndianaServer({
-  baseUrl: testBaseUrl,
-  apiKey: testServerKey,
-  scope,
-});
-const customer = createIndiana({ baseUrl: testBaseUrl, scope });
-const configuration = createConfigurationSync({
-  origin: testBaseUrl,
-  scope: { ...scope, environmentId: testEnvironmentId },
-});
-```
-
-Use the same explicit address for every client in a test run, including Funnel start/controllers and page/visual clients. Environment variables are read by the host, not automatically by the SDK. Sandbox/Live selects business scope inside the chosen service; it does not select a deployment or database. Never retry against another service automatically after an error or unknown command result.
-
-For maintainer checks, use the [SDK testing guide](../../docs/sdk-selfserve.md#maintainer-api-origin-testing). SDK contract fixtures and actual GOP business tests have separate owners.
+Use the same API origin for every client and configuration-sync instance in one integration. Sandbox/Live selects business scope inside that deployment, not a different service or database. Never retry against another service automatically after an error or unknown command result. Maintainer test runs require an explicit target and must not fall back to production; follow the [SDK testing guide](../../docs/sdk-selfserve.md#maintainer-api-origin-testing).
 
 ## Create a Customer Session from a trusted backend
 
@@ -126,7 +103,7 @@ const user = await requireSignedInUser(request);
 const { customer } = await indiana.getOrCreateCustomer({
   externalUserId: user.id,
 });
-const { customerToken } = await indiana.createCustomerSession(customer.id);
+const session = await indiana.createCustomerSession(customer.id);
 ```
 
 Keep the Secret Key on your trusted backend. A Customer ID supplied by a browser is not proof of login. Give each Customer Token only to the corresponding authenticated user. App, Sandbox/Live environment, Customer identity, permissions, and allowed origins are checked independently. The SDK holds Customer credentials in memory; destroy the previous view and clear credentials when signing out or changing accounts.
@@ -138,13 +115,13 @@ const indiana = createIndiana({
   baseUrl,
   scope: { projectId, environment: "sandbox" },
 });
-indiana.identify(customerToken);
+indiana.identify(session);
 const { holdings } = await indiana.readHoldings();
 // On sign-out:
 indiana.reset();
 ```
 
-Indiana maintains an active Customer session through ordinary SDK requests, using the same token and session row. The validity window is 24 hours with a 30-day absolute limit; there is no merchant renewal timer or additional refresh token. Revocation and issuer expiry still apply, and an expired authorization needs a new verified login. See [Customer credentials](../../docs/customer-credentials.md).
+The SDK refreshes its Access/Refresh pair directly with GOP. Access lasts at most one hour, Refresh at most 24 hours per rotation, within the original 30-day session limit. Successful rotation preserves the Customer identity and pending work; a definitive refresh refusal or expired Refresh Token clears the credentials and requires a new verified login. Business requests do not extend expiry or automatically replay after refresh. Revocation and issuer expiry still apply. See [Customer credentials](../../docs/customer-credentials.md).
 
 Customer updates are partial patches and do not use a Customer revision. When a Guest signs in to an existing Customer, the response reports `switched: true`. Resources and history keep their original owner; create a new Session/Funnel for the target Customer. Guest financial facts are not merged.
 
@@ -303,15 +280,15 @@ import {
   createIndiana,
 } from "@tinkerlandai/indiana-sdk";
 
-// Target test API; requires separately accepted domain forwarding and runtime readiness.
-const testApiUrl = "https://api.dev.tinker.cash";
+// Use a Sandbox App and credentials issued by the production deployment.
+const apiUrl = "https://api.tinker.cash";
 const scope = { projectId, environment: "sandbox" as const, environmentId };
 const configuration = createConfigurationSync({
-  origin: testApiUrl,
+  origin: apiUrl,
   scope,
 });
 const indiana = createIndiana({
-  baseUrl: testApiUrl,
+  baseUrl: apiUrl,
   scope: { projectId, environment: "sandbox" },
   configuration,
 });
@@ -403,8 +380,8 @@ export async function showBanner(
   onContinue: (intent: ContentActionIntent) => Promise<void>,
 ) {
   const indiana = createIndiana({
-    baseUrl: "https://api.dev.tinker.cash",
-    scope: { projectId: "<TEST_APP_UUID>", environment: "sandbox" },
+    baseUrl: "https://api.tinker.cash",
+    scope: { projectId: "<APP_UUID>", environment: "sandbox" },
   });
   indiana.identify(customerToken);
   const { content } = await indiana.resolveContent({
@@ -448,3 +425,5 @@ 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.

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 [English](./README.md)
 
-本页使用 SDK 0.8.4、`https://api.dev.tinker.cash` 与测试 App 凭据（协议 0.8）。切换前核对[环境状态](../../docs/development-status.md)。SDK 默认仍指向生产 API，本页示例必须显式设置 `baseUrl`。
+本页示例面向 SDK 0.9.1 和协议 0.9，使用 `https://api.tinker.cash` 以及生产部署内签发的 Sandbox App／凭据。Sandbox 仍属于生产数据，不能复用独立测试部署的凭据。运行前核对[环境状态](../../docs/development-status.md)，确认服务已就绪。
 
 # @tinkerlandai/indiana-sdk
 
@@ -9,10 +9,10 @@
 **IAM 的源码扫描、生成、校验和上传属于独立构建包 `@tinkerlandai/indiana-iam`。** 普通业务 SDK 只保留 GB visual 应用页面变更所需的运行时 release 绑定。完整定义见 [SDK 边界](../../docs/sdk-architecture.md) 与 [IAM 构建包](../iam/README.md)。
 
 ```sh
-npm install --save-exact @tinkerlandai/indiana-sdk@0.8.4
+npm install --save-exact @tinkerlandai/indiana-sdk@0.9.1
 ```
 
-SDK 0.8.4 要求 HTTP 协议 0.8。安装版本须与运行服务匹配；发布包不会部署服务端。实际发布、标签与环境验收范围见 [SDK 发布总账](../../docs/sdk-releases.md) 和 [开发状态](../../docs/development-status.md)。
+SDK 0.9.1 要求 HTTP 协议 0.9。安装版本须与运行服务匹配；发布包不会部署服务端。实际发布、标签与环境验收范围见 [SDK 发布总账](../../docs/sdk-releases.md) 和 [开发状态](../../docs/development-status.md)。
 
 数据／会话层负责公开 JSON、完整性校验和鉴权操作；展示宿主将会话接口接入打包的屏幕渲染器，渲染器消费已提供的数据并返回动作意图。客户端按需加载展示；`/server` 入口使用商户后端的受限 Server Key，不加载屏幕展示。SDK 本地检查不替代运行时授权或付款核实。后台 Preview 为同一个展示宿主提供模拟会话和数据。
 
@@ -21,7 +21,7 @@ SDK 0.8.4 要求 HTTP 协议 0.8。安装版本须与运行服务匹配；发布
 普通 script 标签复用 npm 浏览器实现，无需打包工具：
 
 ```html
-<script src="https://dev.tinker.cash/sdk.js"></script>
+<script src="https://tinker.cash/sdk.js"></script>
 <script type="module">
   const {
     createIndiana,
@@ -32,11 +32,11 @@ SDK 0.8.4 要求 HTTP 协议 0.8。安装版本须与运行服务匹配；发布
     mountContent,
   } = await Indiana.ready;
   const client = createIndiana({
-    baseUrl: "https://api.dev.tinker.cash",
+    baseUrl: "https://api.tinker.cash",
     scope: { projectId: "<APP_UUID>", environment: "sandbox" },
   });
-  // 从验证登录后的自有后端接口获取 customerToken。
-  // client.identify(customerToken);
+  // 从验证登录后的自有后端获取完整 session 凭据对。
+  // client.identify(session);
   // await client.readHoldings();
   // client.track("page_viewed", { page: location.pathname });
   // await client.flush();
@@ -94,11 +94,9 @@ JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@ind
 
 包含此默认值的版本无论标记为 `beta` 或 `latest`，都使用生产 API 地址。标签选择包版本，不选择服务环境。两套 API 入口经 Vercel 转发到各自 Go Indianapolis，入口和业务就绪分别验收。
 
-我们自己测试时，宿主必须显式要求 `INDIANA_TEST_BASE_URL`，缺失就报错，不回落生产默认值。同一轮 Server、Customer、Funnel、页面／视觉客户端的 `baseUrl` 和配置同步的 `origin` 使用同一个测试地址；环境变量由宿主读取，SDK 不自动读取。`environment: "sandbox"` 只选择该服务内的业务环境，不选择部署或数据库。
+同一次接入中的所有客户端与配置同步实例使用同一个 API origin。`environment: "sandbox"` 只选择该部署内的业务环境，不选择另一套服务或数据库；错误或未知写入结果不能触发跨环境自动重试。
 
-测试 API 地址为 `https://api.dev.tinker.cash`，测试主站／Admin 使用 `dev.tinker.cash`。测试应用配置 `INDIANA_TEST_BASE_URL=https://api.dev.tinker.cash`，使用测试环境自己的 App／Key，并核验权限与集成配置。默认地址保持生产 `https://api.tinker.cash`，由测试应用显式覆盖。
-
-维护者验证入口见[测试流程](../../docs/sdk-selfserve.md#maintainer-api-origin-testing)。SDK 契约夹具与真实 GOP 业务测试分别负责，不以旧版本通过数描述当前能力。
+独立测试 API `https://api.dev.tinker.cash` 不在本次生产 0.9 升级范围内，必须使用与其已部署协议匹配的 SDK 和测试凭据。维护者测试必须显式指定目标，不能回落生产默认值，见[测试流程](../../docs/sdk-selfserve.md#maintainer-api-origin-testing)。
 
 ## 从可信后端创建 Customer Session
 
@@ -117,10 +115,10 @@ const user = await requireSignedInUser(request);
 const { customer } = await indiana.getOrCreateCustomer({
   externalUserId: user.id,
 });
-const { customerToken } = await indiana.createCustomerSession(customer.id);
+const session = await indiana.createCustomerSession(customer.id);
 ```
 
-Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将 Customer Token 交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
+Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将完整 Access／Refresh 凭据对交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
 
 ```ts
 import { createIndiana } from "@tinkerlandai/indiana-sdk";
@@ -129,13 +127,13 @@ const indiana = createIndiana({
   baseUrl,
   scope: { projectId, environment: "sandbox" },
 });
-indiana.identify(customerToken);
+indiana.identify(session);
 const { holdings } = await indiana.readHoldings();
 // 退出账号时：
 indiana.reset();
 ```
 
-Indiana 在普通 SDK 请求中延续同一 Customer 会话和 Token，默认有效窗口 24 小时、最长 30 天；无需商户续期定时器，也不增加 Refresh Token。撤销和 Key 到期继续生效，授权过期后需要重新认证。见[Customer 凭据](../../docs/customer-credentials.md)。
+SDK 通过 Refresh Token 直接向 GOP 轮换凭据；Access 最长 1 小时，Refresh 每次轮换最长 24 小时，原会话最长 30 天。成功轮换保留当前 Customer 身份和待处理业务；刷新被明确拒绝或 Refresh Token 过期时清除凭据，需要重新验证登录。普通业务请求不延期，刷新不会自动重放业务写入。撤销和 Key 到期继续生效。见[Customer 凭据](../../docs/customer-credentials.md)。
 
 Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
 
@@ -308,8 +306,8 @@ export async function showBanner(
   onContinue: (intent: ContentActionIntent) => Promise<void>,
 ) {
   const indiana = createIndiana({
-    baseUrl: "https://api.dev.tinker.cash",
-    scope: { projectId: "<TEST_APP_UUID>", environment: "sandbox" },
+    baseUrl: "https://api.tinker.cash",
+    scope: { projectId: "<APP_UUID>", environment: "sandbox" },
   });
   indiana.identify(customerToken);
   const { content } = await indiana.resolveContent({
@@ -336,3 +334,5 @@ export async function showBanner(
 需要加快点击打开时，可提前为当前 Customer 读取内容，再调用根入口的 `prepareContent(container, options)`，参数与 `mountContent` 相同。它提前加载展示模块、校验文档并启动 iframe，等首次渲染后返回句柄；点击时同步调用 `handle.show()`，直接显示同一个 iframe。准备期间不打开弹窗、不抢焦点、不执行动作。句柄用于一次展示，重复 `show()` 不重复挂载；下一次展示需重新准备。
 
 可传入 `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` 共用刷新生命周期。

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

@@ -1,5 +1,5 @@
 import { LanguageModelV4Usage, LanguageModelV4Middleware } from '@ai-sdk/provider';
-import { F as FoundationApi, A as ApiInput } from './api-XDc4pRlN.js';
+import { F as FoundationApi, A as ApiInput } from './api--Zf0gxfj.js';
 import { z } from 'zod';
 
 declare const tokenCounts: z.ZodObject<{
@@ -104,7 +104,7 @@ declare function createAiPricing(options?: AiPricingOptions): {
             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;
+            reservationStatus: "expired" | "pending" | "confirmed" | "released" | null;
             expiresAt: string | null;
             allocations: ({
                 funding: "prepaid";
@@ -175,7 +175,7 @@ declare function createConfiguredAiPricing(client: Pick<FoundationApi, "readAiPr
             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;
+            reservationStatus: "expired" | "pending" | "confirmed" | "released" | null;
             expiresAt: string | null;
             allocations: ({
                 funding: "prepaid";