@tinkerlandai/indiana-sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.3.0
+
+- 0.3.0 uses wire protocol 0.3 for published screen render references. Obsolete 0.2 and its fixed headerless identity are explicitly refused before business execution; no pre-1.0 compatibility adapter is provided. Existing 0.2.0 publication evidence remains immutable.
+- Add `ScreenPreviewHandle.resizeViewport(height)` to resize previews while preserving their active document and interaction state.
+- Keep Funnel background reads separate from the command lock, so polling cannot swallow a screen action. Unchanged GET/shown data preserves the mounted form and selection.
+- Clear a lost-command error when an external `controller.retry()` settles that exact command. A GET before settlement retains the error; unrelated renderer failures remain visible.
+
+- Expose error recovery, retryability, registered business reasons and Retry-After timing on IndianaError. Distinguish unavailable capabilities from missing configuration. Retain HTTP status and request references for non-JSON failures; unknown results, timeouts and lost responses require original-operation recovery and never trigger automatic retries.
+
+- Pause renderer startup deadlines while the host document is hidden, preserving the five-second visible-time budget and cancellation on ready/disposal.
+- Identify the wire protocol and package version with `X-Indiana-Protocol` / `X-Indiana-SDK-Version`; verify advertised successful-response protocols. These changes are not in the immutable published 0.2.0 tarball.
+- Add the stable-major compatibility policy, at least 12 calendar months of predecessor support and 180 days of public notice, with a pinned published-old-SDK/current-server regression gate. Current 0.x still rejects obsolete protocols. See [support policy](../../docs/sdk-versioning-and-support.md).
+
+## 0.2.0 — 2026-10-16
+
+- Breaking: server Funnel starts and decisions use `customer: { type: "id" | "externalUserId", value }`; optional `customerData` is creation-only and requires an external user reference. Remove start-body `customerToken` and decision `customerId`; no legacy compatibility. Customer-credential starts name no Customer.
+- Export `createFunnelCampaignClient` from `/server` for explicit campaign decisions and starts with durable suppression. Validate returned Funnel and Customer identity before accepting a Run.
+- Use `X-Indiana-Web-View` and `X-Indiana-Telemetry-Subject` response headers. Include current renderer, native shell and Paywall recovery/lifecycle fixes.
+- Route native receipt recovery through independent `subscriptions/native/restore`, including read-only recovery. This package release does not certify or publish Apple/Google store integrations; real store acceptance remains deferred.
+
 ## 0.1.0 — 2026-10-16
 
 - Web Beta with current Indiana factories, Customer two-table identity, current Funnel runtime, Feature generation, Offering hierarchy and independent Paywall sessions. No legacy API or data compatibility.

package/README.md

@@ -1,12 +1,20 @@
 # @tinkerlandai/indiana-sdk
 
-Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。`0.1.0` 以 `beta` 标签分发；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
+Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。本包版本为 `0.3.0`，使用协议 `0.3`；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
+
+**0.3.0 / 协议 0.3** 包含独立 Feature 下发、屏幕 render reference 与当前请求头校验。历史 0.2.0 包不能连接使用协议 0.3 的 HTTP handlers；显式或无版本头的旧 0.2 请求都在业务执行前被拒绝。
 
 ```sh
-npm install @tinkerlandai/indiana-sdk@0.1.0
+npm install @tinkerlandai/indiana-sdk@0.3.0
 ```
 
-## 一个 npm 包，五个入口
+## 版本兼容与支持
+
+当前 0.x 仅支持当前协议；1.0 起同一主版本内保持兼容。新稳定主版本发布后，旧稳定主版本至少继续支持 12 个日历月，停止支持提前至少 180 天公开通知，实际日期取两者中较晚者。详见 [版本与支持政策](../../docs/sdk-versioning-and-support.md) 和公开开发文档 `/docs/release-notes#support-policy`。
+
+0.3.0 发送协议及 SDK 版本请求头，并校验成功响应的协议声明。历史 0.2.0 不发送这些请求头；服务端将无版本头的请求固定识别为 0.2，不自动跟随新协议。源码更新不会修改已有 npm 包，也不会自动部署服务端。
+
+## 一个 npm 包，六个入口
 
 | 导入入口                                 | 用途                                                        |
 | ---------------------------------------- | ----------------------------------------------------------- |
@@ -15,6 +23,7 @@ npm install @tinkerlandai/indiana-sdk@0.1.0
 | `@tinkerlandai/indiana-sdk/popup`        | 独立屏幕渲染、清洗和预览                                    |
 | `@tinkerlandai/indiana-sdk/openrouter`   | 可选 OpenRouter 用量集成，需要安装对应 peer dependency      |
 | `@tinkerlandai/indiana-sdk/native-shell` | 原生 WebView 的静态 Funnel shell 资源；不代表商店购买验收   |
+| `@tinkerlandai/indiana-sdk/page`         | 匿名商户页面的网址实验；使用公开的 App environment ID       |
 
 JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@indiana/contracts` 在构建时内联，接入方无需安装私有包。Swift 和 Kotlin 使用各自的包管理生态，不在本次 npm 发布范围内。
 
@@ -55,14 +64,61 @@ indiana.reset();
 
 Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
 
+## Optional stable fingerprint
+
+`fingerprint` is a host-supplied stable deduplication signal, such as an installation identifier. Initialize and retain it before the first Guest/Customer request, independently of login and credentials. Reuse it across Guest identification, account changes and session renewal. The SDK does not collect or generate it.
+
+```ts
+// Trusted backend fragment: installationSignal is retained by the host;
+// verifiedUser.id comes from the host's authenticated login.
+const { customer } = await indiana.getOrCreateCustomer({
+  externalUserId: verifiedUser.id,
+  fingerprint: installationSignal,
+});
+// On Guest creation, use that same installationSignal and separately
+// retain/reuse guestToken for creation retries.
+await indiana.createGuestCustomer({
+  guestToken: retainedGuestToken,
+  fingerprint: installationSignal,
+});
+```
+
+Indiana keeps the first supplied signal as an environment-scoped hash; later values do not replace it. Missing input is valid and retains per-Customer trial deduplication. `unique_fingerprint` additionally deduplicates the configured Product trial across Customers sharing the signal. Business user IDs do not identify an installation; Customer/Guest/session tokens and request IDs have their own lifecycles and should not be fingerprints.
+
+On Web, an independent first-party installation cookie can retain the signal. Clearing it or changing browser storage can produce a new value; sign-out need not reset it. Native hosts persist a random installation signal and define reinstall, restore and reset behavior. This signal is separate from device attestation and authentication. See the Web developer documentation's `/docs/identity#fingerprint` guide for executable HTTP host examples. Trial conflicts remain generic to clients; retain `X-Request-Id` for server-side diagnosis.
+
 ## Funnel、Feature 与独立 Paywall
 
-可信后端通过 `createFunnelStartClient().start()` 提交 `funnelId`、持久保留的 `requestId`、`customerToken`、`locale` 和 `parameters`。响应丢失时保留原编号和输入重试。商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
+可信后端通过 `createFunnelStartClient().start()` 提交 `funnelId`、持久保留的 `requestId`、`customer`、`locale` 和 `parameters`。`customer` 为 `{ type: "id", value: customerId }` 或 `{ type: "externalUserId", value: verifiedUser.id }`。后者可以同时提供仅用于新建的 `customerData`，需要 `customers:write` 权限；已有 Customer 不因此更新。服务端响应返回 `customerId`，后端再为它签发 Customer Session。旧的 start-body `customerToken` 和 decision `customerId` 明确拒绝。
+
+`createFunnelClient({ customerToken, ...options })` 用于已持有 Customer 凭据的客户端；其 `start()` 不指定 `customer` 或 `customerData`，始终以凭据所属 Customer 运行。响应丢失时保留原编号和输入重试，商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
+
+`createFunnelDecisionClient` 的 `submit/decide` 与 `/server` 的 `createFunnelCampaignClient` 同样使用明确的 `customer` 引用。Campaign 客户端提供显式 `decide/start`；受频率或进行中运行限制时，`start` 返回 `suppressed` 和重试时间，不伪造 Run 凭据。Run 实际展示后才提交 `shown`，不能用页面关闭或本地存储代替持久的展示事实。
 
 浏览器使用 `createFunnelRunController` 与 `showFunnelRun`。控制器负责当前协议的命令、读取、重试、恢复和订阅；展示句柄提供 `refresh()` 和 `destroy()`。业务操作按当前发布节点委派给服务端，客户端声明或重定向不构成付款证明。
 
 Local／Remote 求值策略由每个 Funnel 决定。`createFunnelDecisionClient` 支持当前 `configuration()`、`features()`、提交和结果读取；`createFeatureClient` 以 `generation` 标识配置。Local 下载的规则对客户端可见；敏感决策应使用 Remote 和可信业务事实。
 
+### 独立 Feature（0.3 源码候选）
+
+后端 Key 显式授予 `features:read` / `events:write`，通过现有 Customer/Guest Session 交给浏览器，不使用新的凭证种类。
+
+```ts
+const flags = await indiana.features({ attributes: { country: "CA" } });
+const enabled = flags.getFeatureValue("new-checkout", false);
+const unsubscribe = flags.subscribe(() =>
+  updateView(flags.isOn("new-checkout")),
+);
+flags.setAttributes({ country: "US" });
+indiana.track("Checkout Viewed", { source: "pricing" });
+await indiana.flush();
+// 页面卸载时：
+unsubscribe();
+flags.destroy();
+```
+
+每个 flag 默认本地计算，Owner/Admin 可切换为服务器计算。服务器 flag 只下发键与结果，首次结果到达前使用调用方默认值；属性变化立即丢弃旧结果。名单哈希不等于保密，敏感规则应使用服务器计算。本地 Funnel 不得依赖服务器 flag，切换时也会校验仍在运行的历史版本。`identify` / `reset` 会释放旧身份的功能实例和事件队列。
+
 Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
 
 ## Web 商业能力与当前服务边界
@@ -73,10 +129,10 @@ Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给
 
 本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
 
-- 订阅批处理及冲突管理。
-- Billing Authorization 的准备／确认／撤销、Billing Coupon 列表和账单调整确认。
+- 订阅批处理。冲突查询／重试已有对应服务，但仍需匹配部署及业务前置条件。
+- Postpaid Billing Authorization、Billing Coupon 列表和账单调整确认。当前 AutoTopup consent 的准备／确认／撤销已有服务，不能据此推定其他授权类型可用。
 - `claimRewardProduct` 的完整交付。
-- Apple／Google 购买、通知、收据恢复和商店验收；原生协议入口保留为后续配套，当前不可据此承诺交付。
+- Apple／Google 真实商店验收。当前独立购买／恢复的协议及部分服务实现不代表商店已验收；`createNativeReceiptClient().recover()` 使用 `subscriptions/native/restore`，不再发送旧 Funnel 原生恢复命令。
 
 Live 商业执行仍有显式服务端门禁。其他 Product／Price、Entity、订阅追加和数量组合，以匹配服务端的实际能力为准；不自动回退到旧实现。
 

package/THIRD_PARTY_NOTICES.md

@@ -17,3 +17,30 @@ 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.
+
+# @noble/hashes 2.4.0
+
+SHA-256 for hashed saved-group membership is bundled from `@noble/hashes` 2.4.0.
+Source: https://github.com/paulmillr/noble-hashes
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+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.