@stdray-npm/petbox-client 0.1.0-ci.199

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+import { ResolvedConfig } from "./config.js";
+import { TypedEmitter, type PetBoxConfigClientEvents, type PetBoxConfigClientOptions } from "./types.js";
+/**
+ * TypeScript SDK client for PetBox config.
+ *
+ * Fetches resolved config from /v1/conf with ETag-aware polling. Supports all four
+ * response templates (flat, dotnet, envvar, envvar-deep).
+ *
+ * @example
+ * ```ts
+ * const client = new PetBoxConfigClient({
+ *   endpoint: 'https://petbox.3po.su',
+ *   apiKey: process.env.PETBOX_API_KEY!,
+ *   tags: { env: 'prod', project: 'kpvotes' },
+ * });
+ *
+ * const config = await client.start();
+ * console.log(config.get('db.host'));
+ *
+ * client.on('change', (cfg) => console.log('config updated', cfg.data));
+ * ```
+ */
+export declare class PetBoxConfigClient extends TypedEmitter<PetBoxConfigClientEvents> {
+    private readonly options;
+    private readonly fetchImpl;
+    private currentConfig;
+    private etag;
+    private timer;
+    private disposed;
+    constructor(options: PetBoxConfigClientOptions);
+    /** The most recently fetched config, or null if never fetched. */
+    get current(): ResolvedConfig | null;
+    /**
+     * One-shot fetch. Does NOT start background polling.
+     * Throws on auth errors, network errors, and 409 conflicts (unless optional=true).
+     */
+    fetch(): Promise<ResolvedConfig>;
+    /**
+     * Initial fetch + start background ETag polling. Returns the first resolved config.
+     * Fires 'change' events on subsequent updates, 'error' on polling failures.
+     */
+    start(): Promise<ResolvedConfig>;
+    /** Stop background polling. Does NOT clear the last config. */
+    stop(): void;
+    /** Stop polling and remove all listeners. */
+    dispose(): void;
+    private ensureNotDisposed;
+    private buildUrl;
+    private fetchOnce;
+    private startPolling;
+    private poll;
+    private stripEtag;
+    private errorMessage;
+}
+/**
+ * Convenience: one-shot fetch without creating a client instance.
+ * Same as `new PetBoxConfigClient(opts).fetch()`.
+ */
+export declare const fetchConfig: (options: PetBoxConfigClientOptions) => Promise<ResolvedConfig>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAGN,YAAY,EACZ,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAE9B,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,YAAY,CAAC,wBAAwB,CAAC;IAC7E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IACF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,yBAAyB;IAkB9C,kEAAkE;IAClE,IAAI,OAAO,IAAI,cAAc,GAAG,IAAI,CAEnC;IAED;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAatC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAMtC,+DAA+D;IAC/D,IAAI,IAAI,IAAI;IAOZ,6CAA6C;IAC7C,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,QAAQ;YAUF,SAAS;IAqCvB,OAAO,CAAC,YAAY;YAUN,IAAI;IAalB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,YAAY;CAQpB;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,YAAa,yBAAyB,KAAG,OAAO,CAAC,cAAc,CAC/C,CAAC"}

package/dist/client.js

@@ -0,0 +1,187 @@
+import { ResolvedConfig } from "./config.js";
+import { TypedEmitter, PetBoxConfigError, } from "./types.js";
+const DEFAULT_REFRESH_MS = 5 * 60 * 1000;
+/**
+ * TypeScript SDK client for PetBox config.
+ *
+ * Fetches resolved config from /v1/conf with ETag-aware polling. Supports all four
+ * response templates (flat, dotnet, envvar, envvar-deep).
+ *
+ * @example
+ * ```ts
+ * const client = new PetBoxConfigClient({
+ *   endpoint: 'https://petbox.3po.su',
+ *   apiKey: process.env.PETBOX_API_KEY!,
+ *   tags: { env: 'prod', project: 'kpvotes' },
+ * });
+ *
+ * const config = await client.start();
+ * console.log(config.get('db.host'));
+ *
+ * client.on('change', (cfg) => console.log('config updated', cfg.data));
+ * ```
+ */
+export class PetBoxConfigClient extends TypedEmitter {
+    options;
+    fetchImpl;
+    currentConfig = null;
+    etag = null;
+    timer = null;
+    disposed = false;
+    constructor(options) {
+        super();
+        if (!options.endpoint)
+            throw new TypeError("endpoint is required");
+        if (!options.apiKey)
+            throw new TypeError("apiKey is required");
+        if (!options.tags || Object.keys(options.tags).length === 0)
+            throw new TypeError("at least one tag is required");
+        this.options = {
+            endpoint: options.endpoint,
+            apiKey: options.apiKey,
+            tags: options.tags,
+            template: options.template ?? "flat",
+            refreshIntervalMs: options.refreshIntervalMs ?? DEFAULT_REFRESH_MS,
+            optional: options.optional ?? false,
+            fetchImpl: options.fetchImpl,
+        };
+        this.fetchImpl = options.fetchImpl ?? ((...args) => globalThis.fetch(...args));
+    }
+    /** The most recently fetched config, or null if never fetched. */
+    get current() {
+        return this.currentConfig;
+    }
+    /**
+     * One-shot fetch. Does NOT start background polling.
+     * Throws on auth errors, network errors, and 409 conflicts (unless optional=true).
+     */
+    async fetch() {
+        this.ensureNotDisposed();
+        try {
+            const cfg = await this.fetchOnce();
+            this.currentConfig = cfg;
+            this.etag = cfg.etag;
+            return cfg;
+        }
+        catch (err) {
+            if (this.options.optional)
+                return new ResolvedConfig({}, null);
+            throw err;
+        }
+    }
+    /**
+     * Initial fetch + start background ETag polling. Returns the first resolved config.
+     * Fires 'change' events on subsequent updates, 'error' on polling failures.
+     */
+    async start() {
+        const cfg = await this.fetch();
+        this.startPolling();
+        return cfg;
+    }
+    /** Stop background polling. Does NOT clear the last config. */
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Stop polling and remove all listeners. */
+    dispose() {
+        this.disposed = true;
+        this.stop();
+    }
+    // ── internals ──────────────────────────────────────────
+    ensureNotDisposed() {
+        if (this.disposed)
+            throw new Error("PetBoxConfigClient is disposed");
+    }
+    buildUrl() {
+        const base = this.options.endpoint.endsWith("/") ? this.options.endpoint : `${this.options.endpoint}/`;
+        const params = new URLSearchParams();
+        // Sort for stable URLs (helps caching / log grepping).
+        const sortedKeys = Object.keys(this.options.tags).sort();
+        for (const k of sortedKeys)
+            params.set(k, this.options.tags[k] ?? "");
+        if (this.options.template !== "flat")
+            params.set("template", this.options.template);
+        return `${base}v1/conf?${params.toString()}`;
+    }
+    async fetchOnce() {
+        const url = this.buildUrl();
+        const headers = {
+            "X-YobaConf-ApiKey": this.options.apiKey,
+        };
+        if (this.etag !== null)
+            headers["If-None-Match"] = `"${this.etag}"`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, { headers });
+        }
+        catch (cause) {
+            throw new PetBoxConfigError(`Failed to reach PetBox at ${url}: ${String(cause)}`, 0, null);
+        }
+        // 304 — unchanged. Return last-known-good config.
+        if (response.status === 304) {
+            const newEtag = this.stripEtag(response.headers.get("ETag"));
+            return new ResolvedConfig(this.currentConfig?.data ?? {}, newEtag ?? this.etag);
+        }
+        const body = await response.text();
+        if (!response.ok) {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                /* not JSON */
+            }
+            throw new PetBoxConfigError(this.errorMessage(response.status, parsed), response.status, parsed);
+        }
+        const etag = this.stripEtag(response.headers.get("ETag"));
+        const data = JSON.parse(body);
+        return new ResolvedConfig(data, etag);
+    }
+    startPolling() {
+        if (this.options.refreshIntervalMs <= 0)
+            return;
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => {
+            this.poll().catch(() => {
+                /* error emitted inside poll */
+            });
+        }, this.options.refreshIntervalMs);
+    }
+    async poll() {
+        try {
+            const cfg = await this.fetchOnce();
+            if (cfg.etag !== this.etag) {
+                this.currentConfig = cfg;
+                this.etag = cfg.etag;
+                this.emit("change", cfg);
+            }
+        }
+        catch (err) {
+            this.emit("error", err);
+        }
+    }
+    stripEtag(raw) {
+        if (raw === null)
+            return null;
+        // Server sends `"<hex>"` — strip quotes.
+        return raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+    }
+    errorMessage(status, body) {
+        if (body !== null && typeof body === "object" && "error" in body) {
+            const b = body;
+            const reason = typeof b["reason"] === "string" ? `: ${b["reason"]}` : "";
+            return `${b["error"]}${reason}`;
+        }
+        return `HTTP ${status}`;
+    }
+}
+/**
+ * Convenience: one-shot fetch without creating a client instance.
+ * Same as `new PetBoxConfigClient(opts).fetch()`.
+ */
+export const fetchConfig = (options) => new PetBoxConfigClient(options).fetch();
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Immutable resolved config from a PetBox fetch.
+ *
+ * For "flat" template: data is a nested JSON tree; `get("db.host")` traverses it.
+ * For "dotnet" / "envvar" / "envvar-deep": data is a flat `Record<string, string>`;
+ * `get("DB_HOST")` does a direct key lookup.
+ */
+export declare class ResolvedConfig {
+    readonly etag: string | null;
+    private readonly raw;
+    constructor(raw: unknown, etag: string | null);
+    /** The raw parsed JSON response body. */
+    get data(): unknown;
+    /**
+     * Returns the string value at the given dotted path (flat template) or direct key (other templates).
+     * Returns undefined if the path doesn't exist.
+     */
+    get(path: string): string | undefined;
+    /**
+     * Returns the numeric value at the given path, or undefined if missing / not a number.
+     * Accepts JSON numbers and numeric strings.
+     */
+    getNumber(path: string): number | undefined;
+    /**
+     * Returns the boolean value at the given path, or undefined if missing.
+     * Accepts JSON booleans and the strings "true"/"false" (case-insensitive).
+     */
+    getBoolean(path: string): boolean | undefined;
+    /**
+     * Returns the JSON value at the given path (object, array, scalar — whatever the server returned).
+     * Returns undefined if the path doesn't exist.
+     */
+    getJson<T = unknown>(path: string): T | undefined;
+    /**
+     * Flattens the config into a `Record<string, string>` suitable for process env export.
+     * For flat template: expands nested objects to dotted keys. For other templates: returns as-is.
+     */
+    toEnv(): Record<string, string>;
+    private resolve;
+    private flatten;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;gBAElB,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7C,yCAAyC;IACzC,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOrC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW3C;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAY7C;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIjD;;;OAGG;IACH,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ/B,OAAO,CAAC,OAAO;IAoBf,OAAO,CAAC,OAAO;CAUf"}

package/dist/config.js

@@ -0,0 +1,120 @@
+/**
+ * Immutable resolved config from a PetBox fetch.
+ *
+ * For "flat" template: data is a nested JSON tree; `get("db.host")` traverses it.
+ * For "dotnet" / "envvar" / "envvar-deep": data is a flat `Record<string, string>`;
+ * `get("DB_HOST")` does a direct key lookup.
+ */
+export class ResolvedConfig {
+    etag;
+    raw;
+    constructor(raw, etag) {
+        this.raw = raw;
+        this.etag = etag;
+    }
+    /** The raw parsed JSON response body. */
+    get data() {
+        return this.raw;
+    }
+    /**
+     * Returns the string value at the given dotted path (flat template) or direct key (other templates).
+     * Returns undefined if the path doesn't exist.
+     */
+    get(path) {
+        const v = this.resolve(path);
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === "string")
+            return v;
+        return String(v);
+    }
+    /**
+     * Returns the numeric value at the given path, or undefined if missing / not a number.
+     * Accepts JSON numbers and numeric strings.
+     */
+    getNumber(path) {
+        const v = this.resolve(path);
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === "number")
+            return Number.isFinite(v) ? v : undefined;
+        if (typeof v === "string") {
+            const n = Number(v);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the boolean value at the given path, or undefined if missing.
+     * Accepts JSON booleans and the strings "true"/"false" (case-insensitive).
+     */
+    getBoolean(path) {
+        const v = this.resolve(path);
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === "boolean")
+            return v;
+        if (typeof v === "string") {
+            const lower = v.toLowerCase();
+            if (lower === "true")
+                return true;
+            if (lower === "false")
+                return false;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the JSON value at the given path (object, array, scalar — whatever the server returned).
+     * Returns undefined if the path doesn't exist.
+     */
+    getJson(path) {
+        return this.resolve(path);
+    }
+    /**
+     * Flattens the config into a `Record<string, string>` suitable for process env export.
+     * For flat template: expands nested objects to dotted keys. For other templates: returns as-is.
+     */
+    toEnv() {
+        if (this.raw === null || this.raw === undefined)
+            return {};
+        if (typeof this.raw !== "object")
+            return {};
+        const out = {};
+        this.flatten(this.raw, "", out);
+        return out;
+    }
+    resolve(path) {
+        if (this.raw === null || this.raw === undefined)
+            return undefined;
+        if (typeof this.raw !== "object")
+            return undefined;
+        // If the raw data is a flat dictionary (dotnet/envvar/envvar-deep templates),
+        // the keys don't contain dots — do a direct lookup.
+        const obj = this.raw;
+        if (!path.includes("."))
+            return obj[path];
+        // Dotted path — traverse nested object (flat template).
+        const segments = path.split(".");
+        let current = obj;
+        for (const seg of segments) {
+            if (current === null || current === undefined)
+                return undefined;
+            if (typeof current !== "object")
+                return undefined;
+            current = current[seg];
+        }
+        return current;
+    }
+    flatten(obj, prefix, out) {
+        for (const [k, v] of Object.entries(obj)) {
+            const key = prefix ? `${prefix}.${k}` : k;
+            if (v !== null && v !== undefined && typeof v === "object" && !Array.isArray(v)) {
+                this.flatten(v, key, out);
+            }
+            else {
+                out[key] = v === null || v === undefined ? "" : String(v);
+            }
+        }
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PetBoxConfigClient, fetchConfig } from "./client.js";
+export { ResolvedConfig } from "./config.js";
+export { type TagVector, type Template, type PetBoxConfigClientOptions, type PetBoxConfigClientEvents, PetBoxConfigError, TypedEmitter, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACN,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,YAAY,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { PetBoxConfigClient, fetchConfig } from "./client.js";
+export { ResolvedConfig } from "./config.js";
+export { PetBoxConfigError, TypedEmitter, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAKN,iBAAiB,EACjB,YAAY,GACZ,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/** Tag-vector — flat key=value pairs sent as query params to /v1/conf. */
+export type TagVector = Readonly<Record<string, string>>;
+/** Response-shape templates (spec §9.1). */
+export type Template = "flat" | "dotnet" | "envvar" | "envvar-deep";
+/** Options for PetBoxConfigClient. */
+export interface PetBoxConfigClientOptions {
+    /** Base URL of the PetBox server, e.g. "https://petbox.3po.su". Trailing slash optional. */
+    readonly endpoint: string;
+    /** Plaintext API key. Sent as X-YobaConf-ApiKey header on every request. */
+    readonly apiKey: string;
+    /** Tag-vector — every tag the request carries. Resolve finds bindings whose tag-set is a subset. */
+    readonly tags: TagVector;
+    /** Response template (default: "flat"). Controls the shape of the JSON response. */
+    readonly template?: Template;
+    /**
+     * Polling interval in ms. Each poll uses If-None-Match for cheap 304s.
+     * Set to 0 to disable polling (one-shot fetch only). Default: 5 minutes.
+     */
+    readonly refreshIntervalMs?: number;
+    /**
+     * When true, initial fetch failures (network, auth, 409) don't throw — the client
+     * starts with null config and retries on the next poll. Default: false.
+     */
+    readonly optional?: boolean;
+    /** Custom fetch implementation (for testing / proxy injection). */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Structured error from the PetBox config API. */
+export declare class PetBoxConfigError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/** Events emitted by PetBoxConfigClient. */
+export interface PetBoxConfigClientEvents {
+    /** Fired when config changes (200 response with new data). */
+    change: (config: import("./config.js").ResolvedConfig) => void;
+    /** Fired on fetch errors during polling. Initial-fetch errors throw (unless optional). */
+    error: (err: unknown) => void;
+}
+/** Minimal typed event emitter — avoids node:events dependency for portability. */
+export declare class TypedEmitter<Events extends {
+    [K in keyof Events]: (...args: never[]) => void;
+}> {
+    private readonly listeners;
+    on<E extends keyof Events>(event: E, listener: Events[E]): this;
+    off<E extends keyof Events>(event: E, listener: Events[E]): this;
+    protected emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void;
+    protected listenerCount(event: keyof Events): number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEzD,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEpE,sCAAsC;AACtC,MAAM,WAAW,yBAAyB;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAClC;AAED,mDAAmD;AACnD,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM1D;AAED,4CAA4C;AAC5C,MAAM,WAAW,wBAAwB;IACxC,8DAA8D;IAC9D,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,cAAc,KAAK,IAAI,CAAC;IAC/D,0FAA0F;IAC1F,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9B;AAID,mFAAmF;AACnF,qBAAa,YAAY,CAAC,MAAM,SAAS;KAAG,CAAC,IAAI,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI;CAAE;IAC3F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IAEpE,EAAE,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAU/D,GAAG,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAKhE,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAItF,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM;CAGpD"}

package/dist/types.js

@@ -0,0 +1,36 @@
+/** Structured error from the PetBox config API. */
+export class PetBoxConfigError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "PetBoxConfigError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Minimal typed event emitter — avoids node:events dependency for portability. */
+export class TypedEmitter {
+    listeners = new Map();
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+        return this;
+    }
+    emit(event, ...args) {
+        for (const fn of this.listeners.get(event) ?? [])
+            fn(...args);
+    }
+    listenerCount(event) {
+        return this.listeners.get(event)?.size ?? 0;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8BA,mDAAmD;AACnD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,IAAI,CAAU;IAEvB,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAYD,mFAAmF;AACnF,MAAM,OAAO,YAAY;IACP,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEpE,EAAE,CAAyB,KAAQ,EAAE,QAAmB;QACvD,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACV,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAoB,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAyB,KAAQ,EAAE,QAAmB;QACxD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAoB,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACb,CAAC;IAES,IAAI,CAAyB,KAAQ,EAAE,GAAG,IAA2B;QAC9E,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;YAAG,EAA4C,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1G,CAAC;IAES,aAAa,CAAC,KAAmB;QAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IAC7C,CAAC;CACD"}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@stdray-npm/petbox-client",
+	"version": "0.1.0-ci.199",
+	"description": "TypeScript SDK for PetBox — config client with ETag-aware polling. Data + Log surfaces land in 26.3.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write ."
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"typescript": "5.7.3"
+	},
+	"keywords": [
+		"petbox",
+		"configuration",
+		"config"
+	],
+	"license": "MIT",
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stdray/petbox.git",
+		"directory": "src/clients-ts/petbox-client"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	}
+}

package/src/client.ts

@@ -0,0 +1,210 @@
+import { ResolvedConfig } from "./config.js";
+import {
+	type TagVector,
+	type Template,
+	TypedEmitter,
+	type PetBoxConfigClientEvents,
+	type PetBoxConfigClientOptions,
+	PetBoxConfigError,
+} from "./types.js";
+
+const DEFAULT_REFRESH_MS = 5 * 60 * 1000;
+
+/**
+ * TypeScript SDK client for PetBox config.
+ *
+ * Fetches resolved config from /v1/conf with ETag-aware polling. Supports all four
+ * response templates (flat, dotnet, envvar, envvar-deep).
+ *
+ * @example
+ * ```ts
+ * const client = new PetBoxConfigClient({
+ *   endpoint: 'https://petbox.3po.su',
+ *   apiKey: process.env.PETBOX_API_KEY!,
+ *   tags: { env: 'prod', project: 'kpvotes' },
+ * });
+ *
+ * const config = await client.start();
+ * console.log(config.get('db.host'));
+ *
+ * client.on('change', (cfg) => console.log('config updated', cfg.data));
+ * ```
+ */
+export class PetBoxConfigClient extends TypedEmitter<PetBoxConfigClientEvents> {
+	private readonly options: {
+		readonly endpoint: string;
+		readonly apiKey: string;
+		readonly tags: TagVector;
+		readonly template: Template;
+		readonly refreshIntervalMs: number;
+		readonly optional: boolean;
+		readonly fetchImpl: typeof fetch | undefined;
+	};
+	private readonly fetchImpl: typeof fetch;
+	private currentConfig: ResolvedConfig | null = null;
+	private etag: string | null = null;
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private disposed = false;
+
+	constructor(options: PetBoxConfigClientOptions) {
+		super();
+		if (!options.endpoint) throw new TypeError("endpoint is required");
+		if (!options.apiKey) throw new TypeError("apiKey is required");
+		if (!options.tags || Object.keys(options.tags).length === 0) throw new TypeError("at least one tag is required");
+
+		this.options = {
+			endpoint: options.endpoint,
+			apiKey: options.apiKey,
+			tags: options.tags,
+			template: options.template ?? "flat",
+			refreshIntervalMs: options.refreshIntervalMs ?? DEFAULT_REFRESH_MS,
+			optional: options.optional ?? false,
+			fetchImpl: options.fetchImpl,
+		};
+		this.fetchImpl = options.fetchImpl ?? ((...args: Parameters<typeof fetch>) => globalThis.fetch(...args));
+	}
+
+	/** The most recently fetched config, or null if never fetched. */
+	get current(): ResolvedConfig | null {
+		return this.currentConfig;
+	}
+
+	/**
+	 * One-shot fetch. Does NOT start background polling.
+	 * Throws on auth errors, network errors, and 409 conflicts (unless optional=true).
+	 */
+	async fetch(): Promise<ResolvedConfig> {
+		this.ensureNotDisposed();
+		try {
+			const cfg = await this.fetchOnce();
+			this.currentConfig = cfg;
+			this.etag = cfg.etag;
+			return cfg;
+		} catch (err) {
+			if (this.options.optional) return new ResolvedConfig({}, null);
+			throw err;
+		}
+	}
+
+	/**
+	 * Initial fetch + start background ETag polling. Returns the first resolved config.
+	 * Fires 'change' events on subsequent updates, 'error' on polling failures.
+	 */
+	async start(): Promise<ResolvedConfig> {
+		const cfg = await this.fetch();
+		this.startPolling();
+		return cfg;
+	}
+
+	/** Stop background polling. Does NOT clear the last config. */
+	stop(): void {
+		if (this.timer !== null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+
+	/** Stop polling and remove all listeners. */
+	dispose(): void {
+		this.disposed = true;
+		this.stop();
+	}
+
+	// ── internals ──────────────────────────────────────────
+
+	private ensureNotDisposed(): void {
+		if (this.disposed) throw new Error("PetBoxConfigClient is disposed");
+	}
+
+	private buildUrl(): string {
+		const base = this.options.endpoint.endsWith("/") ? this.options.endpoint : `${this.options.endpoint}/`;
+		const params = new URLSearchParams();
+		// Sort for stable URLs (helps caching / log grepping).
+		const sortedKeys = Object.keys(this.options.tags).sort();
+		for (const k of sortedKeys) params.set(k, this.options.tags[k] ?? "");
+		if (this.options.template !== "flat") params.set("template", this.options.template);
+		return `${base}v1/conf?${params.toString()}`;
+	}
+
+	private async fetchOnce(): Promise<ResolvedConfig> {
+		const url = this.buildUrl();
+		const headers: Record<string, string> = {
+			"X-YobaConf-ApiKey": this.options.apiKey,
+		};
+		if (this.etag !== null) headers["If-None-Match"] = `"${this.etag}"`;
+
+		let response: Response;
+		try {
+			response = await this.fetchImpl(url, { headers });
+		} catch (cause) {
+			throw new PetBoxConfigError(`Failed to reach PetBox at ${url}: ${String(cause)}`, 0, null);
+		}
+
+		// 304 — unchanged. Return last-known-good config.
+		if (response.status === 304) {
+			const newEtag = this.stripEtag(response.headers.get("ETag"));
+			return new ResolvedConfig(this.currentConfig?.data ?? {}, newEtag ?? this.etag);
+		}
+
+		const body = await response.text();
+
+		if (!response.ok) {
+			let parsed: unknown = null;
+			try {
+				parsed = JSON.parse(body);
+			} catch {
+				/* not JSON */
+			}
+			throw new PetBoxConfigError(this.errorMessage(response.status, parsed), response.status, parsed);
+		}
+
+		const etag = this.stripEtag(response.headers.get("ETag"));
+		const data: unknown = JSON.parse(body);
+		return new ResolvedConfig(data, etag);
+	}
+
+	private startPolling(): void {
+		if (this.options.refreshIntervalMs <= 0) return;
+		if (this.timer !== null) return;
+		this.timer = setInterval(() => {
+			this.poll().catch(() => {
+				/* error emitted inside poll */
+			});
+		}, this.options.refreshIntervalMs);
+	}
+
+	private async poll(): Promise<void> {
+		try {
+			const cfg = await this.fetchOnce();
+			if (cfg.etag !== this.etag) {
+				this.currentConfig = cfg;
+				this.etag = cfg.etag;
+				this.emit("change", cfg);
+			}
+		} catch (err) {
+			this.emit("error", err);
+		}
+	}
+
+	private stripEtag(raw: string | null): string | null {
+		if (raw === null) return null;
+		// Server sends `"<hex>"` — strip quotes.
+		return raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+	}
+
+	private errorMessage(status: number, body: unknown): string {
+		if (body !== null && typeof body === "object" && "error" in body) {
+			const b = body as Record<string, unknown>;
+			const reason = typeof b["reason"] === "string" ? `: ${b["reason"]}` : "";
+			return `${b["error"]}${reason}`;
+		}
+		return `HTTP ${status}`;
+	}
+}
+
+/**
+ * Convenience: one-shot fetch without creating a client instance.
+ * Same as `new PetBoxConfigClient(opts).fetch()`.
+ */
+export const fetchConfig = (options: PetBoxConfigClientOptions): Promise<ResolvedConfig> =>
+	new PetBoxConfigClient(options).fetch();

package/src/config.ts

@@ -0,0 +1,114 @@
+/**
+ * Immutable resolved config from a PetBox fetch.
+ *
+ * For "flat" template: data is a nested JSON tree; `get("db.host")` traverses it.
+ * For "dotnet" / "envvar" / "envvar-deep": data is a flat `Record<string, string>`;
+ * `get("DB_HOST")` does a direct key lookup.
+ */
+export class ResolvedConfig {
+	readonly etag: string | null;
+	private readonly raw: unknown;
+
+	constructor(raw: unknown, etag: string | null) {
+		this.raw = raw;
+		this.etag = etag;
+	}
+
+	/** The raw parsed JSON response body. */
+	get data(): unknown {
+		return this.raw;
+	}
+
+	/**
+	 * Returns the string value at the given dotted path (flat template) or direct key (other templates).
+	 * Returns undefined if the path doesn't exist.
+	 */
+	get(path: string): string | undefined {
+		const v = this.resolve(path);
+		if (v === undefined || v === null) return undefined;
+		if (typeof v === "string") return v;
+		return String(v);
+	}
+
+	/**
+	 * Returns the numeric value at the given path, or undefined if missing / not a number.
+	 * Accepts JSON numbers and numeric strings.
+	 */
+	getNumber(path: string): number | undefined {
+		const v = this.resolve(path);
+		if (v === undefined || v === null) return undefined;
+		if (typeof v === "number") return Number.isFinite(v) ? v : undefined;
+		if (typeof v === "string") {
+			const n = Number(v);
+			return Number.isFinite(n) ? n : undefined;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Returns the boolean value at the given path, or undefined if missing.
+	 * Accepts JSON booleans and the strings "true"/"false" (case-insensitive).
+	 */
+	getBoolean(path: string): boolean | undefined {
+		const v = this.resolve(path);
+		if (v === undefined || v === null) return undefined;
+		if (typeof v === "boolean") return v;
+		if (typeof v === "string") {
+			const lower = v.toLowerCase();
+			if (lower === "true") return true;
+			if (lower === "false") return false;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Returns the JSON value at the given path (object, array, scalar — whatever the server returned).
+	 * Returns undefined if the path doesn't exist.
+	 */
+	getJson<T = unknown>(path: string): T | undefined {
+		return this.resolve(path) as T | undefined;
+	}
+
+	/**
+	 * Flattens the config into a `Record<string, string>` suitable for process env export.
+	 * For flat template: expands nested objects to dotted keys. For other templates: returns as-is.
+	 */
+	toEnv(): Record<string, string> {
+		if (this.raw === null || this.raw === undefined) return {};
+		if (typeof this.raw !== "object") return {};
+		const out: Record<string, string> = {};
+		this.flatten(this.raw as Record<string, unknown>, "", out);
+		return out;
+	}
+
+	private resolve(path: string): unknown {
+		if (this.raw === null || this.raw === undefined) return undefined;
+		if (typeof this.raw !== "object") return undefined;
+
+		// If the raw data is a flat dictionary (dotnet/envvar/envvar-deep templates),
+		// the keys don't contain dots — do a direct lookup.
+		const obj = this.raw as Record<string, unknown>;
+		if (!path.includes(".")) return obj[path];
+
+		// Dotted path — traverse nested object (flat template).
+		const segments = path.split(".");
+		let current: unknown = obj;
+		for (const seg of segments) {
+			if (current === null || current === undefined) return undefined;
+			if (typeof current !== "object") return undefined;
+			current = (current as Record<string, unknown>)[seg];
+		}
+		return current;
+	}
+
+	private flatten(obj: Record<string, unknown>, prefix: string, out: Record<string, string>): void {
+		for (const [k, v] of Object.entries(obj)) {
+			const key = prefix ? `${prefix}.${k}` : k;
+			if (v !== null && v !== undefined && typeof v === "object" && !Array.isArray(v)) {
+				this.flatten(v as Record<string, unknown>, key, out);
+			} else {
+				out[key] = v === null || v === undefined ? "" : String(v);
+			}
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { PetBoxConfigClient, fetchConfig } from "./client.js";
+export { ResolvedConfig } from "./config.js";
+export {
+	type TagVector,
+	type Template,
+	type PetBoxConfigClientOptions,
+	type PetBoxConfigClientEvents,
+	PetBoxConfigError,
+	TypedEmitter,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,80 @@
+/** Tag-vector — flat key=value pairs sent as query params to /v1/conf. */
+export type TagVector = Readonly<Record<string, string>>;
+
+/** Response-shape templates (spec §9.1). */
+export type Template = "flat" | "dotnet" | "envvar" | "envvar-deep";
+
+/** Options for PetBoxConfigClient. */
+export interface PetBoxConfigClientOptions {
+	/** Base URL of the PetBox server, e.g. "https://petbox.3po.su". Trailing slash optional. */
+	readonly endpoint: string;
+	/** Plaintext API key. Sent as X-YobaConf-ApiKey header on every request. */
+	readonly apiKey: string;
+	/** Tag-vector — every tag the request carries. Resolve finds bindings whose tag-set is a subset. */
+	readonly tags: TagVector;
+	/** Response template (default: "flat"). Controls the shape of the JSON response. */
+	readonly template?: Template;
+	/**
+	 * Polling interval in ms. Each poll uses If-None-Match for cheap 304s.
+	 * Set to 0 to disable polling (one-shot fetch only). Default: 5 minutes.
+	 */
+	readonly refreshIntervalMs?: number;
+	/**
+	 * When true, initial fetch failures (network, auth, 409) don't throw — the client
+	 * starts with null config and retries on the next poll. Default: false.
+	 */
+	readonly optional?: boolean;
+	/** Custom fetch implementation (for testing / proxy injection). */
+	readonly fetchImpl?: typeof fetch;
+}
+
+/** Structured error from the PetBox config API. */
+export class PetBoxConfigError extends Error {
+	readonly status: number;
+	readonly body: unknown;
+
+	constructor(message: string, status: number, body: unknown) {
+		super(message);
+		this.name = "PetBoxConfigError";
+		this.status = status;
+		this.body = body;
+	}
+}
+
+/** Events emitted by PetBoxConfigClient. */
+export interface PetBoxConfigClientEvents {
+	/** Fired when config changes (200 response with new data). */
+	change: (config: import("./config.js").ResolvedConfig) => void;
+	/** Fired on fetch errors during polling. Initial-fetch errors throw (unless optional). */
+	error: (err: unknown) => void;
+}
+
+type Listener = (...args: never[]) => void;
+
+/** Minimal typed event emitter — avoids node:events dependency for portability. */
+export class TypedEmitter<Events extends { [K in keyof Events]: (...args: never[]) => void }> {
+	private readonly listeners = new Map<keyof Events, Set<Listener>>();
+
+	on<E extends keyof Events>(event: E, listener: Events[E]): this {
+		let set = this.listeners.get(event);
+		if (!set) {
+			set = new Set();
+			this.listeners.set(event, set);
+		}
+		set.add(listener as Listener);
+		return this;
+	}
+
+	off<E extends keyof Events>(event: E, listener: Events[E]): this {
+		this.listeners.get(event)?.delete(listener as Listener);
+		return this;
+	}
+
+	protected emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void {
+		for (const fn of this.listeners.get(event) ?? []) (fn as (...a: Parameters<Events[E]>) => void)(...args);
+	}
+
+	protected listenerCount(event: keyof Events): number {
+		return this.listeners.get(event)?.size ?? 0;
+	}
+}