td-feature-node 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# TD Feature Node.js 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.
+ThinkingData 实验平台的 Node.js 服务端 SDK，分阶段实现一期远端分流。
+
+**当前版本：0.0.2。远端分流、曝光、完整服务 Demo、HTTPS、资源压力及发布检查已补齐；自动曝光默认关闭。0.0.2 待发布，0.0.1 已发布；未实现本地分流。真实项目与跨操作系统验收范围另行列明。**
+
+## 分阶段交付
+
+| 阶段 | SDK | Demo | 状态 |
+| --- | --- | --- | --- |
+| S1 | npm 包、类型声明、初始化与关闭 | 初始化示例 | 已完成 |
+| S2 | RCC 请求、签名、响应解码、Feature 取值 | Mock RCC / 真实 RCC 两种运行方式 | 已完成本地验收 |
+| S3 | 单次超时、可选重试、有界并发/排队、结果缓存 | 重试恢复、缓存、过载和超时场景 | 已完成本地验收 |
+| S4 | Java 对齐的手动/自动曝光、去重、队列、采集适配器 | 实际使用结果后曝光 | 已完成本地验收 |
+| S5 | 完整兼容矩阵、负载、内部候选包验收 | 完整 API、进程关闭、显式业务回退 | 本机自动化验收；外部项保留 |
+
+详见 [接入指南](docs/INTEGRATION.md)、[任务清单](docs/TASKS.md)、[Java 对齐基准](docs/JAVA_CONTRACT.md)、[兼容性记录](docs/COMPATIBILITY.md)、[发布验收与保留项](docs/RELEASE.md)。
+
+## 使用
+
+当前待发布版本为 `td-feature-node@0.0.2`。npm 安装包只包含 `dist/`、README、包信息和纯生产依赖发布锁；完整文档与 Demo 保留在源码仓库，不随安装包分发。本文的构建、Demo 和验收命令均在源码仓库根目录执行。
+
+先构建并验证本地包：
+
+```sh
+npm ci
+npm test
+npm run verify:package
+```
+
+0.0.2 发布后，在消费项目从 registry 安装；默认安装无需 TypeScript、Prettier 或开发依赖：
+
+```sh
+npm install td-feature-node@0.0.2
+```
+
+```js
+const { createClient, SplitMode } = require('td-feature-node');
+const client = createClient({
+  splitMode: SplitMode.REMOTE,
+  appId: 'your_app_id',
+  serverUrl: 'https://your-rcc-server.example.com',
+  timeout: 1000,
+  retryTimes: 0,
+  maxConcurrentRequests: 20,
+  maxQueueSize: 0,
+  enableCache: false,
+  autoExposure: false
+});
+
+client.fetch({
+  accountId: 'user_123',
+  distinctId: 'device_456',
+  featureKeys: ['checkout_button'],
+  customParams: { country: 'CN' }
+}).then(function (config) {
+  const feature = config.features['checkout_button'];
+  const text = feature ? feature.asString('购买') : '购买';
+  console.log(text, feature && feature.experiment && feature.experiment.experimentId);
+  if (feature) client.expose(feature, { scene: 'checkout' }); // 在实际使用值后曝光。
+}, function (error) {
+  // 网络或协议错误由业务显式处理，不会伪装成成功的空配置。
+  console.error(error.code, error.message);
+}).then(function () {
+  return client.close(); // 单次脚本示例；服务端应复用 Client，在进程退出时关闭。
+}, function (error) {
+  console.error(error.code, error.message);
+  return client.close();
+});
+```
+
+createClient() 不访问网络。`splitMode` 默认 `SplitMode.REMOTE`，也可直接传 `'REMOTE'`。`SplitMode.LOCAL` 仅作后续扩展预留，当前传入会同步抛出 `INVALID_CONFIG`。`fetch()` 在缓存未命中时请求 RCC，默认不排队、不自动重试；需要时可显式开启。身份必须至少包含一个非空字符串。不指定 Feature 列表或列表为空时请求全部 Feature。`customParams` 只接受 JSON 数据，保留身份、语言和 Feature 字段由 SDK 覆盖；使用原生 `JSON.stringify`，对象和数组中的 null 均保留，未提供的账号/设备字段省略。
+
+## 配置
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `appId` | 必填 | 平台项目 ID |
+| `serverUrl` | 必填 | 远端决策与采集共用的 HTTP(S) 基础地址 |
+| `splitMode` | `SplitMode.REMOTE` | 初始化时选择分流模式；当前仅实现 REMOTE，LOCAL 为预留值且会报错 |
+| `timeout` | 5000 ms | 单次 HTTP 阶段超时，含连接池等待、连接和响应读取；到期中止请求 |
+| `maxHttpConnections` | 20 | 同一 RCC 的连接池最大连接数 |
+| `maxConcurrentRequests` | 与 `maxHttpConnections` 相同 | 活跃 fetch 上限，不能大于连接数；解码和退避期间保留槽位 |
+| `maxQueueSize` | 0 | 默认不排队；可设 0–1000000，并发及等待位置满时返回 `QUEUE_FULL` |
+| `retryTimes` | 0 | 默认不自动重试；首次请求后的最大重试次数，范围 0–10 |
+| `retryInterval` | 500 ms | 首次退避间隔；允许 0 |
+| `retryStrategy` | `EXPONENTIAL_BACKOFF` | 可选 `FIXED_INTERVAL` |
+| `retryJitter` | true | 在退避区间内作 full jitter 随机延迟 |
+| `maxRetryInterval` | 30000 ms | 重试等待上限；`Retry-After` 超过此值时停止重试，返回原 HTTP 错误 |
+| `enableCache` | false | 显式启用成功结果缓存 |
+| `cacheExpireTime` | 86400 秒 | RCC TTL 非正数时的回退；正数 RCC TTL 优先 |
+| `maxCacheSize` | 10000 | LRU 缓存条目上限；0 不存储 |
+| `maxDecompressedResponseBytes` | 10 MiB | `data` 字段 Base64/GZIP 解压后的上限，与 Java 默认值一致 |
+| `autoExposure` | false | 开启后首次读取原始/类型化值时自动曝光 |
+| `exposureDedupMaxSize` | 100000 | 曝光去重条目上限，独立于结果缓存 |
+| `exposureDedupExpireSeconds` | 86400 秒 | 去重 TTL，读取不续期 |
+| `exposureQueueCapacity` | 10000 | 等待曝光容量，范围 1–1000000；另有一个活跃任务 |
+| `exposureBatchSize` | 100 | 自建采集器每批事件数，范围 1–10000 |
+| `exposureFlushIntervalMillis` | 1000 ms | 自建采集器不足一批时的最长缓冲时间 |
+| `exposureFlushTimeoutMillis` | 5000 ms | flush/close 等待预算；自建采集请求的单次 I/O 预算 |
+| `tdAnalytics` | 未指定 | 复用业务已有 Node 采集实例，外部实例由业务关闭 |
+| `exposureAdapter` | 未指定 | 自定义异步采集适配器，与 `tdAnalytics` 互斥，外部实例由业务关闭 |
+| `tlsCa` | 运行时默认信任根 | 显式 PEM CA 字符串/数组会替换默认 CA 列表，作用于 RCC/自建采集 HTTPS，仍检查主机名 |
+
+`timeout` 只控制每次 HTTP 尝试，重试会重新计时；排队、重试等待和 RCC 字段解码不计入该 HTTP 超时。整次 fetch 的耗时会随尝试次数与退避等待增加，可用 AbortSignal 提前取消。完整语义和示例见 [S3 请求可靠性与缓存](docs/RELIABILITY.md)。
+
+默认最多 20 个活跃 fetch，没有等待队列，失败只尝试一次。显式开启排队或重试后，整次 fetch 仍没有 SDK 内置的总期限；有业务截止时间时传入带期限的 signal。较早版本默认重试 3 次、排队 1000 项，接入升级时需留意默认行为变化。
+
+`serverUrl` 不接受认证信息、查询参数或 fragment，末尾 `/` 会归一化。未知或未实现的配置会报错，当前不能设置本地模式。
+
+## Feature 读取
+
+`fetch()` 返回只读的普通对象：
+
+```js
+{
+  features: { checkout_button: feature },
+  ttl: 60 // RCC 原始 TTL，单位秒，不是缓存剩余寿命
+}
+```
+
+通过 `result.features[key]` 查找，缺失时为 `undefined`；`Object.keys(result.features)` 枚举 Feature。字典没有原型，`__proto__`、`constructor` 等服务端 Key 也能安全读取，`experiment_detail` 不进入字典。
+
+Feature 提供 `key`、`value`、`accountId`、`distinctId`、`experiment` 和 `hasValue` 属性；转换方法为 `asString(fallback)`、`asNumber(fallback)`、`asBoolean(fallback)`、`asJson(fallback)`。省略 fallback 时默认为 null；false、0、空字符串不会被业务默认值覆盖。
+
+JSON 数字使用原生 `number`：`asString()` 按 `String(number)` 输出，对象和数组按 `JSON.stringify` 输出。例如 `1.0` 读取为 `1`、字符串为 `"1"`，`1e23` 的字符串为 `"1e+23"`。超出安全整数范围的数字遵循 JS 精度规则，`9007199254740993` 会读取为 `9007199254740992`；需要精确保留的长 ID 应由服务端作为字符串返回。
+
+`asNumber()` 接受数字或非空数字字符串，按 `Number()` 解析；例如 `"0x10"` 为 16，`"1f"`、`"0x1.8p1"`、NaN、空白字符串和其他类型返回 fallback。`asBoolean()` 接受布尔值或大小写不限的 `"true"` / `"false"` 字符串。`asJson()` 接受对象或解析为对象的 JSON 字符串；空字符串、`"null"`、数组和无效 JSON 返回 fallback。
+
+`experiment` 为 null 或只读实验信息对象；实验 ID、分组、控制组和自定义分桶直接从对象读取。不再提供重复元数据 getter，也不为远端模式构造版本/分流来源占位值。
+
+读取 `value` 或调用转换方法会触发可选自动曝光；读取元数据和 hasValue 不会。自动曝光默认关闭。展开、序列化 Feature 也会读取 value，调试元数据时只选取所需字段。
+
+未发布 API 在 rc.2 直接调整，不提供旧构造器或 getter 别名。旧候选迁移及维护约定见 [Node API 与编码约定](docs/NODE_STYLE.md)。
+
+## 曝光
+
+`client.expose(feature, properties?)` 同步返回是否入队；未匹配、重复、队列满或已关闭返回 false。返回 true 不是入库确认。入队前复制属性，所有 `#` 开头的自定义属性被忽略。远端曝光只发送 Java 已提供的元数据，不从结果的 Feature Key 推造远端元数据。
+
+自动曝光默认关闭；显式开启后，`value` 和所有类型化读取首次触发，包括返回业务默认值的情况。元数据读取与 `hasValue` 不触发；每次 fetch（包括缓存命中）的结果各自有一次触发状态，再经过 Client 级去重。队列拒绝或提交失败撤销去重标记，新结果或手动曝光可重试，同一个自动结果不会再次触发。
+
+默认采集器按 100 条一批发送，不足一批最多缓冲 1 秒；同一批共用一次 GZIP/HTTP 请求。一个批次发送期间，后续曝光留在有容量限制的队列中。`client.flush()` 立即刷新余量，`client.close()` 在关闭预算内排空。复用外部采集实例时，保留该实例的批量和定时配置；官方 `track()` 同步返回，不逐条等待网络回调或触发 flush。
+
+默认自建采集器直接依赖官方 npm 包 `thinkingdata-node@1.5.0`，首次曝光时惰性加载；也可通过 `tdAnalytics` 复用已有官方实例。SDK 只为自建实例配置传输资源、TLS、超时与关闭，不修改官方包源码。依赖与适配边界见 [曝光与采集说明](docs/EXPOSURE.md)。
+
+## 错误与关闭
+
+`fetch(request, options?)` 对参数、网络和协议错误均返回 Promise rejection。`FeatureError.code` 区分 `INVALID_CONFIG`、`INVALID_REQUEST`、`NETWORK_ERROR`、`HTTP_ERROR`、`REMOTE_ERROR`、`INVALID_RESPONSE`、`RESPONSE_TOO_LARGE`、`TIMEOUT`、`ABORTED`、`QUEUE_FULL`、`CLIENT_CLOSED`、`EXPOSURE_ERROR`。
+
+HTTP 错误附 `httpStatus`；RCC 业务错误附原始 `remoteCode` 和 Java 映射后的 `errorCode`。未知 RCC code 映射到 5000，但保留原始 code。符合 Java 兼容契约的空数据/缺失模板仍是成功的空配置，也可缓存。
+
+`clearCache()` 只清结果缓存，不清曝光去重。曝光入队后由 SDK 后台发送，业务请求无需调用或等待 `flush()`；它是测试、批处理等需要等待此前曝光处理完成时使用的可选接口。超时或适配器 flush 失败分别拒绝为 `TIMEOUT`、`EXPOSURE_ERROR`。单个曝光提交失败会撤销去重标记。
+
+`close()` 停收、取消 fetch 和退避，有限等待曝光排空并关闭自建采集实例；超时丢弃待处理曝光并取消自有连接，外部采集实例仍由业务管理。方法可重复调用，关闭后不能再次 fetch。没有本地规则轮询或采集周期定时器。flush 控制槽和关闭的具体边界见 [曝光说明](docs/EXPOSURE.md)。
+
+
+## Demo 与兼容验证
+
+```sh
+npm run demo
+npm run demo:s3
+npm run demo:s4
+npm run demo:s5
+npm run demo:service
+npm run verify:package -- /path/to/node-v12.0.0/bin/node /path/to/another/node
+npm run verify:production-install -- /path/to/node-v12.0.0/bin/node
+```
+
+基础 Demo 展示缓存，S3 展示可靠性，S4 展示曝光；S5 自动跑 API→RCC→缓存取值→曝光→采集→回退→关闭，service 提供常驻本机 API 和 SIGTERM 关闭。默认都只使用本机 Mock。完整接入和真实模式见 [指南](docs/INTEGRATION.md)、[Demo 说明](examples/node-demo/README.md)。真实 RCC、曝光入库及四进程生命周期的执行结果见 [真实联调](docs/LIVE_RCC_VERIFICATION.md)和 [PM2 验收](docs/PM2.md)，记录保留实际验收时的版本号。
+
+验收从同一 tarball 安装 SDK，执行支持版本矩阵、最低 Node 版本的 engine-strict 生产安装、JS/TS/ESM 消费、八个压力场景及官方采集实例验证。测试和 Demo 从仓库运行，通过 `TD_FEATURE_SDK_PATH` 指向已安装的 SDK，生成绑定 SHA-256 的报告。命令、指标边界和公网发布保留项见 [压力验收](docs/PERFORMANCE.md)、[发布验收](docs/RELEASE.md)。没有自动发布步骤。
+
+当前版本为 `0.0.2`，最低 Node.js **12.0.0**，发布 ES2019 CommonJS 与 `.d.ts`。`thinkingdata-node@1.5.0` 保留为生产依赖；仓库使用完整的 `package-lock.json` 安装开发工具；打包时自动生成只含生产依赖的 `npm-shrinkwrap.json`，固定支持 Node 12 的依赖树，包括 `winston@3.17.0`、`@dabh/diagnostics@2.0.3`、`triple-beam@1.3.0`、`color@3.2.1` 和 `color-string@1.9.1`。打包结束会移除临时发布锁，保留正常的仓库 npm ci 流程。仓库和发布包均不使用 overrides，不包含 vendor 或修改过的官方源码。构建工具属于开发依赖，维护构建使用现代 Node；TLS 功能测试另需 OpenSSL CLI，消费 SDK 无需该命令。Node 12.0–12.16 的 ESM 导入需启用 `--experimental-modules`，CommonJS 无需该参数。
+
+Java 固定样本已纳入测试；维护者可用 `npm run fixtures:java` 从同级 Java SDK 当前源码重新生成。该命令需要 JDK 17+、Python 3 和脚本列出的本地 Maven 缓存依赖，不修改 Java 项目，不访问真实 RCC。

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import type { ClientOptions, ResolvedClientOptions, FeatureRequest, FetchOptions, ExposureProperties } from './types';
+import { Evaluation } from './evaluation';
+import { Feature } from './feature';
+/** REMOTE evaluation client. Construction performs no network I/O. */
+export declare class Client {
+    private readonly config;
+    private readonly transport;
+    private readonly pending;
+    private readonly operations;
+    private readonly scheduler;
+    private readonly cache;
+    private readonly reporter;
+    private readonly automaticExposure;
+    private cacheGeneration;
+    private closing;
+    private closePromise;
+    constructor(options: ClientOptions);
+    get options(): Readonly<ResolvedClientOptions>;
+    get closed(): boolean;
+    fetch(request: FeatureRequest, options?: FetchOptions): Promise<Evaluation>;
+    private evaluate;
+    clearCache(): void;
+    /** Returns queue acceptance only; duplicates, unmatched results and overload return false. */
+    expose(feature: Feature | null | undefined, properties?: ExposureProperties | null): boolean;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Create one long-lived client per project; close it during application shutdown. */
+export declare function createClient(options: ClientOptions): Client;

package/dist/client.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+exports.createClient = createClient;
+const config_1 = require("./common/config");
+const errors_1 = require("./errors");
+const http_transport_1 = require("./core/http-transport");
+const request_1 = require("./core/request");
+const response_1 = require("./core/response");
+const request_operation_1 = require("./core/request-operation");
+const request_scheduler_1 = require("./core/request-scheduler");
+const config_snapshot_1 = require("./core/config-snapshot");
+const result_cache_1 = require("./core/result-cache");
+const retry_1 = require("./core/retry");
+const feature_1 = require("./feature");
+const expose_reporter_1 = require("./report/expose-reporter");
+const thinking_data_adapter_1 = require("./report/thinking-data-adapter");
+const owned_collection_adapter_1 = require("./report/owned-collection-adapter");
+/** REMOTE evaluation client. Construction performs no network I/O. */
+class Client {
+    constructor(options) {
+        this.pending = new Set();
+        this.operations = new Set();
+        this.cacheGeneration = 0;
+        this.closing = false;
+        this.config = (0, config_1.normalizeOptions)(options);
+        this.transport = new http_transport_1.HttpTransport(this.config);
+        this.scheduler = new request_scheduler_1.Scheduler(this.config.maxConcurrentRequests, this.config.maxQueueSize);
+        this.cache = this.config.enableCache
+            ? new result_cache_1.ResultCache(this.config.maxCacheSize, this.config.cacheExpireTime)
+            : null;
+        const adapter = this.config.exposureAdapter ||
+            (this.config.tdAnalytics
+                ? new thinking_data_adapter_1.ThinkingDataAdapter(this.config.tdAnalytics)
+                : new owned_collection_adapter_1.OwnedCollectionAdapter(this.config));
+        this.reporter = new expose_reporter_1.ExposeReporter(adapter, !this.config.exposureAdapter && !this.config.tdAnalytics, this.config);
+        this.automaticExposure = this.config.autoExposure
+            ? (feature) => {
+                this.reporter.report(feature);
+            }
+            : undefined;
+    }
+    get options() {
+        return this.config;
+    }
+    get closed() {
+        return this.closing;
+    }
+    fetch(request, options = {}) {
+        if (this.closing)
+            return Promise.reject(new errors_1.FeatureError('Client is closed', 'CLIENT_CLOSED'));
+        let operation;
+        try {
+            validateFetchOptions(options);
+            const op = (operation = new request_operation_1.Operation(options.signal));
+            this.operations.add(op);
+            op.check();
+            const built = (0, request_1.buildRequest)(this.config.appId, request);
+            op.check();
+            const key = this.cache ? (0, result_cache_1.configCacheKey)(built.body) : '';
+            const cached = this.cache ? this.cache.get(key) : null;
+            op.check();
+            if (cached) {
+                const result = (0, config_snapshot_1.bindSnapshot)(cached, built.accountId, built.distinctId, this.automaticExposure);
+                op.check();
+                op.dispose();
+                this.operations.delete(op);
+                return Promise.resolve(result);
+            }
+            const generation = this.cacheGeneration;
+            let completed;
+            const work = this.scheduler
+                .submit(op, () => this.evaluate(built, op))
+                .then((snapshot) => {
+                completed = snapshot;
+                op.check();
+                const result = (0, config_snapshot_1.bindSnapshot)(snapshot, built.accountId, built.distinctId, this.automaticExposure);
+                op.check();
+                if (this.cache && generation === this.cacheGeneration) {
+                    this.cache.set(key, snapshot);
+                    try {
+                        op.check();
+                    }
+                    catch (error) {
+                        this.cache.removeIfSame(key, snapshot);
+                        throw error;
+                    }
+                }
+                return result;
+            });
+            const promise = work.then((result) => {
+                try {
+                    op.check();
+                    return result;
+                }
+                catch (error) {
+                    if (this.cache && completed)
+                        this.cache.removeIfSame(key, completed);
+                    throw error;
+                }
+                finally {
+                    op.dispose();
+                    this.operations.delete(op);
+                }
+            }, (error) => {
+                op.dispose();
+                this.operations.delete(op);
+                throw error;
+            });
+            this.pending.add(promise);
+            const remove = () => {
+                this.pending.delete(promise);
+            };
+            promise.then(remove, remove);
+            return promise;
+        }
+        catch (error) {
+            if (operation) {
+                operation.dispose();
+                this.operations.delete(operation);
+            }
+            return Promise.reject(error);
+        }
+    }
+    evaluate(built, operation) {
+        let retries = 0;
+        const attempt = () => {
+            operation.check();
+            return this.transport
+                .send(built, operation)
+                .then((response) => {
+                operation.check();
+                return (0, response_1.parseSnapshot)(response, this.config.maxDecompressedResponseBytes, operation);
+            })
+                .then((snapshot) => {
+                operation.check();
+                return snapshot;
+            }, (error) => {
+                operation.check();
+                if (retries >= this.config.retryTimes || !(0, retry_1.retryable)(error))
+                    throw error;
+                const delay = (0, retry_1.retryDelay)(retries, error, this.config);
+                if (delay === null)
+                    throw error;
+                retries++;
+                return operation.sleep(delay).then(attempt);
+            });
+        };
+        return attempt();
+    }
+    clearCache() {
+        this.cacheGeneration++;
+        if (this.cache)
+            this.cache.clear();
+    }
+    /** Returns queue acceptance only; duplicates, unmatched results and overload return false. */
+    expose(feature, properties) {
+        if (feature !== null && feature !== undefined && !(0, feature_1.isFeature)(feature))
+            throw new errors_1.FeatureError('expose requires a feature returned by fetch', 'INVALID_REQUEST');
+        return this.reporter.report(feature, properties);
+    }
+    flush() {
+        return this.reporter.flush();
+    }
+    close() {
+        if (!this.closePromise) {
+            this.closing = true;
+            this.scheduler.close();
+            Array.from(this.operations).forEach(function (operation) {
+                operation.cancel(new errors_1.FeatureError('Client is closed', 'CLIENT_CLOSED'));
+            });
+            this.transport.close();
+            this.clearCache();
+            const exposures = this.reporter.close();
+            this.closePromise = Promise.all(Array.from(this.pending)
+                .map(function (promise) {
+                return promise.then(function () { }, function () { });
+            })
+                .concat([exposures])).then(function () { });
+        }
+        return this.closePromise;
+    }
+}
+exports.Client = Client;
+function validateFetchOptions(options) {
+    if (!options ||
+        typeof options !== 'object' ||
+        Array.isArray(options) ||
+        Object.keys(options).some(function (key) {
+            return key !== 'signal';
+        })) {
+        throw new errors_1.FeatureError('Invalid fetch options', 'INVALID_REQUEST');
+    }
+    const signal = options.signal;
+    if (signal !== undefined &&
+        (!signal ||
+            typeof signal.aborted !== 'boolean' ||
+            typeof signal.addEventListener !== 'function' ||
+            typeof signal.removeEventListener !== 'function')) {
+        throw new errors_1.FeatureError('signal must implement AbortSignalLike', 'INVALID_REQUEST');
+    }
+}
+/** Create one long-lived client per project; close it during application shutdown. */
+function createClient(options) {
+    return new Client(options);
+}

package/dist/common/coercion.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject, JsonValue } from '../types';
+export declare function toNumber(value: JsonValue, fallback: number | null): number | null;
+export declare function toBoolean(value: JsonValue, fallback: boolean | null): boolean | null;
+export declare function toJson(value: JsonValue, fallback: JsonObject | null): JsonObject | null;

package/dist/common/coercion.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toNumber = toNumber;
+exports.toBoolean = toBoolean;
+exports.toJson = toJson;
+const json_1 = require("./json");
+function toNumber(value, fallback) {
+    if (typeof value !== 'number' && (typeof value !== 'string' || value.trim() === ''))
+        return fallback;
+    const number = Number(value);
+    return Number.isNaN(number) ? fallback : number;
+}
+function toBoolean(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    return typeof value === 'string' && /^(true|false)$/i.test(value)
+        ? value.toLowerCase() === 'true'
+        : fallback;
+}
+function toJson(value, fallback) {
+    if ((0, json_1.isObject)(value))
+        return (0, json_1.freezeJson)(value);
+    if (typeof value !== 'string')
+        return fallback;
+    try {
+        const parsed = JSON.parse(value);
+        return (0, json_1.isObject)(parsed) ? (0, json_1.freezeJson)(parsed) : fallback;
+    }
+    catch (_) {
+        return fallback;
+    }
+}

package/dist/common/config.d.ts

@@ -0,0 +1,8 @@
+import { type ClientOptions, type ResolvedClientOptions } from '../types';
+export declare function normalizeOptions(options: ClientOptions): Readonly<ResolvedClientOptions>;
+export declare function requestLocation(baseUrl: string): {
+    protocol: string;
+    hostname: string;
+    port: string | null;
+    path: string;
+};

package/dist/common/config.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOptions = normalizeOptions;
+exports.requestLocation = requestLocation;
+const net_1 = require("net");
+const url_1 = require("url");
+const types_1 = require("../types");
+const errors_1 = require("../errors");
+function normalizeServerUrl(value) {
+    if (typeof value !== 'string' || value.length === 0 || /[\s\\]/.test(value)) {
+        throw new errors_1.FeatureError('serverUrl must be a non-empty HTTP(S) base URL');
+    }
+    const authority = /^https?:\/\/([^/?#]+)/i.exec(value);
+    const address = authority && /^(\[[^\]]+\]|[^:@\[\]]+)(?::([0-9]+))?$/.exec(authority[1]);
+    if (!address) {
+        throw new errors_1.FeatureError('serverUrl must include a valid HTTP(S) host and optional port');
+    }
+    if (/[?#]/.test(value) || /[%|^`<>"'{}]/.test(address[1])) {
+        throw new errors_1.FeatureError('serverUrl must be a base URL with a valid host and no query or fragment');
+    }
+    if (address[1].charAt(0) === '[' && (0, net_1.isIP)(address[1].slice(1, -1)) !== 6) {
+        throw new errors_1.FeatureError('serverUrl contains an invalid IPv6 host');
+    }
+    if (address[2] !== undefined && (Number(address[2]) < 1 || Number(address[2]) > 65535)) {
+        throw new errors_1.FeatureError('serverUrl port must be between 1 and 65535');
+    }
+    try {
+        const parsed = new url_1.URL(value);
+        if (!parsed.hostname || parsed.username || parsed.password)
+            throw new Error('invalid base URL');
+    }
+    catch (_) {
+        throw new errors_1.FeatureError('serverUrl must be a base URL without credentials, query or fragment');
+    }
+    return value.replace(/\/+$/, '');
+}
+function normalizeOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new errors_1.FeatureError('client options are required');
+    }
+    Object.keys(options).forEach(function (key) {
+        if ([
+            'appId',
+            'serverUrl',
+            'splitMode',
+            'timeout',
+            'maxHttpConnections',
+            'maxDecompressedResponseBytes',
+            'retryTimes',
+            'retryInterval',
+            'retryStrategy',
+            'retryJitter',
+            'maxRetryInterval',
+            'maxConcurrentRequests',
+            'maxQueueSize',
+            'enableCache',
+            'cacheExpireTime',
+            'maxCacheSize',
+            'autoExposure',
+            'exposureDedupMaxSize',
+            'exposureDedupExpireSeconds',
+            'exposureQueueCapacity',
+            'exposureBatchSize',
+            'exposureFlushIntervalMillis',
+            'exposureFlushTimeoutMillis',
+            'exposureAdapter',
+            'tdAnalytics',
+            'tlsCa',
+        ].indexOf(key) < 0) {
+            throw new errors_1.FeatureError('Unsupported client option: ' + key);
+        }
+    });
+    if (typeof options.appId !== 'string' ||
+        options.appId.trim().length === 0 ||
+        /[\x00-\x1f\x7f]/.test(options.appId)) {
+        throw new errors_1.FeatureError('appId must be a non-empty string');
+    }
+    const splitMode = options.splitMode === undefined ? types_1.SplitMode.REMOTE : options.splitMode;
+    if (splitMode !== types_1.SplitMode.REMOTE)
+        throw new errors_1.FeatureError('Only splitMode REMOTE is currently supported');
+    const timeout = positiveInteger(options.timeout, 5000, 'timeout');
+    const connections = positiveInteger(options.maxHttpConnections, 20, 'maxHttpConnections');
+    const concurrent = positiveInteger(options.maxConcurrentRequests, connections, 'maxConcurrentRequests');
+    if (concurrent > connections)
+        throw new errors_1.FeatureError('maxConcurrentRequests must not exceed maxHttpConnections');
+    const strategy = options.retryStrategy === undefined ? 'EXPONENTIAL_BACKOFF' : options.retryStrategy;
+    if (strategy !== 'FIXED_INTERVAL' && strategy !== 'EXPONENTIAL_BACKOFF')
+        throw new errors_1.FeatureError('Invalid retryStrategy');
+    if (options.exposureAdapter !== undefined && options.tdAnalytics !== undefined)
+        throw new errors_1.FeatureError('exposureAdapter and tdAnalytics are mutually exclusive');
+    [options.exposureAdapter, options.tdAnalytics].forEach(function (adapter) {
+        if (adapter !== undefined &&
+            (!adapter || typeof adapter.track !== 'function' || typeof adapter.flush !== 'function')) {
+            throw new errors_1.FeatureError('Collection adapter must implement track and flush');
+        }
+    });
+    if (options.tdAnalytics !== undefined && typeof options.tdAnalytics.close !== 'function')
+        throw new errors_1.FeatureError('tdAnalytics must implement close');
+    return Object.freeze({
+        appId: options.appId,
+        serverUrl: normalizeServerUrl(options.serverUrl),
+        splitMode,
+        timeout: timeout,
+        maxHttpConnections: connections,
+        maxDecompressedResponseBytes: positiveInteger(options.maxDecompressedResponseBytes, 10 * 1024 * 1024, 'maxDecompressedResponseBytes'),
+        retryTimes: boundedInteger(options.retryTimes, 0, 'retryTimes', 0, 10),
+        retryInterval: boundedInteger(options.retryInterval, 500, 'retryInterval', 0),
+        retryStrategy: strategy,
+        retryJitter: booleanOption(options.retryJitter, true, 'retryJitter'),
+        maxRetryInterval: boundedInteger(options.maxRetryInterval, 30000, 'maxRetryInterval', 0),
+        maxConcurrentRequests: concurrent,
+        maxQueueSize: boundedInteger(options.maxQueueSize, 0, 'maxQueueSize', 0, 1000000),
+        enableCache: booleanOption(options.enableCache, false, 'enableCache'),
+        cacheExpireTime: boundedInteger(options.cacheExpireTime, 86400, 'cacheExpireTime', 0),
+        maxCacheSize: boundedInteger(options.maxCacheSize, 10000, 'maxCacheSize', 0),
+        autoExposure: booleanOption(options.autoExposure, false, 'autoExposure'),
+        exposureDedupMaxSize: positiveInteger(options.exposureDedupMaxSize, 100000, 'exposureDedupMaxSize'),
+        exposureDedupExpireSeconds: positiveInteger(options.exposureDedupExpireSeconds, 86400, 'exposureDedupExpireSeconds'),
+        exposureQueueCapacity: boundedInteger(options.exposureQueueCapacity, 10000, 'exposureQueueCapacity', 1, 1000000),
+        exposureBatchSize: boundedInteger(options.exposureBatchSize, 100, 'exposureBatchSize', 1, 10000),
+        exposureFlushIntervalMillis: positiveInteger(options.exposureFlushIntervalMillis, 1000, 'exposureFlushIntervalMillis'),
+        exposureFlushTimeoutMillis: positiveInteger(options.exposureFlushTimeoutMillis, 5000, 'exposureFlushTimeoutMillis'),
+        exposureAdapter: options.exposureAdapter,
+        tdAnalytics: options.tdAnalytics,
+        tlsCa: normalizeCa(options.tlsCa),
+    });
+}
+function normalizeCa(ca) {
+    if (ca === undefined)
+        return undefined;
+    const entries = Array.isArray(ca) ? ca : [ca];
+    if (entries.length === 0 ||
+        entries.some(function (entry) {
+            return (typeof entry !== 'string' ||
+                entry.trim().length === 0 ||
+                entry.indexOf('-----BEGIN CERTIFICATE-----') < 0);
+        }))
+        throw new errors_1.FeatureError('tlsCa must contain PEM CA certificates');
+    return Array.isArray(ca) ? Object.freeze(entries.slice()) : ca;
+}
+function positiveInteger(value, fallback, name) {
+    return boundedInteger(value, fallback, name, 1);
+}
+function boundedInteger(value, fallback, name, minimum, maximum = 2147483647) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' ||
+        !isFinite(value) ||
+        Math.floor(value) !== value ||
+        value < minimum ||
+        value > maximum) {
+        throw new errors_1.FeatureError(name + ' must be an integer between ' + minimum + ' and ' + maximum);
+    }
+    return value;
+}
+function booleanOption(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new errors_1.FeatureError(name + ' must be a boolean');
+    return value;
+}
+function requestLocation(baseUrl) {
+    const endpoint = baseUrl + '/v1/remote-config/get';
+    const parsed = new url_1.URL(endpoint);
+    return {
+        protocol: parsed.protocol,
+        hostname: parsed.hostname.replace(/^\[|\]$/g, ''),
+        port: parsed.port || null,
+        path: parsed.pathname,
+    };
+}

package/dist/common/json.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue, JsonObject } from '../types';
+export declare function isObject(value: JsonValue | undefined): value is JsonObject;
+export declare function stringValue(value: JsonValue | undefined): string | null;
+/** Freeze a detached JSON copy once, then reuse SDK-owned immutable values. */
+export declare function freezeJson(value: JsonValue): JsonValue;
+/** Snapshot a caller's JSON data without invoking toJSON hooks or losing reserved keys. */
+export declare function snapshotJson(value: JsonValue, ancestors?: object[]): JsonValue;