@rollercoders/flagforge-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rollercoders
+
+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,62 @@
+# flagforge-node
+
+Node.js client for FlagForge feature flags. Read-only, zero dependencies, uses native `fetch` (Node 18+).
+
+## Installation
+
+```bash
+npm install flagforge-node
+```
+
+## Usage
+
+```typescript
+import { FlagForgeClient } from 'flagforge-node';
+
+const client = new FlagForgeClient({
+  host:    'https://flagforge.myapp.com',
+  apiKey:  'ff_xxxx',
+  timeout: 5000, // ms, optional — default: 5000
+});
+
+// Single flag — throws FlagForgeError on error
+const enabled = await client.isEnabled('new-dashboard', {
+  userId:     'user-123',
+  attributes: { plan: 'premium' },
+});
+
+// Single flag — returns false on error (no exception)
+const safe = await client.isEnabledSafe('new-dashboard', { userId: 'user-123' });
+
+// Subset of flags
+const results = await client.evaluateMany(['flag-a', 'flag-b'], { userId: 'user-123' });
+// { 'flag-a': true, 'flag-b': false }
+
+// All flags for the environment
+const all = await client.evaluateAll({ userId: 'user-123' });
+```
+
+## Error Handling
+
+All methods except `isEnabledSafe` throw `FlagForgeError` on:
+- Network errors
+- Non-2xx HTTP responses
+- Invalid JSON responses
+- Timeout
+
+```typescript
+import { FlagForgeError } from 'flagforge-node';
+
+try {
+  const enabled = await client.isEnabled('my-flag');
+} catch (err) {
+  if (err instanceof FlagForgeError) {
+    console.error('Flag evaluation failed:', err.message);
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- FlagForge server with `POST /api/evaluate/all` endpoint

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+export declare class FlagForgeError extends Error {
+    constructor(message: string);
+}
+export interface FlagForgeClientOptions {
+    host: string;
+    apiKey: string;
+    timeout?: number;
+}
+export interface EvaluationContext {
+    userId?: string;
+    attributes?: Record<string, unknown>;
+}
+export type FlagResults = Record<string, boolean>;
+export declare class FlagForgeClient {
+    private readonly host;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(options: FlagForgeClientOptions);
+    evaluateAll(context?: EvaluationContext): Promise<FlagResults>;
+    isEnabled(flagKey: string, context?: EvaluationContext): Promise<boolean>;
+    isEnabledSafe(flagKey: string, context?: EvaluationContext): Promise<boolean>;
+    evaluateMany(flagKeys: string[], context?: EvaluationContext): Promise<FlagResults>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,sBAAsB;IAMrC,WAAW,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC;IAyClE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjF,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC;CAI9F"}

package/dist/client.js

@@ -0,0 +1,69 @@
+export class FlagForgeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FlagForgeError';
+    }
+}
+export class FlagForgeClient {
+    host;
+    apiKey;
+    timeout;
+    constructor(options) {
+        this.host = options.host.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout ?? 5000;
+    }
+    async evaluateAll(context = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        let response;
+        try {
+            response = await fetch(`${this.host}/api/evaluate/all`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(context),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new FlagForgeError(err instanceof Error ? err.message : 'Network error');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw new FlagForgeError(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        let data;
+        try {
+            data = await response.json();
+        }
+        catch {
+            throw new FlagForgeError('Invalid JSON response');
+        }
+        if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+            throw new FlagForgeError('Invalid JSON response');
+        }
+        return data;
+    }
+    async isEnabled(flagKey, context = {}) {
+        const results = await this.evaluateAll(context);
+        return results[flagKey] === true;
+    }
+    async isEnabledSafe(flagKey, context = {}) {
+        try {
+            return await this.isEnabled(flagKey, context);
+        }
+        catch {
+            return false;
+        }
+    }
+    async evaluateMany(flagKeys, context = {}) {
+        const all = await this.evaluateAll(context);
+        return Object.fromEntries(flagKeys.map((k) => [k, all[k] === true]));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FlagForgeClient, FlagForgeError } from './client.js';
+export type { FlagForgeClientOptions, EvaluationContext, FlagResults } from './client.js';
+//# 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,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FlagForgeClient, FlagForgeError } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@rollercoders/flagforge-node",
+  "version": "0.1.0",
+  "description": "Node.js client for FlagForge feature flagging",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "yarn@4.13.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vitest": "^1"
+  }
+}