@redpennon/node-sdk 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @redpennon/node-sdk
+
+[![npm](https://img.shields.io/npm/v/@redpennon/node-sdk)](https://www.npmjs.com/package/@redpennon/node-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/redpennon/sdks/blob/main/LICENSE)
+
+Thin HTTP client for the [RedPennon](https://redpennon.dev) feature flag evaluation API.
+
+## Installation
+
+```bash
+npm install @redpennon/node-sdk
+```
+
+Requires Node 20+. No runtime dependencies — uses the global `fetch`.
+
+## Quick start
+
+```ts
+import { RedPennonClient } from "@redpennon/node-sdk";
+
+const client = new RedPennonClient({ apiKey: "YOUR_ENV_API_KEY" });
+
+// Simple: get the resolved value or your default on any failure.
+const enabled = await client.variableValue("dark-mode-enabled", {
+  default: false,
+});
+
+// With user context (for targeting rules).
+const user = { id: "user_123", email: "alice@example.com" };
+const enabled = await client.variableValue("dark-mode-enabled", {
+  default: false,
+  user,
+});
+
+// Full result: value + variation + reason.
+const result = await client.variable("dark-mode-enabled", { user });
+console.log(result.value, result.variation, result.reason);
+
+// Batch: resolve many flags in one round-trip.
+const results = await client.variables(["flag-a", "flag-b"], { user });
+const flagA = results["flag-a"].value;
+```
+
+## API
+
+### `new RedPennonClient({ apiKey, baseUrl?, fetchImpl? })`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `apiKey` | `string` | Environment API key from the RedPennon dashboard. |
+| `baseUrl` | `string?` | Override the API base URL (default: `https://api.redpennon.dev`). |
+| `fetchImpl` | `typeof fetch?` | Custom fetch — useful for testing. |
+
+### `client.variableValue(key, { default, user? }) → Promise<T>`
+
+Returns the resolved value or `default` on any failure (network error, non-2xx, `value=null`). Use this in production code — your default is the load-bearing contract.
+
+### `client.variable(key, { user? }) → Promise<VariableResult>`
+
+Returns the full evaluation result (`value`, `variation`, `reason`, `feature`). Throws `APIError` on network or non-2xx errors.
+
+### `client.variables(keys, { user? }) → Promise<Record<string, VariableResult>>`
+
+Batch evaluation — one HTTP round-trip for multiple flags. Unknown keys return `reason: "variable_not_found"` inline rather than throwing.
+
+## Local development
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+## License
+
+[MIT](../LICENSE) © RedPennon

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * RedPennon Node SDK — variable-key evaluation client.
+ *
+ * Two evaluation methods cover the two SDK ergonomics teams reach
+ * for:
+ *
+ *   * {@link RedPennonClient.variableValue} — "give me the value, or
+ *     this fallback". Returns the resolved value or the
+ *     developer-supplied default. Network failures swallow into the
+ *     default so the calling app never crashes because the API is
+ *     unreachable; the developer's code default is the contract.
+ *
+ *   * {@link RedPennonClient.variable} — "give me the full result
+ *     object". Returns the typed result (`value`, `variation`,
+ *     `reason`, `feature`) so callers can branch on `reason` for
+ *     telemetry, dashboards, or per-state UI. Network failures
+ *     surface as {@link APIError}; callers opting into the result
+ *     shape opt into error handling.
+ *
+ * Batch evaluation ({@link RedPennonClient.variables}) lets one HTTP
+ * round-trip resolve many flags for the same user context.
+ */
+export declare const DEFAULT_API_BASE_URL = "https://api.redpennon.dev";
+export type UserContext = {
+    id?: string;
+    email?: string;
+    organisation_id?: string;
+    ip?: string;
+    audiences?: string[];
+    /**
+     * Application version string supplied by the calling app. The
+     * evaluator treats it as opaque text — operators like `is`,
+     * `contains`, and `starts_with` work; numeric/semver comparisons do
+     * not. Server-side SDKs can't auto-detect this, so populate it
+     * manually if you need to target on it.
+     */
+    app_version?: string;
+    /**
+     * Free-form platform identifier (e.g. `"ios"`, `"android"`,
+     * `"web"`). Server-side SDKs don't auto-populate this either.
+     */
+    platform?: string;
+    /**
+     * ISO-3166 alpha-2 country code (e.g. `"AU"`, `"US"`).
+     */
+    country?: string;
+    /**
+     * Arbitrary user attributes for `custom_property` targeting
+     * conditions. Keys are looked up by the rule's `custom_key`; values
+     * may be strings, numbers, booleans, or arrays of strings.
+     */
+    custom_data?: Record<string, unknown>;
+};
+/**
+ * Reasons surfaced by the evaluation engine. Mirrors the server-side
+ * constants 1:1 so SDK consumers can switch on the string value.
+ */
+export type EvaluationReason = "targeting_rule_matched" | "default_variation" | "no_rule_matched" | "targeting_disabled" | "feature_complete" | "feature_deleted" | "feature_archived" | "self_targeting_override" | "variable_not_found";
+export type VariableResult<T> = {
+    key: string;
+    /** Resolved value, or `null` when the platform served no value. */
+    value: T | null;
+    /** Variation slug served, or `null` when no value was served. */
+    variation: string | null;
+    reason: EvaluationReason;
+    /** Parent feature slug, or `null` when the key didn't resolve. */
+    feature: string | null;
+    /** Opaque signed trace token returned by the server when the user has stable identity (`id` or `email`). `null` or absent when not available. Pass to `trackEvents` to correlate metric events with evaluations. */
+    evaluation_trace?: string | null;
+};
+export type BatchResults = Record<string, VariableResult<unknown>>;
+export type EventPayload = {
+    event: string;
+    variable: string;
+    variation: string;
+    user?: UserContext;
+    value?: number;
+    /** ISO-8601 timestamp; defaults to server receive time when omitted. */
+    occurred_at?: string;
+    /** Opaque trace token from a prior {@link VariableResult.evaluation_trace}. */
+    evaluation_trace?: string;
+};
+export type TrackEventsResult = {
+    accepted: number;
+};
+export declare class APIError extends Error {
+    readonly statusCode: number;
+    readonly body: string;
+    /**
+     * Platform governance error code parsed from the response body's
+     * structured `{"error", "code"}` payload (e.g. `rate_limit_exceeded`,
+     * `organisation_suspended`, `monthly_active_users_exceeded`).
+     * `null` for transport errors or unstructured responses. Callers
+     * branching on governance state should match on `code`, not `message`.
+     */
+    readonly code: string | null;
+    constructor(statusCode: number, message: string, body: string, code?: string | null);
+}
+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;
+};
+export type EvalOptions = {
+    user?: UserContext;
+};
+/**
+ * Thin client around the variable-key evaluation endpoints.
+ * Stateless — one instance can serve any number of concurrent
+ * evaluations and is safe to keep as a module-level singleton.
+ */
+export declare class RedPennonClient {
+    readonly origin: string;
+    readonly apiKey: string;
+    readonly fetchImpl: typeof fetch;
+    constructor(options: ClientOptions);
+    /**
+     * Resolve a single variable to its full result object.
+     *
+     * Network errors and non-2xx responses surface as {@link APIError};
+     * callers that want fail-open semantics should use
+     * {@link variableValue} instead.
+     */
+    variable<T = unknown>(key: string, options?: EvalOptions): Promise<VariableResult<T>>;
+    /**
+     * Resolve a single variable to its value, falling back to
+     * `defaultValue` whenever the platform served no value (network
+     * error, unknown key, deleted/archived feature, targeting
+     * disabled). This is the method that should be reached for in
+     * application code: the developer-supplied default is the
+     * load-bearing contract.
+     */
+    variableValue<T>(key: string, defaultValue: T, options?: EvalOptions): Promise<T>;
+    /**
+     * Record one or more metric events. Pass the `evaluation_trace` from a
+     * prior {@link variable} call to correlate events with the evaluation
+     * that triggered them.
+     *
+     * Throws {@link APIError} on any non-2xx response, including governance
+     * errors (`events_batch_too_large`, `rate_limit_exceeded`, etc.).
+     */
+    trackEvents(events: EventPayload[]): Promise<TrackEventsResult>;
+    /**
+     * Resolve multiple variables in one HTTP round-trip. Each result
+     * has the same shape as {@link variable}; unknown keys surface as
+     * `variable_not_found` inline.
+     */
+    variables(keys: string[], options?: EvalOptions): Promise<BatchResults>;
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,yBAAyB,GACzB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oNAAoN;IACpN,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;AAEnE,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEjB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,IAAW;CAO1F;AAcD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,KAAK,CAAC;gBAErB,OAAO,EAAE,aAAa;IAMlC;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAuB7B;;;;;;;OAOG;IACG,aAAa,CAAC,CAAC,EACnB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC;IAYb;;;;;;;OAOG;IACG,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkBrE;;;;OAIG;IACG,SAAS,CACb,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,YAAY,CAAC;CAoBzB"}

package/dist/index.js

@@ -0,0 +1,161 @@
+/**
+ * RedPennon Node SDK — variable-key evaluation client.
+ *
+ * Two evaluation methods cover the two SDK ergonomics teams reach
+ * for:
+ *
+ *   * {@link RedPennonClient.variableValue} — "give me the value, or
+ *     this fallback". Returns the resolved value or the
+ *     developer-supplied default. Network failures swallow into the
+ *     default so the calling app never crashes because the API is
+ *     unreachable; the developer's code default is the contract.
+ *
+ *   * {@link RedPennonClient.variable} — "give me the full result
+ *     object". Returns the typed result (`value`, `variation`,
+ *     `reason`, `feature`) so callers can branch on `reason` for
+ *     telemetry, dashboards, or per-state UI. Network failures
+ *     surface as {@link APIError}; callers opting into the result
+ *     shape opt into error handling.
+ *
+ * Batch evaluation ({@link RedPennonClient.variables}) lets one HTTP
+ * round-trip resolve many flags for the same user context.
+ */
+export const DEFAULT_API_BASE_URL = "https://api.redpennon.dev";
+export class APIError extends Error {
+    statusCode;
+    body;
+    /**
+     * Platform governance error code parsed from the response body's
+     * structured `{"error", "code"}` payload (e.g. `rate_limit_exceeded`,
+     * `organisation_suspended`, `monthly_active_users_exceeded`).
+     * `null` for transport errors or unstructured responses. Callers
+     * branching on governance state should match on `code`, not `message`.
+     */
+    code;
+    constructor(statusCode, message, body, code = null) {
+        super(`redpennon: api error ${statusCode}: ${message}`);
+        this.name = "APIError";
+        this.statusCode = statusCode;
+        this.body = body;
+        this.code = code;
+    }
+}
+function parseErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object" && typeof parsed.code === "string" && parsed.code) {
+            return parsed.code;
+        }
+    }
+    catch {
+        // Body is not JSON; leave code unparsed.
+    }
+    return null;
+}
+/**
+ * Thin client around the variable-key evaluation endpoints.
+ * Stateless — one instance can serve any number of concurrent
+ * evaluations and is safe to keep as a module-level singleton.
+ */
+export class RedPennonClient {
+    origin;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        this.origin = (options.baseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    }
+    /**
+     * Resolve a single variable to its full result object.
+     *
+     * Network errors and non-2xx responses surface as {@link APIError};
+     * callers that want fail-open semantics should use
+     * {@link variableValue} instead.
+     */
+    async variable(key, options = {}) {
+        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),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
+        }
+        return (await response.json());
+    }
+    /**
+     * Resolve a single variable to its value, falling back to
+     * `defaultValue` whenever the platform served no value (network
+     * error, unknown key, deleted/archived feature, targeting
+     * disabled). This is the method that should be reached for in
+     * application code: the developer-supplied default is the
+     * load-bearing contract.
+     */
+    async variableValue(key, defaultValue, options = {}) {
+        try {
+            const result = await this.variable(key, options);
+            return result.value === null ? defaultValue : result.value;
+        }
+        catch {
+            // Swallow all errors — network, API, JSON parse — and serve the
+            // developer-supplied default. The SDK's job is to keep the
+            // calling app running, not to surface infra problems.
+            return defaultValue;
+        }
+    }
+    /**
+     * Record one or more metric events. Pass the `evaluation_trace` from a
+     * prior {@link variable} call to correlate events with the evaluation
+     * that triggered them.
+     *
+     * Throws {@link APIError} on any non-2xx response, including governance
+     * 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 }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
+        }
+        return (await response.json());
+    }
+    /**
+     * Resolve multiple variables in one HTTP round-trip. Each result
+     * has the same shape as {@link variable}; unknown keys surface as
+     * `variable_not_found` inline.
+     */
+    async variables(keys, options = {}) {
+        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),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new APIError(response.status, response.statusText, text, parseErrorCode(text));
+        }
+        const parsed = (await response.json());
+        return parsed.results;
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@redpennon/node-sdk",
+  "version": "1.0.0",
+  "description": "RedPennon feature flag evaluation API client for Node.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/redpennon/sdks.git",
+    "directory": "node"
+  },
+  "homepage": "https://docs.redpennon.dev",
+  "bugs": "https://github.com/redpennon/sdks/issues",
+  "keywords": ["feature-flags", "feature-toggles", "redpennon"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  },
+  "license": "MIT"
+}