@evumi/berth-config 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @evumi/berth-config
 
-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.
+读取 Berth 项目 Config 的客户端。第一次读取时拉一次整份配置，之后都从内存读；后台用一个长轮询保持最新。零运行时依赖，支持 Node ≥ 18、Bun、Deno 和不带 Node 内置模块的 edge 运行时。
+
+> **不要放机密。** Config 对组织成员可读。密码、密钥放到服务变量里。
+
+## 用法
+
+Berth 会给容器注入 `BERTH_CONFIG_URL` 和 `BERTH_CONFIG_TOKEN`，直接用默认导出：
+
+```ts
+import { config } from '@evumi/berth-config';
+
+const enabled = await config.get<boolean>('newCheckout');
+const all = await config.getAll();
+const unsubscribe = config.subscribe((doc) => console.log('config changed', doc));
+```
+
+自己建客户端：
+
+```ts
+import { createClient } from '@evumi/berth-config';
+
+const cfg = createClient({
+  url: process.env.BERTH_CONFIG_URL,   // 默认读环境变量
+  token: process.env.BERTH_CONFIG_TOKEN,
+  fallback: './config.local.json',     // 本地开发或启动时连不上服务器时使用
+  timeoutMs: 5000,
+  onError: (err) => console.warn('config:', err.code, err.message), // 默认什么都不打
+});
+```
+
+| 方法 | 说明 |
+|---|---|
+| `get<T>(key)` | 某个顶层字段，不存在时返回 `undefined` |
+| `getAll<T>(keys?)` | 整份文档，或只取给出的字段 |
+| `has(key)` | 字段是否存在 |
+| `digest()` | 当前 ETag（不带引号）；用的是 fallback 时为 `""` |
+| `version()` | 当前版本号；还没有配置或用的是 fallback 时为 `0` |
+| `subscribe(cb)` | 配置变化时回调，返回取消函数 |
+| `close()` | 停止长轮询并中断进行中的请求 |
+
+返回值是副本，改了不影响缓存。
+
+## 行为
+
+- 第一次调用任意方法时拉取 `GET /v1/config`，并发调用共用这一次请求；失败了下次调用会重试。
+- 之后后台只有一个长轮询（`?wait=55` + `If-None-Match`），变化时立即更新并通知订阅者。
+- 出错时按指数退避重试（带抖动，最长 30 秒）；429 按 `Retry-After` 等待。
+- Node 里长轮询的连接和定时器都已 `unref`，不会让进程退出不了；脚本里也不需要手动 `close()`。
+- 错误都是 `BerthConfigError`，带 `code`（`unauthorized`、`not_found`、`unavailable`、`rate_limited`、`timeout`、`network`、`missing_env`、`fallback` 等）和 `status`。令牌不会出现在错误或日志里。
+
+## Next.js
+
+```ts
+// app/page.tsx（服务端组件）
+import { config } from '@evumi/berth-config';
+
+export default async function Page() {
+  const banner = await config.get<string>('banner');
+  return <main>{banner && <p>{banner}</p>}</main>;
+}
+```
+
+Edge 运行时也能用，`fallback` 只能传对象（edge 没有文件系统）。
+
+## Express
+
+```ts
+import express from 'express';
+import { config } from '@evumi/berth-config';
+
+const app = express();
+app.get('/', async (_req, res) => {
+  const { maxItems = 20 } = await config.getAll<{ maxItems?: number }>();
+  res.json({ maxItems });
+});
+app.listen(3000);
+```
+
+## 本地开发
+
+本地没有 `BERTH_CONFIG_URL` / `BERTH_CONFIG_TOKEN` 时读 `fallback`：
+
+```ts
+const cfg = createClient({ fallback: './config.local.json' });   // 文件（Node/Bun/Deno）
+const cfg2 = createClient({ fallback: { newCheckout: true } });  // 或直接给对象
+```
+
+没有环境变量也没有 `fallback` 时，读取会抛 `missing_env`。
+
+## 开发
+
+```sh
+pnpm install
+pnpm test    # 先构建，再跑 vitest（含 ESM/CJS 子进程退出测试）
+pnpm build   # dist/esm + dist/cjs
+```

package/dist/cjs/errors.d.ts

@@ -0,0 +1,19 @@
+/** Error codes. The first four come from the server; the rest are raised by the client. */
+export type ErrorCode = 'unauthorized' | 'not_found' | 'bad_request' | 'unavailable' | 'rate_limited' | 'timeout' | 'network' | 'invalid_response' | 'missing_env' | 'fallback' | 'closed' | 'subscriber' | (string & {});
+export declare class BerthConfigError extends Error {
+    name: string;
+    readonly code: ErrorCode;
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number;
+    /** Parsed Retry-After, for 429 responses. */
+    readonly retryAfterMs?: number;
+    constructor(code: ErrorCode, message: string, extra?: {
+        status?: number;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+/** Builds an error from a non-2xx/304 response body of the form {"error":{"code","message"}}. */
+export declare function responseError(status: number, body: string, retryAfter: string | null): BerthConfigError;
+/** Retry-After is either delta-seconds or an HTTP date. */
+export declare function parseRetryAfter(v: string | null): number | undefined;

package/dist/cjs/errors.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BerthConfigError = void 0;
+exports.responseError = responseError;
+exports.parseRetryAfter = parseRetryAfter;
+class BerthConfigError extends Error {
+    name = 'BerthConfigError';
+    code;
+    /** HTTP status, when the error came from a response. */
+    status;
+    /** Parsed Retry-After, for 429 responses. */
+    retryAfterMs;
+    constructor(code, message, extra = {}) {
+        super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+        this.code = code;
+        this.status = extra.status;
+        this.retryAfterMs = extra.retryAfterMs;
+    }
+}
+exports.BerthConfigError = BerthConfigError;
+const statusCodes = { 400: 'bad_request', 401: 'unauthorized', 403: 'unauthorized', 404: 'not_found', 429: 'rate_limited' };
+/** Builds an error from a non-2xx/304 response body of the form {"error":{"code","message"}}. */
+function responseError(status, body, retryAfter) {
+    let code = statusCodes[status] ?? (status >= 500 ? 'unavailable' : 'bad_request');
+    let message = `config request failed with HTTP ${status}`;
+    try {
+        const e = JSON.parse(body)?.error;
+        if (typeof e?.code === 'string' && status !== 429)
+            code = e.code;
+        if (typeof e?.message === 'string' && e.message)
+            message = e.message;
+    }
+    catch {
+        // Non-JSON error body (proxy page etc.): keep the generic message.
+    }
+    return new BerthConfigError(code, message, { status, retryAfterMs: parseRetryAfter(retryAfter) });
+}
+/** Retry-After is either delta-seconds or an HTTP date. */
+function parseRetryAfter(v) {
+    if (!v)
+        return undefined;
+    const s = Number(v);
+    if (Number.isFinite(s))
+        return Math.max(0, s * 1000);
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? undefined : Math.max(0, t - Date.now());
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,45 @@
+import { BerthConfigError } from './errors.js';
+import { type FetchLike } from './transport.js';
+export { BerthConfigError, type ErrorCode } from './errors.js';
+export type ConfigDocument = Record<string, unknown>;
+export interface ClientOptions {
+    /** Base URL without /v1. Default: env BERTH_CONFIG_URL. */
+    url?: string;
+    /** Bearer token (bcfg_...). Default: env BERTH_CONFIG_TOKEN. */
+    token?: string;
+    /** Local JSON file path or object, used when env vars are absent or the server is unreachable at startup. */
+    fallback?: string | ConfigDocument;
+    /** Timeout for a normal request; a long poll gets waitSeconds on top. Default 5000. */
+    timeoutMs?: number;
+    /** Long-poll wait sent as ?wait= (1..60). Default 55. */
+    waitSeconds?: number;
+    /** Keep the cache fresh with a background long poll. Default true. */
+    poll?: boolean;
+    /** Retry delays for the poll loop. baseMs is also the minimum gap between polls. Default 1000 / 30000. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Called with background errors (poll failures, fallback use, subscriber throws). Nothing is logged by default. */
+    onError?: (err: BerthConfigError) => void;
+    /** Custom fetch. When set it is used for every request, including long polls. */
+    fetch?: FetchLike;
+}
+export interface ConfigClient {
+    /** Value of one top-level key, or undefined when absent. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Whole document, or only the given keys. */
+    getAll<T extends ConfigDocument = ConfigDocument>(keys?: string[]): Promise<T>;
+    has(key: string): Promise<boolean>;
+    /** ETag digest without quotes; "" when served from fallback. */
+    digest(): Promise<string>;
+    /** Berth-Config-Version; 0 when there is no document yet or served from fallback. */
+    version(): Promise<number>;
+    /** Called with the new document after each change. Returns an unsubscribe function. */
+    subscribe(cb: (doc: ConfigDocument) => void): () => void;
+    /** Stops the poll loop and aborts the in-flight request. */
+    close(): void;
+}
+export declare function createClient(opts?: ClientOptions): ConfigClient;
+/** Client built from BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN on first use. */
+export declare const config: ConfigClient;

package/dist/cjs/index.js

@@ -0,0 +1,296 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = exports.BerthConfigError = void 0;
+exports.createClient = createClient;
+const errors_js_1 = require("./errors.js");
+const transport_js_1 = require("./transport.js");
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "BerthConfigError", { enumerable: true, get: function () { return errors_js_2.BerthConfigError; } });
+function env(name) {
+    const g = globalThis;
+    try {
+        return g.process?.env?.[name] ?? g.Deno?.env.get(name) ?? undefined;
+    }
+    catch {
+        return undefined; // Deno without --allow-env
+    }
+}
+const clone = (v) => (v === undefined ? v : structuredClone(v));
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+async function readFallback(fb) {
+    if (typeof fb !== 'string')
+        return clone(fb);
+    const fsName = 'node:fs/promises';
+    const fs = await Promise.resolve(`${fsName}`).then(s => __importStar(require(s)));
+    let doc;
+    try {
+        doc = JSON.parse(await fs.readFile(fb, 'utf8'));
+    }
+    catch (e) {
+        throw new errors_js_1.BerthConfigError('fallback', `cannot read fallback file ${fb}: ${e.message}`, { cause: e });
+    }
+    if (!isObject(doc))
+        throw new errors_js_1.BerthConfigError('fallback', `fallback file ${fb} must contain a JSON object`);
+    return doc;
+}
+/** Errors that mean "server unreachable", where falling back is right. Auth and request errors are not. */
+const transient = (e) => e instanceof errors_js_1.BerthConfigError && ['network', 'timeout', 'unavailable', 'rate_limited', 'invalid_response'].includes(e.code);
+class Client {
+    opts;
+    endpoint;
+    token;
+    timeoutMs;
+    wait;
+    baseMs;
+    maxMs;
+    doc;
+    etag = '';
+    ver = 0;
+    ready;
+    polling = false;
+    closed = false;
+    abort = new AbortController();
+    wake;
+    subs = new Set();
+    constructor(opts = {}) {
+        this.opts = opts;
+        const url = opts.url ?? env('BERTH_CONFIG_URL');
+        this.token = opts.token ?? env('BERTH_CONFIG_TOKEN');
+        if (url)
+            this.endpoint = url.replace(/\/+$/, '').replace(/\/v1$/, '') + '/v1/config';
+        this.timeoutMs = opts.timeoutMs ?? 5000;
+        this.wait = Math.min(60, Math.max(1, Math.round(opts.waitSeconds ?? 55)));
+        this.baseMs = opts.backoff?.baseMs ?? 1000;
+        this.maxMs = opts.backoff?.maxMs ?? 30_000;
+    }
+    async get(key) {
+        return clone((await this.load())[key]);
+    }
+    async getAll(keys) {
+        const doc = await this.load();
+        if (!keys)
+            return clone(doc);
+        const out = {};
+        for (const k of keys)
+            if (Object.hasOwn(doc, k))
+                out[k] = clone(doc[k]);
+        return out;
+    }
+    async has(key) {
+        return Object.hasOwn(await this.load(), key);
+    }
+    async digest() {
+        await this.load();
+        return this.etag.replace(/^W\//, '').replace(/^"|"$/g, '');
+    }
+    async version() {
+        await this.load();
+        return this.ver;
+    }
+    subscribe(cb) {
+        this.subs.add(cb);
+        this.load().catch((e) => this.report(e));
+        return () => void this.subs.delete(cb);
+    }
+    close() {
+        this.closed = true;
+        this.subs.clear();
+        this.abort.abort();
+        this.wake?.();
+    }
+    /** First call fetches the document once; concurrent callers share it; a failed load is retried next call. */
+    async load() {
+        if (!this.doc) {
+            if (this.closed)
+                throw new errors_js_1.BerthConfigError('closed', 'client closed');
+            this.ready ??= this.init().catch((e) => {
+                this.ready = undefined;
+                throw e;
+            });
+            await this.ready;
+        }
+        return this.doc;
+    }
+    async init() {
+        const { fallback } = this.opts;
+        if (!this.endpoint || !this.token) {
+            if (fallback === undefined) {
+                throw new errors_js_1.BerthConfigError('missing_env', 'BERTH_CONFIG_URL and BERTH_CONFIG_TOKEN are not set and no fallback was given');
+            }
+            this.doc = await readFallback(fallback);
+            return;
+        }
+        try {
+            const res = await this.request(false);
+            if (res.status !== 200)
+                throw (0, errors_js_1.responseError)(res.status, res.body, res.header('retry-after'));
+            this.apply(res);
+        }
+        catch (e) {
+            if (fallback === undefined || !transient(e))
+                throw e;
+            this.doc = await readFallback(fallback);
+            this.report(e);
+        }
+        if (this.opts.poll !== false)
+            void this.pollLoop();
+    }
+    request(longPoll) {
+        const headers = { authorization: `Bearer ${this.token}`, accept: 'application/json' };
+        let url = this.endpoint;
+        let timeout = this.timeoutMs;
+        if (longPoll) {
+            url += `?wait=${this.wait}`;
+            timeout += this.wait * 1000;
+            if (this.etag)
+                headers['if-none-match'] = this.etag;
+        }
+        if (this.opts.fetch)
+            return (0, transport_js_1.viaFetch)(this.opts.fetch, url, headers, timeout, this.abort.signal);
+        if (longPoll && transport_js_1.isNode)
+            return (0, transport_js_1.viaNodeHttp)(url, headers, timeout, this.abort.signal);
+        return (0, transport_js_1.viaFetch)((u, i) => fetch(u, i), url, headers, timeout, this.abort.signal);
+    }
+    /** Applies a 200 response. Returns true when the document changed. */
+    apply(res) {
+        let doc;
+        try {
+            doc = JSON.parse(res.body);
+        }
+        catch {
+            throw new errors_js_1.BerthConfigError('invalid_response', 'config response is not JSON', { status: res.status });
+        }
+        if (!isObject(doc))
+            throw new errors_js_1.BerthConfigError('invalid_response', 'config document is not a JSON object', { status: res.status });
+        const etag = res.header('etag') ?? '';
+        if (this.doc && etag && etag === this.etag)
+            return false;
+        this.doc = doc;
+        this.etag = etag;
+        this.ver = Number.parseInt(res.header('berth-config-version') ?? '0', 10) || 0;
+        return true;
+    }
+    /** The single background loop. `polling` guarantees at most one per client. */
+    async pollLoop() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        let failures = 0;
+        try {
+            while (!this.closed) {
+                const started = Date.now();
+                let delay;
+                try {
+                    const res = await this.request(true);
+                    if (res.status === 200) {
+                        if (this.apply(res))
+                            this.notify();
+                    }
+                    else if (res.status !== 304) {
+                        throw (0, errors_js_1.responseError)(res.status, res.body, res.header('retry-after'));
+                    }
+                    failures = 0;
+                    delay = this.baseMs - (Date.now() - started); // never poll faster than baseMs
+                }
+                catch (e) {
+                    if (this.closed)
+                        break;
+                    this.report(e);
+                    failures++;
+                    const backoff = Math.min(this.maxMs, this.baseMs * 2 ** (failures - 1)) * (0.5 + Math.random() / 2);
+                    const ra = e instanceof errors_js_1.BerthConfigError ? e.retryAfterMs : undefined;
+                    delay = ra === undefined ? backoff : Math.min(ra, 300_000);
+                }
+                if (delay > 0 && !this.closed)
+                    await this.sleep(delay);
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(t);
+                this.wake = undefined;
+                resolve();
+            };
+            const t = setTimeout(done, ms);
+            (0, transport_js_1.unref)(t);
+            this.wake = done;
+        });
+    }
+    notify() {
+        for (const cb of [...this.subs]) {
+            try {
+                cb(clone(this.doc));
+            }
+            catch (e) {
+                this.report(e);
+            }
+        }
+    }
+    report(e) {
+        if (!this.opts.onError)
+            return;
+        const err = e instanceof errors_js_1.BerthConfigError ? e : new errors_js_1.BerthConfigError('subscriber', String(e?.message ?? e), { cause: e });
+        try {
+            this.opts.onError(err);
+        }
+        catch {
+            // An onError that throws must not break the loop.
+        }
+    }
+}
+function createClient(opts) {
+    return new Client(opts);
+}
+let shared;
+const def = () => (shared ??= createClient());
+/** Client built from BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN on first use. */
+exports.config = {
+    get: (key) => def().get(key),
+    getAll: (keys) => def().getAll(keys),
+    has: (key) => def().has(key),
+    digest: () => def().digest(),
+    version: () => def().version(),
+    subscribe: (cb) => def().subscribe(cb),
+    close: () => {
+        shared?.close();
+        shared = undefined;
+    },
+};

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/transport.d.ts

@@ -0,0 +1,20 @@
+export interface HttpResponse {
+    status: number;
+    header(name: string): string | null;
+    body: string;
+}
+export type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<Response>;
+/** Lets a timer not hold a Node/Bun process open. No-op elsewhere. */
+export declare function unref(t: unknown): void;
+/** Real Node.js (not Bun/Deno compatibility layers). */
+export declare const isNode: boolean;
+/** One request through fetch, with a timeout and an outer abort signal (close()). */
+export declare function viaFetch(f: FetchLike, url: string, headers: Record<string, string>, timeoutMs: number, signal: AbortSignal): Promise<HttpResponse>;
+/**
+ * Background long polls in Node go through node:http with an unref'd socket:
+ * an in-flight fetch() would keep the process alive for up to a minute.
+ */
+export declare function viaNodeHttp(url: string, headers: Record<string, string>, timeoutMs: number, signal: AbortSignal): Promise<HttpResponse>;

package/dist/cjs/transport.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNode = void 0;
+exports.unref = unref;
+exports.viaFetch = viaFetch;
+exports.viaNodeHttp = viaNodeHttp;
+const errors_js_1 = require("./errors.js");
+/** Lets a timer not hold a Node/Bun process open. No-op elsewhere. */
+function unref(t) {
+    t?.unref?.();
+}
+const g = globalThis;
+/** Real Node.js (not Bun/Deno compatibility layers). */
+exports.isNode = !!g.process?.versions?.node && !g.process.versions.bun && !g.Deno;
+function timeoutError(ms) {
+    return new errors_js_1.BerthConfigError('timeout', `config request timed out after ${ms} ms`);
+}
+/** One request through fetch, with a timeout and an outer abort signal (close()). */
+async function viaFetch(f, url, headers, timeoutMs, signal) {
+    const ctrl = new AbortController();
+    const abort = () => ctrl.abort();
+    signal.addEventListener('abort', abort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => ((timedOut = true), ctrl.abort()), timeoutMs);
+    unref(timer);
+    try {
+        const res = await f(url, { headers, signal: ctrl.signal });
+        const body = await res.text();
+        return { status: res.status, header: (n) => res.headers.get(n), body };
+    }
+    catch (e) {
+        if (timedOut)
+            throw timeoutError(timeoutMs);
+        if (signal.aborted)
+            throw new errors_js_1.BerthConfigError('closed', 'client closed');
+        throw new errors_js_1.BerthConfigError('network', `config request failed: ${e?.message ?? e}`, { cause: e });
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', abort);
+    }
+}
+// Kept in variables so bundlers for edge runtimes do not try to resolve them.
+const HTTP = 'node:http';
+const HTTPS = 'node:https';
+/**
+ * Background long polls in Node go through node:http with an unref'd socket:
+ * an in-flight fetch() would keep the process alive for up to a minute.
+ */
+async function viaNodeHttp(url, headers, timeoutMs, signal) {
+    const u = new URL(url);
+    const mod = await Promise.resolve(`${u.protocol === 'https:' ? HTTPS : HTTP}`).then(s => __importStar(require(s)));
+    return new Promise((resolve, reject) => {
+        const req = mod.request(u, { headers, signal }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => (body += c));
+            res.on('error', (e) => reject(new errors_js_1.BerthConfigError('network', `config request failed: ${e.message}`, { cause: e })));
+            res.on('end', () => {
+                const header = (n) => {
+                    const v = res.headers[n.toLowerCase()];
+                    return v === undefined ? null : Array.isArray(v) ? v.join(', ') : v;
+                };
+                resolve({ status: res.statusCode ?? 0, header, body });
+            });
+        });
+        req.on('socket', (s) => s.unref());
+        req.setTimeout(timeoutMs, () => req.destroy(timeoutError(timeoutMs)));
+        req.on('error', (e) => {
+            if (e instanceof errors_js_1.BerthConfigError)
+                reject(e);
+            else if (signal.aborted)
+                reject(new errors_js_1.BerthConfigError('closed', 'client closed'));
+            else
+                reject(new errors_js_1.BerthConfigError('network', `config request failed: ${e.message}`, { cause: e }));
+        });
+        req.end();
+    });
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,19 @@
+/** Error codes. The first four come from the server; the rest are raised by the client. */
+export type ErrorCode = 'unauthorized' | 'not_found' | 'bad_request' | 'unavailable' | 'rate_limited' | 'timeout' | 'network' | 'invalid_response' | 'missing_env' | 'fallback' | 'closed' | 'subscriber' | (string & {});
+export declare class BerthConfigError extends Error {
+    name: string;
+    readonly code: ErrorCode;
+    /** HTTP status, when the error came from a response. */
+    readonly status?: number;
+    /** Parsed Retry-After, for 429 responses. */
+    readonly retryAfterMs?: number;
+    constructor(code: ErrorCode, message: string, extra?: {
+        status?: number;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+/** Builds an error from a non-2xx/304 response body of the form {"error":{"code","message"}}. */
+export declare function responseError(status: number, body: string, retryAfter: string | null): BerthConfigError;
+/** Retry-After is either delta-seconds or an HTTP date. */
+export declare function parseRetryAfter(v: string | null): number | undefined;

package/dist/esm/errors.js

@@ -0,0 +1,41 @@
+export class BerthConfigError extends Error {
+    name = 'BerthConfigError';
+    code;
+    /** HTTP status, when the error came from a response. */
+    status;
+    /** Parsed Retry-After, for 429 responses. */
+    retryAfterMs;
+    constructor(code, message, extra = {}) {
+        super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+        this.code = code;
+        this.status = extra.status;
+        this.retryAfterMs = extra.retryAfterMs;
+    }
+}
+const statusCodes = { 400: 'bad_request', 401: 'unauthorized', 403: 'unauthorized', 404: 'not_found', 429: 'rate_limited' };
+/** Builds an error from a non-2xx/304 response body of the form {"error":{"code","message"}}. */
+export function responseError(status, body, retryAfter) {
+    let code = statusCodes[status] ?? (status >= 500 ? 'unavailable' : 'bad_request');
+    let message = `config request failed with HTTP ${status}`;
+    try {
+        const e = JSON.parse(body)?.error;
+        if (typeof e?.code === 'string' && status !== 429)
+            code = e.code;
+        if (typeof e?.message === 'string' && e.message)
+            message = e.message;
+    }
+    catch {
+        // Non-JSON error body (proxy page etc.): keep the generic message.
+    }
+    return new BerthConfigError(code, message, { status, retryAfterMs: parseRetryAfter(retryAfter) });
+}
+/** Retry-After is either delta-seconds or an HTTP date. */
+export function parseRetryAfter(v) {
+    if (!v)
+        return undefined;
+    const s = Number(v);
+    if (Number.isFinite(s))
+        return Math.max(0, s * 1000);
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? undefined : Math.max(0, t - Date.now());
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,45 @@
+import { BerthConfigError } from './errors.js';
+import { type FetchLike } from './transport.js';
+export { BerthConfigError, type ErrorCode } from './errors.js';
+export type ConfigDocument = Record<string, unknown>;
+export interface ClientOptions {
+    /** Base URL without /v1. Default: env BERTH_CONFIG_URL. */
+    url?: string;
+    /** Bearer token (bcfg_...). Default: env BERTH_CONFIG_TOKEN. */
+    token?: string;
+    /** Local JSON file path or object, used when env vars are absent or the server is unreachable at startup. */
+    fallback?: string | ConfigDocument;
+    /** Timeout for a normal request; a long poll gets waitSeconds on top. Default 5000. */
+    timeoutMs?: number;
+    /** Long-poll wait sent as ?wait= (1..60). Default 55. */
+    waitSeconds?: number;
+    /** Keep the cache fresh with a background long poll. Default true. */
+    poll?: boolean;
+    /** Retry delays for the poll loop. baseMs is also the minimum gap between polls. Default 1000 / 30000. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Called with background errors (poll failures, fallback use, subscriber throws). Nothing is logged by default. */
+    onError?: (err: BerthConfigError) => void;
+    /** Custom fetch. When set it is used for every request, including long polls. */
+    fetch?: FetchLike;
+}
+export interface ConfigClient {
+    /** Value of one top-level key, or undefined when absent. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Whole document, or only the given keys. */
+    getAll<T extends ConfigDocument = ConfigDocument>(keys?: string[]): Promise<T>;
+    has(key: string): Promise<boolean>;
+    /** ETag digest without quotes; "" when served from fallback. */
+    digest(): Promise<string>;
+    /** Berth-Config-Version; 0 when there is no document yet or served from fallback. */
+    version(): Promise<number>;
+    /** Called with the new document after each change. Returns an unsubscribe function. */
+    subscribe(cb: (doc: ConfigDocument) => void): () => void;
+    /** Stops the poll loop and aborts the in-flight request. */
+    close(): void;
+}
+export declare function createClient(opts?: ClientOptions): ConfigClient;
+/** Client built from BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN on first use. */
+export declare const config: ConfigClient;

package/dist/esm/index.js

@@ -0,0 +1,258 @@
+import { BerthConfigError, responseError } from './errors.js';
+import { isNode, unref, viaFetch, viaNodeHttp } from './transport.js';
+export { BerthConfigError } from './errors.js';
+function env(name) {
+    const g = globalThis;
+    try {
+        return g.process?.env?.[name] ?? g.Deno?.env.get(name) ?? undefined;
+    }
+    catch {
+        return undefined; // Deno without --allow-env
+    }
+}
+const clone = (v) => (v === undefined ? v : structuredClone(v));
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+async function readFallback(fb) {
+    if (typeof fb !== 'string')
+        return clone(fb);
+    const fsName = 'node:fs/promises';
+    const fs = await import(/* webpackIgnore: true */ fsName);
+    let doc;
+    try {
+        doc = JSON.parse(await fs.readFile(fb, 'utf8'));
+    }
+    catch (e) {
+        throw new BerthConfigError('fallback', `cannot read fallback file ${fb}: ${e.message}`, { cause: e });
+    }
+    if (!isObject(doc))
+        throw new BerthConfigError('fallback', `fallback file ${fb} must contain a JSON object`);
+    return doc;
+}
+/** Errors that mean "server unreachable", where falling back is right. Auth and request errors are not. */
+const transient = (e) => e instanceof BerthConfigError && ['network', 'timeout', 'unavailable', 'rate_limited', 'invalid_response'].includes(e.code);
+class Client {
+    opts;
+    endpoint;
+    token;
+    timeoutMs;
+    wait;
+    baseMs;
+    maxMs;
+    doc;
+    etag = '';
+    ver = 0;
+    ready;
+    polling = false;
+    closed = false;
+    abort = new AbortController();
+    wake;
+    subs = new Set();
+    constructor(opts = {}) {
+        this.opts = opts;
+        const url = opts.url ?? env('BERTH_CONFIG_URL');
+        this.token = opts.token ?? env('BERTH_CONFIG_TOKEN');
+        if (url)
+            this.endpoint = url.replace(/\/+$/, '').replace(/\/v1$/, '') + '/v1/config';
+        this.timeoutMs = opts.timeoutMs ?? 5000;
+        this.wait = Math.min(60, Math.max(1, Math.round(opts.waitSeconds ?? 55)));
+        this.baseMs = opts.backoff?.baseMs ?? 1000;
+        this.maxMs = opts.backoff?.maxMs ?? 30_000;
+    }
+    async get(key) {
+        return clone((await this.load())[key]);
+    }
+    async getAll(keys) {
+        const doc = await this.load();
+        if (!keys)
+            return clone(doc);
+        const out = {};
+        for (const k of keys)
+            if (Object.hasOwn(doc, k))
+                out[k] = clone(doc[k]);
+        return out;
+    }
+    async has(key) {
+        return Object.hasOwn(await this.load(), key);
+    }
+    async digest() {
+        await this.load();
+        return this.etag.replace(/^W\//, '').replace(/^"|"$/g, '');
+    }
+    async version() {
+        await this.load();
+        return this.ver;
+    }
+    subscribe(cb) {
+        this.subs.add(cb);
+        this.load().catch((e) => this.report(e));
+        return () => void this.subs.delete(cb);
+    }
+    close() {
+        this.closed = true;
+        this.subs.clear();
+        this.abort.abort();
+        this.wake?.();
+    }
+    /** First call fetches the document once; concurrent callers share it; a failed load is retried next call. */
+    async load() {
+        if (!this.doc) {
+            if (this.closed)
+                throw new BerthConfigError('closed', 'client closed');
+            this.ready ??= this.init().catch((e) => {
+                this.ready = undefined;
+                throw e;
+            });
+            await this.ready;
+        }
+        return this.doc;
+    }
+    async init() {
+        const { fallback } = this.opts;
+        if (!this.endpoint || !this.token) {
+            if (fallback === undefined) {
+                throw new BerthConfigError('missing_env', 'BERTH_CONFIG_URL and BERTH_CONFIG_TOKEN are not set and no fallback was given');
+            }
+            this.doc = await readFallback(fallback);
+            return;
+        }
+        try {
+            const res = await this.request(false);
+            if (res.status !== 200)
+                throw responseError(res.status, res.body, res.header('retry-after'));
+            this.apply(res);
+        }
+        catch (e) {
+            if (fallback === undefined || !transient(e))
+                throw e;
+            this.doc = await readFallback(fallback);
+            this.report(e);
+        }
+        if (this.opts.poll !== false)
+            void this.pollLoop();
+    }
+    request(longPoll) {
+        const headers = { authorization: `Bearer ${this.token}`, accept: 'application/json' };
+        let url = this.endpoint;
+        let timeout = this.timeoutMs;
+        if (longPoll) {
+            url += `?wait=${this.wait}`;
+            timeout += this.wait * 1000;
+            if (this.etag)
+                headers['if-none-match'] = this.etag;
+        }
+        if (this.opts.fetch)
+            return viaFetch(this.opts.fetch, url, headers, timeout, this.abort.signal);
+        if (longPoll && isNode)
+            return viaNodeHttp(url, headers, timeout, this.abort.signal);
+        return viaFetch((u, i) => fetch(u, i), url, headers, timeout, this.abort.signal);
+    }
+    /** Applies a 200 response. Returns true when the document changed. */
+    apply(res) {
+        let doc;
+        try {
+            doc = JSON.parse(res.body);
+        }
+        catch {
+            throw new BerthConfigError('invalid_response', 'config response is not JSON', { status: res.status });
+        }
+        if (!isObject(doc))
+            throw new BerthConfigError('invalid_response', 'config document is not a JSON object', { status: res.status });
+        const etag = res.header('etag') ?? '';
+        if (this.doc && etag && etag === this.etag)
+            return false;
+        this.doc = doc;
+        this.etag = etag;
+        this.ver = Number.parseInt(res.header('berth-config-version') ?? '0', 10) || 0;
+        return true;
+    }
+    /** The single background loop. `polling` guarantees at most one per client. */
+    async pollLoop() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        let failures = 0;
+        try {
+            while (!this.closed) {
+                const started = Date.now();
+                let delay;
+                try {
+                    const res = await this.request(true);
+                    if (res.status === 200) {
+                        if (this.apply(res))
+                            this.notify();
+                    }
+                    else if (res.status !== 304) {
+                        throw responseError(res.status, res.body, res.header('retry-after'));
+                    }
+                    failures = 0;
+                    delay = this.baseMs - (Date.now() - started); // never poll faster than baseMs
+                }
+                catch (e) {
+                    if (this.closed)
+                        break;
+                    this.report(e);
+                    failures++;
+                    const backoff = Math.min(this.maxMs, this.baseMs * 2 ** (failures - 1)) * (0.5 + Math.random() / 2);
+                    const ra = e instanceof BerthConfigError ? e.retryAfterMs : undefined;
+                    delay = ra === undefined ? backoff : Math.min(ra, 300_000);
+                }
+                if (delay > 0 && !this.closed)
+                    await this.sleep(delay);
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(t);
+                this.wake = undefined;
+                resolve();
+            };
+            const t = setTimeout(done, ms);
+            unref(t);
+            this.wake = done;
+        });
+    }
+    notify() {
+        for (const cb of [...this.subs]) {
+            try {
+                cb(clone(this.doc));
+            }
+            catch (e) {
+                this.report(e);
+            }
+        }
+    }
+    report(e) {
+        if (!this.opts.onError)
+            return;
+        const err = e instanceof BerthConfigError ? e : new BerthConfigError('subscriber', String(e?.message ?? e), { cause: e });
+        try {
+            this.opts.onError(err);
+        }
+        catch {
+            // An onError that throws must not break the loop.
+        }
+    }
+}
+export function createClient(opts) {
+    return new Client(opts);
+}
+let shared;
+const def = () => (shared ??= createClient());
+/** Client built from BERTH_CONFIG_URL / BERTH_CONFIG_TOKEN on first use. */
+export const config = {
+    get: (key) => def().get(key),
+    getAll: (keys) => def().getAll(keys),
+    has: (key) => def().has(key),
+    digest: () => def().digest(),
+    version: () => def().version(),
+    subscribe: (cb) => def().subscribe(cb),
+    close: () => {
+        shared?.close();
+        shared = undefined;
+    },
+};

package/dist/esm/transport.d.ts

@@ -0,0 +1,20 @@
+export interface HttpResponse {
+    status: number;
+    header(name: string): string | null;
+    body: string;
+}
+export type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<Response>;
+/** Lets a timer not hold a Node/Bun process open. No-op elsewhere. */
+export declare function unref(t: unknown): void;
+/** Real Node.js (not Bun/Deno compatibility layers). */
+export declare const isNode: boolean;
+/** One request through fetch, with a timeout and an outer abort signal (close()). */
+export declare function viaFetch(f: FetchLike, url: string, headers: Record<string, string>, timeoutMs: number, signal: AbortSignal): Promise<HttpResponse>;
+/**
+ * Background long polls in Node go through node:http with an unref'd socket:
+ * an in-flight fetch() would keep the process alive for up to a minute.
+ */
+export declare function viaNodeHttp(url: string, headers: Record<string, string>, timeoutMs: number, signal: AbortSignal): Promise<HttpResponse>;

package/dist/esm/transport.js

@@ -0,0 +1,73 @@
+import { BerthConfigError } from './errors.js';
+/** Lets a timer not hold a Node/Bun process open. No-op elsewhere. */
+export function unref(t) {
+    t?.unref?.();
+}
+const g = globalThis;
+/** Real Node.js (not Bun/Deno compatibility layers). */
+export const isNode = !!g.process?.versions?.node && !g.process.versions.bun && !g.Deno;
+function timeoutError(ms) {
+    return new BerthConfigError('timeout', `config request timed out after ${ms} ms`);
+}
+/** One request through fetch, with a timeout and an outer abort signal (close()). */
+export async function viaFetch(f, url, headers, timeoutMs, signal) {
+    const ctrl = new AbortController();
+    const abort = () => ctrl.abort();
+    signal.addEventListener('abort', abort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => ((timedOut = true), ctrl.abort()), timeoutMs);
+    unref(timer);
+    try {
+        const res = await f(url, { headers, signal: ctrl.signal });
+        const body = await res.text();
+        return { status: res.status, header: (n) => res.headers.get(n), body };
+    }
+    catch (e) {
+        if (timedOut)
+            throw timeoutError(timeoutMs);
+        if (signal.aborted)
+            throw new BerthConfigError('closed', 'client closed');
+        throw new BerthConfigError('network', `config request failed: ${e?.message ?? e}`, { cause: e });
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', abort);
+    }
+}
+// Kept in variables so bundlers for edge runtimes do not try to resolve them.
+const HTTP = 'node:http';
+const HTTPS = 'node:https';
+/**
+ * Background long polls in Node go through node:http with an unref'd socket:
+ * an in-flight fetch() would keep the process alive for up to a minute.
+ */
+export async function viaNodeHttp(url, headers, timeoutMs, signal) {
+    const u = new URL(url);
+    const mod = await import(/* webpackIgnore: true */ u.protocol === 'https:' ? HTTPS : HTTP);
+    return new Promise((resolve, reject) => {
+        const req = mod.request(u, { headers, signal }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => (body += c));
+            res.on('error', (e) => reject(new BerthConfigError('network', `config request failed: ${e.message}`, { cause: e })));
+            res.on('end', () => {
+                const header = (n) => {
+                    const v = res.headers[n.toLowerCase()];
+                    return v === undefined ? null : Array.isArray(v) ? v.join(', ') : v;
+                };
+                resolve({ status: res.statusCode ?? 0, header, body });
+            });
+        });
+        req.on('socket', (s) => s.unref());
+        req.setTimeout(timeoutMs, () => req.destroy(timeoutError(timeoutMs)));
+        req.on('error', (e) => {
+            if (e instanceof BerthConfigError)
+                reject(e);
+            else if (signal.aborted)
+                reject(new BerthConfigError('closed', 'client closed'));
+            else
+                reject(new BerthConfigError('network', `config request failed: ${e.message}`, { cause: e }));
+        });
+        req.end();
+    });
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@evumi/berth-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Client for Berth project Config: cached reads with background long-poll refresh.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evumi/berth.git",
+    "directory": "sdk/js"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/cjs-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}