@redpennon/node-sdk 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -79,9 +79,20 @@ export type EventPayload = {
     occurred_at?: string;
     /** Opaque trace token from a prior {@link VariableResult.evaluation_trace}. */
     evaluation_trace?: string;
+    /**
+     * De-duplication key, unique per environment, at most 200 characters.
+     *
+     * Send one and a retry after a timeout is free: the platform skips
+     * keys it has already stored instead of counting the event twice.
+     * Omit it and repeats are stored — which is correct for genuinely
+     * repeated events, since nothing else can tell them apart.
+     */
+    event_id?: string;
 };
 export type TrackEventsResult = {
     accepted: number;
+    /** Rows skipped because their `event_id` was already stored. */
+    duplicates?: number;
 };
 export declare class APIError extends Error {
     readonly statusCode: number;
@@ -96,12 +107,28 @@ export declare class APIError extends Error {
     readonly code: string | null;
     constructor(statusCode: number, message: string, body: string, code?: string | null);
 }
+/**
+ * Default per-request timeout, in milliseconds.
+ *
+ * A flag lookup that has not answered within a second is not going to
+ * be useful to the render that asked for it. Without a bound, a hung
+ * API hangs the calling application indefinitely — the exact failure
+ * the fail-open design exists to prevent, and one `variableValue`
+ * cannot catch because the request never returns.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 1000;
 export type ClientOptions = {
     apiKey: string;
     /** Override the API origin. Defaults to {@link DEFAULT_API_BASE_URL}. */
     baseUrl?: string;
     /** Override the fetch implementation (handy for tests). */
     fetchImpl?: typeof fetch;
+    /**
+     * Per-request timeout in milliseconds. Defaults to
+     * {@link DEFAULT_TIMEOUT_MS}. Pass 0 to disable the bound entirely —
+     * only sensible when the caller imposes its own.
+     */
+    timeoutMs?: number;
 };
 export type EvalOptions = {
     user?: UserContext;
@@ -115,7 +142,10 @@ export declare class RedPennonClient {
     readonly origin: string;
     readonly apiKey: string;
     readonly fetchImpl: typeof fetch;
+    readonly timeoutMs: number;
     constructor(options: ClientOptions);
+    /** Request init shared by every call, including the timeout signal. */
+    private requestInit;
     /**
      * Resolve a single variable to its full result object.
      *
@@ -148,5 +178,16 @@ export declare class RedPennonClient {
      * `variable_not_found` inline.
      */
     variables(keys: string[], options?: EvalOptions): Promise<BatchResults>;
+    /**
+     * Batch counterpart of {@link variableValue}: resolve many keys and
+     * return a value for each, falling back to the matching entry in
+     * `defaults` whenever the platform served no value or the call failed
+     * outright.
+     *
+     * Without this, only the single-key path actually failed open — a
+     * caller batching for efficiency had to hand-roll the try/catch that
+     * makes the SDK's central promise true.
+     */
+    variableValues<T extends Record<string, unknown>>(defaults: T, options?: EvalOptions): Promise<T>;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -52,6 +52,16 @@ function parseErrorCode(body) {
     }
     return null;
 }
+/**
+ * Default per-request timeout, in milliseconds.
+ *
+ * A flag lookup that has not answered within a second is not going to
+ * be useful to the render that asked for it. Without a bound, a hung
+ * API hangs the calling application indefinitely — the exact failure
+ * the fail-open design exists to prevent, and one `variableValue`
+ * cannot catch because the request never returns.
+ */
+export const DEFAULT_TIMEOUT_MS = 1000;
 /**
  * Thin client around the variable-key evaluation endpoints.
  * Stateless — one instance can serve any number of concurrent
@@ -61,10 +71,27 @@ export class RedPennonClient {
     origin;
     apiKey;
     fetchImpl;
+    timeoutMs;
     constructor(options) {
         this.origin = (options.baseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
         this.apiKey = options.apiKey;
         this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** Request init shared by every call, including the timeout signal. */
+    requestInit(body) {
+        const init = {
+            method: "POST",
+            headers: {
+                "X-API-Key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        };
+        if (this.timeoutMs > 0) {
+            init.signal = AbortSignal.timeout(this.timeoutMs);
+        }
+        return init;
     }
     /**
      * Resolve a single variable to its full result object.
@@ -77,14 +104,7 @@ export class RedPennonClient {
         const body = {};
         if (options.user)
             body.user = options.user;
-        const response = await this.fetchImpl(`${this.origin}/v1/variables/${encodeURIComponent(key)}`, {
-            method: "POST",
-            headers: {
-                "X-API-Key": this.apiKey,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(body),
-        });
+        const response = await this.fetchImpl(`${this.origin}/v1/variables/${encodeURIComponent(key)}`, this.requestInit(body));
         if (!response.ok) {
             const text = await response.text();
             throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
@@ -120,14 +140,7 @@ export class RedPennonClient {
      * errors (`events_batch_too_large`, `rate_limit_exceeded`, etc.).
      */
     async trackEvents(events) {
-        const response = await this.fetchImpl(`${this.origin}/v1/events`, {
-            method: "POST",
-            headers: {
-                "X-API-Key": this.apiKey,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ events }),
-        });
+        const response = await this.fetchImpl(`${this.origin}/v1/events`, this.requestInit({ events }));
         if (!response.ok) {
             const text = await response.text();
             throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
@@ -143,14 +156,7 @@ export class RedPennonClient {
         const body = { keys };
         if (options.user)
             body.user = options.user;
-        const response = await this.fetchImpl(`${this.origin}/v1/variables`, {
-            method: "POST",
-            headers: {
-                "X-API-Key": this.apiKey,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(body),
-        });
+        const response = await this.fetchImpl(`${this.origin}/v1/variables`, this.requestInit(body));
         if (!response.ok) {
             const text = await response.text();
             throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
@@ -158,4 +164,31 @@ export class RedPennonClient {
         const parsed = (await response.json());
         return parsed.results;
     }
+    /**
+     * Batch counterpart of {@link variableValue}: resolve many keys and
+     * return a value for each, falling back to the matching entry in
+     * `defaults` whenever the platform served no value or the call failed
+     * outright.
+     *
+     * Without this, only the single-key path actually failed open — a
+     * caller batching for efficiency had to hand-roll the try/catch that
+     * makes the SDK's central promise true.
+     */
+    async variableValues(defaults, options = {}) {
+        const keys = Object.keys(defaults);
+        try {
+            const results = await this.variables(keys, options);
+            const out = { ...defaults };
+            for (const key of keys) {
+                const value = results[key]?.value;
+                if (value !== null && value !== undefined) {
+                    out[key] = value;
+                }
+            }
+            return out;
+        }
+        catch {
+            return { ...defaults };
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpennon/node-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "RedPennon feature flag evaluation API client for Node.js",
   "type": "module",
   "main": "./dist/index.js",