@feathq/js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 feat HQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @feathq/js-sdk
+
+Server-side JavaScript / TypeScript SDK for [feat](https://feat.so) feature flags. Local flag evaluation against a polled datafile, OpenFeature provider included.
+
+For browser code, use [`@feathq/web-sdk`](../web-sdk). For edge runtimes via service binding, use [`@feathq/worker-sdk`](../worker-sdk).
+
+## Install
+
+```bash
+npm install @feathq/js-sdk
+# or
+yarn add @feathq/js-sdk
+```
+
+Node.js 18+ (built-in `fetch`). Bun and Deno are supported.
+
+## Usage
+
+```ts
+import { FeatClient } from "@feathq/js-sdk";
+
+const client = new FeatClient({
+  apiKey: process.env.FEAT_SERVER_KEY!,    // feat_sdk_…
+  dataPlaneUrl: "https://data.feat.so",
+});
+
+await client.ready();
+
+const result = await client.evaluate("checkout-v2", false, {
+  targetingKey: "user-123",
+  user: { plan: "pro", email: "alice@example.com" },
+});
+
+if (result.value) {
+  // …
+}
+```
+
+Use a **server** API key (`feat_sdk_…`). Mobile and client-side keys are for the mobile and browser SDKs respectively.
+
+## OpenFeature
+
+```ts
+import { OpenFeature } from "@openfeature/server-sdk";
+import { FeatClient, FeatProvider } from "@feathq/js-sdk";
+
+const featClient = new FeatClient({ apiKey, dataPlaneUrl });
+await OpenFeature.setProviderAndWait(new FeatProvider(featClient));
+
+const client = OpenFeature.getClient();
+const enabled = await client.getBooleanValue("checkout-v2", false, {
+  targetingKey: "user-123",
+});
+```
+
+## How it works
+
+- The SDK fetches a per-environment **datafile** and keeps it in memory.
+- Polls every 30 s by default (configurable down to 5 s). ETag-aware: unchanged polls are 304s.
+- Evaluation is local; no per-flag network call.
+- `dataPlaneUrl` must use `https://` (the constructor rejects plaintext URLs except `http://localhost` for tests).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+var featEval = require('@feathq/feat-eval');
+var core = require('@openfeature/core');
+
+// src/client.ts
+var MIN_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var FeatClient = class {
+  constructor(config) {
+    this.config = config;
+    assertHttpsUrl(config.dataPlaneUrl);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.pollIntervalMs = Math.max(
+      config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      MIN_POLL_INTERVAL_MS
+    );
+  }
+  config;
+  datafile = null;
+  etag = null;
+  timer = null;
+  readyPromise = null;
+  fetchImpl;
+  pollIntervalMs;
+  async ready() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.bootstrap();
+    }
+    return this.readyPromise;
+  }
+  // Fetch once now. Returns true if the datafile changed.
+  async refresh() {
+    return this.fetchDatafile();
+  }
+  async evaluate(flagKey, defaultValue, context) {
+    if (!this.datafile) {
+      return {
+        value: defaultValue,
+        variationId: null,
+        reason: "ERROR",
+        errorMessage: "client not ready: call client.ready() before evaluate"
+      };
+    }
+    const result = await featEval.evaluate(flagKey, defaultValue, context, this.datafile);
+    return result;
+  }
+  close() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  async bootstrap() {
+    await this.fetchDatafile();
+    this.timer = setInterval(() => {
+      void this.fetchDatafile().catch((err) => {
+        console.warn(
+          "feat: background poll failed:",
+          err instanceof Error ? err.message : String(err)
+        );
+      });
+    }, this.pollIntervalMs);
+    const t = this.timer;
+    t.unref?.();
+  }
+  async fetchDatafile() {
+    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`
+    };
+    if (this.etag) headers["If-None-Match"] = this.etag;
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (res.status === 304) return false;
+    if (res.status === 404) return false;
+    if (!res.ok) {
+      throw new Error(`fetchDatafile failed: ${res.status}`);
+    }
+    const lengthHeader = res.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_DATAFILE_BYTES) {
+      throw new Error("datafile exceeds maximum allowed size");
+    }
+    const next = await res.json();
+    this.datafile = next;
+    this.etag = res.headers.get("etag");
+    return true;
+  }
+};
+function assertHttpsUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol === "https:") return;
+    if (u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1")) {
+      return;
+    }
+  } catch {
+  }
+  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+}
+var FeatProvider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  metadata = { name: "feat" };
+  runsOn = "server";
+  hooks = [];
+  status = "NOT_READY";
+  async initialize() {
+    await this.client.ready();
+    this.status = "READY";
+  }
+  async onClose() {
+    this.client.close();
+    this.status = "NOT_READY";
+  }
+  async resolveBooleanEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "boolean") {
+      return wrongType(defaultValue, typeof result.value, "boolean");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveStringEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "string") {
+      return wrongType(defaultValue, typeof result.value, "string");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveNumberEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "number") {
+      return wrongType(defaultValue, typeof result.value, "number");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveObjectEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    return toResolution(result.value, result);
+  }
+};
+function toResolution(value, result) {
+  return {
+    value,
+    reason: result.reason,
+    ...result.variationId ? { variant: result.variationId } : {},
+    ...result.errorMessage ? { errorCode: core.ErrorCode.GENERAL, errorMessage: result.errorMessage } : {}
+  };
+}
+function wrongType(defaultValue, got, want) {
+  return {
+    value: defaultValue,
+    reason: "ERROR",
+    errorCode: core.ErrorCode.TYPE_MISMATCH,
+    errorMessage: `flag value type ${got} does not match requested ${want}`
+  };
+}
+function toEvalContext(ctx) {
+  const out = {};
+  for (const [k, v] of Object.entries(ctx)) {
+    if (k === "targetingKey" && typeof v === "string") {
+      out.targetingKey = v;
+      continue;
+    }
+    if (v && typeof v === "object" && !Array.isArray(v) && "key" in v) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+Object.defineProperty(exports, "evaluate", {
+  enumerable: true,
+  get: function () { return featEval.evaluate; }
+});
+exports.FeatClient = FeatClient;
+exports.FeatProvider = FeatProvider;

package/dist/index.d.cts

@@ -0,0 +1,45 @@
+import { EvalContext, EvaluationResult } from '@feathq/feat-eval';
+export { ContextKindObject, EvalContext, EvaluationResult, Reason, evaluate } from '@feathq/feat-eval';
+import { ProviderMetadata, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/core';
+import { Provider, Hook, ProviderStatus } from '@openfeature/server-sdk';
+export { Datafile, Operator } from '@feathq/datafile-schema';
+
+interface FeatClientConfig {
+    apiKey: string;
+    dataPlaneUrl: string;
+    pollIntervalMs?: number;
+    fetch?: typeof fetch;
+}
+declare class FeatClient {
+    private readonly config;
+    private datafile;
+    private etag;
+    private timer;
+    private readyPromise;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    constructor(config: FeatClientConfig);
+    ready(): Promise<void>;
+    refresh(): Promise<boolean>;
+    evaluate<T = unknown>(flagKey: string, defaultValue: T, context: EvalContext): Promise<EvaluationResult<T>>;
+    close(): void;
+    private bootstrap;
+    private fetchDatafile;
+}
+
+declare class FeatProvider implements Provider {
+    private readonly client;
+    readonly metadata: ProviderMetadata;
+    readonly runsOn: "server";
+    readonly hooks: Hook[];
+    status: ProviderStatus;
+    constructor(client: FeatClient);
+    initialize(): Promise<void>;
+    onClose(): Promise<void>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<boolean>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<string>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<number>>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<T>>;
+}
+
+export { FeatClient, type FeatClientConfig, FeatProvider };

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { EvalContext, EvaluationResult } from '@feathq/feat-eval';
+export { ContextKindObject, EvalContext, EvaluationResult, Reason, evaluate } from '@feathq/feat-eval';
+import { ProviderMetadata, EvaluationContext, Logger, ResolutionDetails, JsonValue } from '@openfeature/core';
+import { Provider, Hook, ProviderStatus } from '@openfeature/server-sdk';
+export { Datafile, Operator } from '@feathq/datafile-schema';
+
+interface FeatClientConfig {
+    apiKey: string;
+    dataPlaneUrl: string;
+    pollIntervalMs?: number;
+    fetch?: typeof fetch;
+}
+declare class FeatClient {
+    private readonly config;
+    private datafile;
+    private etag;
+    private timer;
+    private readyPromise;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    constructor(config: FeatClientConfig);
+    ready(): Promise<void>;
+    refresh(): Promise<boolean>;
+    evaluate<T = unknown>(flagKey: string, defaultValue: T, context: EvalContext): Promise<EvaluationResult<T>>;
+    close(): void;
+    private bootstrap;
+    private fetchDatafile;
+}
+
+declare class FeatProvider implements Provider {
+    private readonly client;
+    readonly metadata: ProviderMetadata;
+    readonly runsOn: "server";
+    readonly hooks: Hook[];
+    status: ProviderStatus;
+    constructor(client: FeatClient);
+    initialize(): Promise<void>;
+    onClose(): Promise<void>;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<boolean>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<string>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<number>>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, _logger: Logger): Promise<ResolutionDetails<T>>;
+}
+
+export { FeatClient, type FeatClientConfig, FeatProvider };

package/dist/index.js

@@ -0,0 +1,189 @@
+import { evaluate } from '@feathq/feat-eval';
+export { evaluate } from '@feathq/feat-eval';
+import { ErrorCode } from '@openfeature/core';
+
+// src/client.ts
+var MIN_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_POLL_INTERVAL_MS = 3e4;
+var MAX_DATAFILE_BYTES = 10 * 1024 * 1024;
+var FeatClient = class {
+  constructor(config) {
+    this.config = config;
+    assertHttpsUrl(config.dataPlaneUrl);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.pollIntervalMs = Math.max(
+      config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      MIN_POLL_INTERVAL_MS
+    );
+  }
+  config;
+  datafile = null;
+  etag = null;
+  timer = null;
+  readyPromise = null;
+  fetchImpl;
+  pollIntervalMs;
+  async ready() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.bootstrap();
+    }
+    return this.readyPromise;
+  }
+  // Fetch once now. Returns true if the datafile changed.
+  async refresh() {
+    return this.fetchDatafile();
+  }
+  async evaluate(flagKey, defaultValue, context) {
+    if (!this.datafile) {
+      return {
+        value: defaultValue,
+        variationId: null,
+        reason: "ERROR",
+        errorMessage: "client not ready: call client.ready() before evaluate"
+      };
+    }
+    const result = await evaluate(flagKey, defaultValue, context, this.datafile);
+    return result;
+  }
+  close() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  async bootstrap() {
+    await this.fetchDatafile();
+    this.timer = setInterval(() => {
+      void this.fetchDatafile().catch((err) => {
+        console.warn(
+          "feat: background poll failed:",
+          err instanceof Error ? err.message : String(err)
+        );
+      });
+    }, this.pollIntervalMs);
+    const t = this.timer;
+    t.unref?.();
+  }
+  async fetchDatafile() {
+    const url = `${this.config.dataPlaneUrl.replace(/\/$/, "")}/sdk/v1/datafile`;
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`
+    };
+    if (this.etag) headers["If-None-Match"] = this.etag;
+    const res = await this.fetchImpl(url, { method: "GET", headers });
+    if (res.status === 304) return false;
+    if (res.status === 404) return false;
+    if (!res.ok) {
+      throw new Error(`fetchDatafile failed: ${res.status}`);
+    }
+    const lengthHeader = res.headers.get("content-length");
+    if (lengthHeader && Number(lengthHeader) > MAX_DATAFILE_BYTES) {
+      throw new Error("datafile exceeds maximum allowed size");
+    }
+    const next = await res.json();
+    this.datafile = next;
+    this.etag = res.headers.get("etag");
+    return true;
+  }
+};
+function assertHttpsUrl(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol === "https:") return;
+    if (u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1")) {
+      return;
+    }
+  } catch {
+  }
+  throw new Error("dataPlaneUrl must use https:// (http://localhost allowed for tests)");
+}
+var FeatProvider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  metadata = { name: "feat" };
+  runsOn = "server";
+  hooks = [];
+  status = "NOT_READY";
+  async initialize() {
+    await this.client.ready();
+    this.status = "READY";
+  }
+  async onClose() {
+    this.client.close();
+    this.status = "NOT_READY";
+  }
+  async resolveBooleanEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "boolean") {
+      return wrongType(defaultValue, typeof result.value, "boolean");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveStringEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "string") {
+      return wrongType(defaultValue, typeof result.value, "string");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveNumberEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    if (typeof result.value !== "number") {
+      return wrongType(defaultValue, typeof result.value, "number");
+    }
+    return toResolution(result.value, result);
+  }
+  async resolveObjectEvaluation(flagKey, defaultValue, context, _logger) {
+    const result = await this.client.evaluate(
+      flagKey,
+      defaultValue,
+      toEvalContext(context)
+    );
+    return toResolution(result.value, result);
+  }
+};
+function toResolution(value, result) {
+  return {
+    value,
+    reason: result.reason,
+    ...result.variationId ? { variant: result.variationId } : {},
+    ...result.errorMessage ? { errorCode: ErrorCode.GENERAL, errorMessage: result.errorMessage } : {}
+  };
+}
+function wrongType(defaultValue, got, want) {
+  return {
+    value: defaultValue,
+    reason: "ERROR",
+    errorCode: ErrorCode.TYPE_MISMATCH,
+    errorMessage: `flag value type ${got} does not match requested ${want}`
+  };
+}
+function toEvalContext(ctx) {
+  const out = {};
+  for (const [k, v] of Object.entries(ctx)) {
+    if (k === "targetingKey" && typeof v === "string") {
+      out.targetingKey = v;
+      continue;
+    }
+    if (v && typeof v === "object" && !Array.isArray(v) && "key" in v) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export { FeatClient, FeatProvider };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@feathq/js-sdk",
+  "version": "0.1.0",
+  "description": "feat feature-flag SDK for JavaScript and TypeScript (server-side, OpenFeature provider)",
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "openfeature",
+    "feat",
+    "feature-management"
+  ],
+  "license": "MIT",
+  "author": "feat HQ <engineering@feat.so>",
+  "homepage": "https://feat.so",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/feathq/js-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/feathq/js-sdk/issues"
+  },
+  "type": "module",
+  "packageManager": "yarn@4.14.1",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@feathq/datafile-schema": "^0.1.0",
+    "@feathq/feat-eval": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@openfeature/server-sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@openfeature/core": "^1.10.0",
+    "@openfeature/server-sdk": "^1.18.0",
+    "@types/node": "^25.6.2",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "resolutions": {
+    "@feathq/datafile-schema": "portal:../../packages/datafile-schema",
+    "@feathq/datafile-schema@workspace:*": "portal:../../packages/datafile-schema",
+    "@feathq/feat-eval": "portal:../../packages/feat-eval"
+  }
+}