@tinkerlandai/indiana-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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.

package/README.md

@@ -1,12 +1,20 @@
 # @tinkerlandai/indiana-sdk
 
-Indiana 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。`0.2.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.2.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.2.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,6 +64,29 @@ 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`、`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` 明确拒绝。
@@ -67,6 +99,26 @@ Customer 使用原始业务字段；资料更新是部分 patch，没有 Custome
 
 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 商业能力与当前服务边界

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.