@maksymshypytsia/flags-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @maksymshypytsia/flags-sdk
+
+Tiny client for the [feature-flags-saas](https://github.com/ShipaM/feature-flags-saas)
+service. It makes **one** request, caches the result in memory and then decides
+locally and deterministically whether a flag is on for a user.
+No polling, no WebSocket.
+
+## Install
+
+```bash
+npm install @maksymshypytsia/flags-sdk
+```
+
+## Quick start
+
+```ts
+import { getFlags } from "@maksymshypytsia/flags-sdk";
+const flags = await getFlags({
+  apiKey: "ffk_prod_...", // dashboard -> Project -> API keys
+  userKey: "user-42", // any stable id: user id, email, ...
+  baseUrl: "https://flags.example.com", // where the service runs
+});
+if (flags.isEnabled("new-checkout")) {
+  // show the new checkout
+}
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Development
+
+```bash
+npm install         # install dev dependencies
+npm run typecheck   # tsc --noEmit, type errors only
+npm test            # vitest run
+```
+
+### Build and pack
+
+```bash
+npm run build       # tsc -> dist/ (old dist/ is deleted first)
+ls dist             # hashRollout.d.ts hashRollout.js index.d.ts index.js
+npm pack --dry-run  # list what goes into the package, creates nothing
+npm pack            # create maksymshypytsia-flags-sdk-0.1.0.tgz
+```
+
+Only `dist/`, `README.md` and `package.json` end up in the package
+(see `"files"` in `package.json`). Test files are excluded from the build
+by `tsconfig.build.json`.
+
+### Try the package locally
+
+Install the `.tgz` into any other project to check it before publishing:
+
+```bash
+cd ../some-app
+npm install ../feature-flags-sdk/maksymshypytsia-flags-sdk-0.1.0.tgz
+```
+
+`*.tgz` and `dist/` are in `.gitignore`, so they are never committed.

package/dist/hashRollout.d.ts

@@ -0,0 +1,6 @@
+/** Fast, non-cryptographic hash. Returns a number from 0 to 2^32 - 1. */
+export declare function fnv1a(input: string): number;
+/** Get a user's bucket from 0 to 99 for a specific flag. */
+export declare function getBucket(userKey: string, flagKey: string): number;
+/** Check if a flag is enabled for a user at the given rollout percentage. */
+export declare function isEnabledForUser(userKey: string, flagKey: string, rolloutPercentage: number): boolean;

package/dist/hashRollout.js

@@ -0,0 +1,31 @@
+// Deterministic rollout: the same user and flag always get the same result.
+const FNV_OFFSET_BASIS = 0x811c9dc5; // Initial value for FNV-1a (32-bit).
+const FNV_PRIME = 0x01000193; // FNV-1a multiplication constant.
+const encoder = new TextEncoder();
+/** Fast, non-cryptographic hash. Returns a number from 0 to 2^32 - 1. */
+export function fnv1a(input) {
+    let hash = FNV_OFFSET_BASIS;
+    // Hash the UTF-8 bytes so different languages get the same result.
+    for (const byte of encoder.encode(input)) {
+        hash ^= byte; // Mix the byte into the hash.
+        hash = Math.imul(hash, FNV_PRIME); // Multiply using 32-bit arithmetic.
+    }
+    return hash >>> 0; // Convert the result to an unsigned 32-bit number.
+}
+/** Get a user's bucket from 0 to 99 for a specific flag. */
+export function getBucket(userKey, flagKey) {
+    // Combine user and flag so each flag gets its own rollout.
+    return fnv1a(`${userKey}:${flagKey}`) % 100;
+}
+/** Check if a flag is enabled for a user at the given rollout percentage. */
+export function isEnabledForUser(userKey, flagKey, rolloutPercentage) {
+    // Handle edge cases explicitly.
+    if (Number.isNaN(rolloutPercentage))
+        return false;
+    if (rolloutPercentage <= 0)
+        return false;
+    if (rolloutPercentage >= 100)
+        return true;
+    // Enable the flag if the user's bucket is inside the rollout range.
+    return getBucket(userKey, flagKey) < rolloutPercentage;
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { isEnabledForUser } from "./hashRollout.js";
+export { isEnabledForUser };
+/** One flag exactly as GET /api/v1/flags returns it. */
+export type FlagData = {
+    enabled: boolean;
+    rollout: number;
+};
+export type GetFlagsOptions = {
+    /** Project API key, e.g. "ffk_prod_...". Sent as "Authorization: Bearer <key>". */
+    apiKey: string;
+    /** Any stable id of the end user (user id, email...). Decides the rollout bucket. */
+    userKey: string;
+    /** Where the feature-flags service lives, e.g. "https://flags.example.com". */
+    baseUrl: string;
+};
+export type FlagsClient = {
+    /** true if the flag exists, is enabled and the user is inside its rollout. */
+    isEnabled(flagKey: string): boolean;
+};
+/** Forget cached flags. The next getFlags() call fetches again. */
+export declare function clearCache(): void;
+export declare function getFlags(options: GetFlagsOptions): Promise<FlagsClient>;

package/dist/index.js

@@ -0,0 +1,48 @@
+import { isEnabledForUser } from "./hashRollout.js";
+// Re-exported so a server can reuse the exact same rollout logic as the SDK.
+export { isEnabledForUser };
+// In-memory cache: ONE network request per baseUrl + apiKey.
+// We store the Promise, so parallel getFlags() calls share the same request.
+const cache = new Map();
+/** Forget cached flags. The next getFlags() call fetches again. */
+export function clearCache() {
+    cache.clear();
+}
+async function fetchFlags(apiKey, baseUrl) {
+    const res = await fetch(`${baseUrl}/api/v1/flags`, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok)
+        throw new Error(`Failed to load flags: HTTP ${res.status}`);
+    const body = (await res.json());
+    if (!body || typeof body.flags !== "object" || body.flags === null) {
+        throw new Error("Failed to load flags: unexpected response format");
+    }
+    return body.flags;
+}
+export async function getFlags(options) {
+    const { apiKey, userKey, baseUrl } = options;
+    if (!apiKey)
+        throw new TypeError("getFlags: apiKey is required");
+    if (!userKey)
+        throw new TypeError("getFlags: userKey is required");
+    if (!baseUrl)
+        throw new TypeError("getFlags: baseUrl is required");
+    const base = baseUrl.replace(/\/+$/, ""); // "https://x.com/" -> "https://x.com"
+    const cacheKey = `${base}|${apiKey}`;
+    let pending = cache.get(cacheKey);
+    if (!pending) {
+        pending = fetchFlags(apiKey, base);
+        cache.set(cacheKey, pending);
+        pending.catch(() => cache.delete(cacheKey)); // never cache a failure
+    }
+    const data = await pending;
+    return {
+        isEnabled(flagKey) {
+            const flag = data[flagKey];
+            if (!flag || !flag.enabled)
+                return false; // unknown or switched off
+            return isEnabledForUser(userKey, flagKey, flag.rollout);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@maksymshypytsia/flags-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Tiny client SDK for feature-flags-saas: one fetch, local evaluation.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipaM/feature-flags-sdk.git"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5",
+    "vitest": "^5.0.5"
+  }
+}