@faststats/flags-sdk 0.0.1

package/README.md

@@ -0,0 +1,4 @@
+# INITIAL RELEASE — DO NOT USE
+
+This placeholder release exists only to bootstrap npm trusted publishing.
+Do not install or use this version. Wait for the official release.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { Adapter } from "flags";
+//#region src/index.d.ts
+/** Who a flag is evaluated for. Return this from the flag's `identify`. */
+export interface FastStatsEntities {
+  /** Stable device, install or server ID. Required unless `userId` is set. */
+  identifier?: string;
+  /** Your own ID for a signed-in user. Rollouts follow it across devices. */
+  userId?: string;
+  /** Links evaluations to a session in analytics. */
+  sessionId?: string;
+  /** Anything targeting rules should match on. */
+  attributes?: Record<string, unknown>;
+}
+export interface FastStatsAdapterOptions {
+  /**
+   * Public project token or a FastStats API key scoped to one project.
+   * Defaults to `FASTSTATS_FLAGS_TOKEN`, then `FASTSTATS_TOKEN`.
+   */
+  token?: string;
+  /** Base URL of the feature flags service. Defaults to `FASTSTATS_FLAGS_ENDPOINT`. */
+  endpoint?: string;
+  /** Link to a flag in the dashboard, shown in the Flags Explorer. */
+  origin?: string | ((key: string) => string | undefined);
+  /** Aborts an evaluation that takes longer, so the flag serves its default. */
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+export type FastStatsReason = "disabled" | "prerequisite_failed" | "target_match" | "rule_match" | "fallthrough";
+export declare class FastStatsFlagsError extends Error {
+  name: string;
+}
+export declare function createFastStatsAdapter(options?: FastStatsAdapterOptions): <ValueType, EntitiesType extends FastStatsEntities = FastStatsEntities>() => Adapter<ValueType, EntitiesType>;
+/**
+ * Adapter configured from `FASTSTATS_FLAGS_TOKEN` (or `FASTSTATS_TOKEN`) and,
+ * optionally, `FASTSTATS_FLAGS_ENDPOINT`.
+ */
+export declare const fastStatsAdapter: <ValueType, EntitiesType extends FastStatsEntities = FastStatsEntities>() => Adapter<ValueType, EntitiesType>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,76 @@
+//#region src/index.ts
+const DEFAULT_ENDPOINT = "https://flags.faststats.dev";
+const DEFAULT_TIMEOUT_MS = 3e3;
+const COUNTRY_HEADERS = ["x-vercel-ip-country", "cf-ipcountry"];
+var FastStatsFlagsError = class extends Error {
+	name = "FastStatsFlagsError";
+};
+function createFastStatsAdapter(options = {}) {
+	let connection;
+	function connect() {
+		if (!connection) {
+			const token = options.token ?? process.env.FASTSTATS_FLAGS_TOKEN ?? process.env.FASTSTATS_TOKEN;
+			if (!token) throw new FastStatsFlagsError("FastStats Adapter: Missing token. Pass `token` or set FASTSTATS_FLAGS_TOKEN");
+			connection = {
+				url: `${(options.endpoint ?? process.env.FASTSTATS_FLAGS_ENDPOINT ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/v1/evaluate`,
+				token
+			};
+		}
+		return connection;
+	}
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const adapterId = Symbol("faststats");
+	async function evaluate(keys, entities, headers) {
+		if (!entities?.identifier && !entities?.userId) throw new FastStatsFlagsError("FastStats Adapter: identify() must return an identifier or userId");
+		const { url, token } = connect();
+		const attributes = { ...entities.attributes };
+		const country = COUNTRY_HEADERS.map((name) => headers.get(name)).find(Boolean);
+		if (country && attributes.country === void 0) attributes.country = country;
+		const requestHeaders = {
+			"content-type": "application/json",
+			authorization: `Bearer ${token}`
+		};
+		const userAgent = headers.get("user-agent");
+		if (userAgent) requestHeaders["user-agent"] = userAgent;
+		const response = await (options.fetch ?? fetch)(url, {
+			method: "POST",
+			headers: requestHeaders,
+			body: JSON.stringify({
+				identifier: entities.identifier,
+				userId: entities.userId,
+				sessionId: entities.sessionId,
+				attributes,
+				flags: [...new Set(keys)]
+			}),
+			signal: AbortSignal.timeout(timeoutMs),
+			cache: "no-store"
+		});
+		if (!response.ok) throw new FastStatsFlagsError(`FastStats Adapter: Evaluation failed with status ${response.status}`);
+		const body = await response.json();
+		if (typeof body?.flags !== "object" || body.flags === null) throw new FastStatsFlagsError("FastStats Adapter: Unexpected response from the flags service");
+		return body.flags;
+	}
+	return function fastStatsAdapter() {
+		return {
+			adapterId,
+			origin: options.origin,
+			async decide({ key, entities, headers, defaultValue }) {
+				const result = (await evaluate([key], entities, headers))[key];
+				if (result) return result.value;
+				if (defaultValue !== void 0) return defaultValue;
+				throw new FastStatsFlagsError(`FastStats Adapter: Flag "${key}" does not exist and has no defaultValue`);
+			},
+			async bulkDecide({ flags, entities, headers }) {
+				const results = await evaluate(flags.map((flag) => flag.key), entities, headers);
+				return Object.fromEntries(Object.entries(results).map(([key, result]) => [key, result.value]));
+			}
+		};
+	};
+}
+/**
+* Adapter configured from `FASTSTATS_FLAGS_TOKEN` (or `FASTSTATS_TOKEN`) and,
+* optionally, `FASTSTATS_FLAGS_ENDPOINT`.
+*/
+const fastStatsAdapter = createFastStatsAdapter();
+//#endregion
+export { FastStatsFlagsError, createFastStatsAdapter, fastStatsAdapter };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@faststats/flags-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faststats-dev/faststats-javascript.git"
+  },
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "flags": ">=4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "flags": "^4.3.1",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2"
+  }
+}