@tinkerlandai/indiana-sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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.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.
+- Converge current request/response contracts and regenerate native shell assets. Include canonical Stripe payment setup, subscription administration and License client contracts. Server availability is documented in README; unfinished billing authorization, batch/conflict, Reward Product and native execution remain outside accepted scope.
+- Keep one npm package with browser, server, popup, OpenRouter and native-shell entries. Swift/Kotlin store acceptance and publication are deferred.
+
+- Move Local/Remote evaluation policy to each Funnel. New Funnels default to Local; Owner/Admin manage it in Funnel settings. API keys only authenticate and authorize calls; one key can call different modes. Remove `remoteEval`: `configuration()` reads the Funnel mode and the server enforces rule downloads and API decisions.
+- Add `configuration()` with public Funnel topology and versioned resource references. Remote payloads omit rules and commercial parameters; Local payloads include pure evaluation configuration.
+- Keep business actions server-authoritative. Existing Funnels migrate explicitly to Remote; one API key can call both Local and Remote Funnels.
+
+## 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,91 @@
-# 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 的 JavaScript／TypeScript SDK，包含浏览器、Node.js、屏幕渲染与可选 AI 用量集成。`0.1.0` 以 `beta` 标签分发；服务端和数据库必须使用匹配的当前协议。本版本有破坏性变更，不提供旧名称、旧输入或旧数据模型的兼容层。
+
+```sh
+npm install @tinkerlandai/indiana-sdk@0.1.0
+```
+
+## 一个 npm 包，五个入口
+
+| 导入入口                                 | 用途                                                        |
+| ---------------------------------------- | ----------------------------------------------------------- |
+| `@tinkerlandai/indiana-sdk`              | 浏览器 Customer、Funnel、Feature 与独立 Paywall 客户端      |
+| `@tinkerlandai/indiana-sdk/server`       | 可信 Node.js 后端、Customer Session、业务写入和 Funnel 决策 |
+| `@tinkerlandai/indiana-sdk/popup`        | 独立屏幕渲染、清洗和预览                                    |
+| `@tinkerlandai/indiana-sdk/openrouter`   | 可选 OpenRouter 用量集成，需要安装对应 peer dependency      |
+| `@tinkerlandai/indiana-sdk/native-shell` | 原生 WebView 的静态 Funnel shell 资源；不代表商店购买验收   |
+
+JavaScript 与 TypeScript 共用本包，声明文件随包提供。内部 `@indiana/contracts` 在构建时内联，接入方无需安装私有包。Swift 和 Kotlin 使用各自的包管理生态，不在本次 npm 发布范围内。
+
+## 从可信后端创建 Customer Session
+
+```ts
+import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server";
+
+const indiana = createIndianaServer({
+  baseUrl: process.env.INDIANA_BASE_URL!,
+  apiKey: process.env.INDIANA_SECRET_KEY!,
+  scope: {
+    projectId: process.env.INDIANA_PROJECT_ID!,
+    environment: "sandbox",
+  },
+});
+const user = await requireSignedInUser(request);
+const { customer } = await indiana.getOrCreateCustomer({
+  externalUserId: user.id,
+});
+const { customerToken } = await indiana.createCustomerSession(customer.id);
+```
+
+Secret Key 仅保存在可信后端。浏览器传入的 Customer ID 不能作为登录证明；将 Customer Token 交给对应的已登录用户。App、Sandbox／Live、Customer、权限和允许来源分别校验。SDK 在内存中持有客户凭据；退出或切换身份时销毁旧视图并清理凭据。
+
+```ts
+import { createIndiana } from "@tinkerlandai/indiana-sdk";
+
+const indiana = createIndiana({
+  baseUrl,
+  scope: { projectId, environment: "sandbox" },
+});
+indiana.identify(customerToken);
+const { holdings } = await indiana.readHoldings();
+// 退出账号时：
+indiana.reset();
+```
+
+Customer 使用原始业务字段；资料更新是部分 patch，没有 Customer revision。Guest 登录到已有 Customer 时返回 `switched: true`，资源和历史保留原归属，接入方应为目标 Customer 创建新 Session／Funnel；不合并旧 Guest 的财务事实。
+
+## Funnel、Feature 与独立 Paywall
+
+可信后端通过 `createFunnelStartClient().start()` 提交 `funnelId`、持久保留的 `requestId`、`customerToken`、`locale` 和 `parameters`。响应丢失时保留原编号和输入重试。商业参数放在 `parameters.commerce`。运行有独立的 Run Token，不能据此切换 Customer。
+
+浏览器使用 `createFunnelRunController` 与 `showFunnelRun`。控制器负责当前协议的命令、读取、重试、恢复和订阅；展示句柄提供 `refresh()` 和 `destroy()`。业务操作按当前发布节点委派给服务端，客户端声明或重定向不构成付款证明。
+
+Local／Remote 求值策略由每个 Funnel 决定。`createFunnelDecisionClient` 支持当前 `configuration()`、`features()`、提交和结果读取；`createFeatureClient` 以 `generation` 标识配置。Local 下载的规则对客户端可见；敏感决策应使用 Remote 和可信业务事实。
+
+Offering 固定 Product Version 的范围与层级。Paywall 固定已发布 Offering Version，并独立选择显示的 Product 子集、分组、顺序和默认项。`createPaywallStartClient`、`createPaywallSession`、`showPaywall` 使用独立 Paywall Session，不创建占位 Funnel。付款完成后重新查询权益，业务后端仍须重新鉴权并幂等扣减用量。
+
+## Web 商业能力与当前服务边界
+
+当前服务端实现了 Customer／Guest、Entitlement 检查、持有与账本读取、用量和余额、Coupon／推荐码、Offering／独立 Paywall，以及配置后的 Stripe Sandbox attach、支付方式收集、订阅验证／更新／退款／Trial 和 License 分配路径。每个操作仍受已配置的支付账号、执行模式、Product／Price 条款和当前实现范围约束；接口存在不表示任意组合已验收。
+
+Stripe 环境的 `autumn` 模式由 Indiana 执行；`record_only` 返回交给商户后端执行的指令。两种模式都从验证后的 Stripe 事实写入财务与权益。支付方式收集本身不产生扣款、Invoice 或额外权益。报价／确认／读取使用各自持久操作 ID；同一请求编号不能更换输入。
+
+本 Beta **不认证完整商业功能或生产运行**。当前仍未接通的服务包括：
+
+- 订阅批处理及冲突管理。
+- Billing Authorization 的准备／确认／撤销、Billing Coupon 列表和账单调整确认。
+- `claimRewardProduct` 的完整交付。
+- Apple／Google 购买、通知、收据恢复和商店验收；原生协议入口保留为后续配套，当前不可据此承诺交付。
+
+Live 商业执行仍有显式服务端门禁。其他 Product／Price、Entity、订阅追加和数量组合，以匹配服务端的实际能力为准；不自动回退到旧实现。
+
+## AI 用量
+
+`/server` 提供 AI SDK 用量中间件；`/openrouter` 提供 OpenRouter 包装器。宿主必须提供每次调用的持久幂等键、usage／quote 存储及恢复回调。恢复时重放原报价的扣款，不重新运行模型。密钥始终留在可信后端。
+
+## 发布与验收
+
+npm 发布不部署 Web 服务、不应用数据库迁移，也不发布 Swift／Kotlin 包。安装消费、类型、离线单元和构建检查，与真实 Auth／RLS、Stripe、原生商店、浏览器和线上部署分别记录；局部通过不代表整套产品验收。
+
+版本、冻结产物哈希和 registry 回读见 [发布总账](../../docs/sdk-releases.md)；当前架构与实现边界见 [开发状态](../../docs/development-status.md)。

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.