@maksymshypytsia/flags-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShipaM
+
+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

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @maksymshypytsia/flags-sdk
 
-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.
+[![npm version](https://img.shields.io/npm/v/@maksymshypytsia/flags-sdk.svg)](https://www.npmjs.com/package/@maksymshypytsia/flags-sdk)
+[![license](https://img.shields.io/npm/l/@maksymshypytsia/flags-sdk.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/@maksymshypytsia/flags-sdk.svg)](https://nodejs.org)
+![types](https://img.shields.io/npm/types/@maksymshypytsia/flags-sdk.svg)
+
+Tiny JavaScript/TypeScript client for [feature-flags-saas](https://github.com/ShipaM/feature-flags-saas).
+
+- **One request.** Flags are fetched once and cached in memory.
+- **Local evaluation.** `isEnabled()` is synchronous: no network, no waiting.
+- **Same answer as the server.** Uses the exact same rollout hash, so a user always lands in the same bucket.
+- **Zero runtime dependencies**, ESM, written in TypeScript (types included).
+- No polling, no WebSocket.
+
+## Installation
+
+```bash
+npm install @maksymshypytsia/flags-sdk
+```
+
+<details>
+<summary>pnpm / yarn / bun</summary>
+
+```bash
+pnpm add @maksymshypytsia/flags-sdk
+yarn add @maksymshypytsia/flags-sdk
+bun add @maksymshypytsia/flags-sdk
+```
+
+</details>
+
+**Requirements:** Node.js 18+ (or any modern browser) because the SDK uses the built-in `fetch`.
+The package is **ESM only**: use `import`, not `require`.
+
+## Quick start
+
+```ts
+import { getFlags } from "@maksymshypytsia/flags-sdk";
+
+const flags = await getFlags({
+  apiKey: process.env.FLAGS_API_KEY!, // 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
+}
+```
+
+## How to get the values
+
+| Option    | Where to get it                                                      |
+| --------- | -------------------------------------------------------------------- |
+| `apiKey`  | Dashboard -> your project -> **API keys**. Looks like `ffk_prod_...` |
+| `userKey` | Your own stable user identifier (id, email). Never random per visit  |
+| `baseUrl` | The address of your feature-flags-saas deployment, no `/api` suffix  |
+
+Each API key belongs to one environment (`dev`, `staging`, `prod`), so use a separate key per environment.
+
+## Usage
+
+### Server (Node.js, Next.js route, Express...)
+
+```ts
+import { getFlags } from "@maksymshypytsia/flags-sdk";
+
+export async function handler(userId: string) {
+  const flags = await getFlags({
+    apiKey: process.env.FLAGS_API_KEY!,
+    userKey: userId,
+    baseUrl: process.env.FLAGS_URL!,
+  });
+  return flags.isEnabled("new-checkout") ? "new" : "old";
+}
+```
+
+Calling `getFlags` for many users is cheap: the network request happens only
+once per `baseUrl` + `apiKey`, every other call reuses the cached data
+(parallel calls share the same request).
+
+### Refresh the flags
+
+Flags are **not** refreshed automatically. When you want fresh data:
+
+```ts
+import { clearCache, getFlags } from "@maksymshypytsia/flags-sdk";
+
+clearCache(); // forget what we have
+const flags = await getFlags({ apiKey, userKey, baseUrl }); // fetches again
+```
+
+### Error handling
+
+```ts
+try {
+  const flags = await getFlags({ apiKey, userKey, baseUrl });
+} catch (error) {
+  // wrong key (HTTP 401), server down, unexpected response...
+  // a failed request is never cached, the next call tries again
+}
+```
+
+A sensible pattern is to treat "could not load flags" as "all flags off".
+
+## API
+
+### `getFlags(options): Promise<FlagsClient>`
+
+| Option    | Type     | Description                                            |
+| --------- | -------- | ------------------------------------------------------ |
+| `apiKey`  | `string` | Project API key. Sent as `Authorization: Bearer <key>` |
+| `userKey` | `string` | Stable id of the end user                              |
+| `baseUrl` | `string` | Service URL. A trailing `/` is ignored                 |
+
+Throws `TypeError` if an option is empty, and `Error` if the request fails
+or the response has an unexpected shape.
+
+### `client.isEnabled(flagKey): boolean`
+
+`true` only if the flag exists, is enabled **and** the user falls inside the
+flag's rollout percentage. Unknown or disabled flags return `false`.
+Synchronous, makes no network requests, always gives the same answer for the same user and flag.
+
+### `clearCache(): void`
+
+Forgets cached flags; the next `getFlags()` fetches again.
+
+### `isEnabledForUser(userKey, flagKey, rollout): boolean`
+
+The raw rollout function the server uses. Handy for tests or for evaluating on your own server.
+
+## How it works
+
+1. `getFlags` sends one `GET {baseUrl}/api/v1/flags` with your API key.
+2. The response (`{ flags: { key: { enabled, rollout } } }`) is cached in memory.
+3. `isEnabled` computes `FNV-1a(userKey + ":" + flagKey) % 100` and compares it with the `rollout` percentage.
+   The same input always gives the same bucket, so a user does not flip between old and new.
+
+## FAQ
+
+**Can I use it in the browser?**
+Yes, if the service allows your origin (CORS). Keep in mind that an API key in
+public frontend code is visible to everyone, so do not use a key you consider secret.
+
+**Why does `require()` fail?**
+The package is ESM only. Use `import`, or `await import("@maksymshypytsia/flags-sdk")`.
+
+**Why does a user get a different result than my colleague?**
+Rollout depends on `userKey`. Make sure you pass the same stable value everywhere.
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+npm run build       # tsc -> dist/
+npm pack --dry-run  # see what goes into the package
+```
+
+Try an unpublished build in another project:
+
+```bash
+npm pack
+cd ../some-app && npm install ../feature-flags-sdk/maksymshypytsia-flags-sdk-0.1.0.tgz
+```
+
+Release: `npm version patch && git push --follow-tags && npm publish`.
+
+## License
+
+MIT

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,55 @@
 {
   "name": "@maksymshypytsia/flags-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+    "feature-flag",
+    "rollout",
+    "sdk",
+    "typescript"
+  ],
+  "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"
+  },
+  "homepage": "https://github.com/ShipaM/feature-flags-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/ShipaM/feature-flags-sdk/issues"
+  },
+  "author": "Maksym Shypytsia"
+}