@orange-ember/easy-flags-sdk 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# Easy Flags SDK
+
+Official TypeScript SDK for the **Easy Flags** feature flag management platform. Manage features toggles, rollouts, and targeting rules with ease in your Node.js or Browser applications.
+
+## Key Features
+
+- 🚀 **Universal Support**: Works seamlessly in Node.js, Browsers, and Edge environments.
+- 🛡️ **Strongly Typed**: Full TypeScript support with generics for flag values.
+- 📉 **Smart Context**: Automatically optimizes requests (GET/POST) based on context size.
+- 🔇 **Silent Fail**: Never breaks your app – returns user-defined defaults if the service is unavailable.
+- 📦 **Modern Bundle**: Shipped in ESM and CommonJS formats.
+
+## Installation
+
+```bash
+npm install @orange-ember/easy-flags-sdk
+# or
+yarn add @orange-ember/easy-flags-sdk
+# pnpm
+pnpm add @orange-ember/easy-flags-sdk
+```
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```typescript
+import { EasyFlagsClient } from "@orange-ember/easy-flags-sdk";
+
+const client = new EasyFlagsClient({
+  apiKey: "your-api-key",
+  spaceId: "your-space-id",
+  environmentId: "your-environment-id",
+});
+```
+
+### 2. Evaluate a Flag
+
+```typescript
+// Basic boolean toggle
+const isFeatureEnabled = await client.evaluate("new-ui-v2", {
+  defaultValue: false,
+});
+
+if (isFeatureEnabled) {
+  renderNewUI();
+}
+```
+
+### 3. Using Smart Context & Generics
+
+Pass a `userId` and a custom `context` for advanced targeting and deterministic rollouts.
+
+```typescript
+const buttonColor = await client.evaluate<string>("signup-btn-color", {
+  defaultValue: "#000000",
+  userId: "user_123",
+  context: {
+    plan: "premium",
+    country: "US",
+  },
+});
+```
+
+## Advanced Configuration
+
+| Option          | Type      | Default      | Description                                      |
+| --------------- | --------- | ------------ | ------------------------------------------------ |
+| `apiKey`        | `string`  | **Required** | Your Easy Flags API Key.                         |
+| `spaceId`       | `string`  | **Required** | The ID of your Space.                            |
+| `environmentId` | `string`  | **Required** | The ID of the environment (e.g., prod, staging). |
+| `baseUrl`       | `string`  | `https://`   | Custom API base URL.                             |
+| `debug`         | `boolean` | `false`      | Enable console logging for debugging.            |
+
+## Error Handling
+
+The SDK implements a "Silent Fail" strategy. If a network request fails or the service returns an error, the `evaluate` method catch the error and return the `defaultValue` provided in the options.
+
+```typescript
+const flag = await client.evaluate("my-flag", {
+  defaultValue: "safe-value",
+});
+// result is always 'safe-value' if something goes wrong
+```
+
+## License
+
+Apache-2.0 © Orange Ember Studios

package/dist/index.d.mts

@@ -0,0 +1,26 @@
+interface EasyFlagsConfig {
+    apiKey: string;
+    spaceId: string;
+    environmentId: string;
+    baseUrl?: string;
+    debug?: boolean;
+}
+interface EvaluationOptions<T = any> {
+    userId?: string;
+    context?: Record<string, any>;
+    defaultValue: T;
+}
+interface EvaluationResult<T = any> {
+    value: T;
+    matched: boolean;
+    reason?: string;
+}
+
+declare class EasyFlagsClient {
+    private readonly config;
+    constructor(config: EasyFlagsConfig);
+    private log;
+    evaluate<T = any>(featureKey: string, options: EvaluationOptions<T>): Promise<T>;
+}
+
+export { EasyFlagsClient, type EasyFlagsConfig, type EvaluationOptions, type EvaluationResult };

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+interface EasyFlagsConfig {
+    apiKey: string;
+    spaceId: string;
+    environmentId: string;
+    baseUrl?: string;
+    debug?: boolean;
+}
+interface EvaluationOptions<T = any> {
+    userId?: string;
+    context?: Record<string, any>;
+    defaultValue: T;
+}
+interface EvaluationResult<T = any> {
+    value: T;
+    matched: boolean;
+    reason?: string;
+}
+
+declare class EasyFlagsClient {
+    private readonly config;
+    constructor(config: EasyFlagsConfig);
+    private log;
+    evaluate<T = any>(featureKey: string, options: EvaluationOptions<T>): Promise<T>;
+}
+
+export { EasyFlagsClient, type EasyFlagsConfig, type EvaluationOptions, type EvaluationResult };

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";var i=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var p=(s,e)=>{for(var t in e)i(s,t,{get:e[t],enumerable:!0})},y=(s,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of g(e))!d.call(s,a)&&a!==t&&i(s,a,{get:()=>e[a],enumerable:!(n=f(e,a))||n.enumerable});return s};var h=s=>y(i({},"__esModule",{value:!0}),s);var m={};p(m,{EasyFlagsClient:()=>l});module.exports=h(m);var l=class{constructor(e){this.config={baseUrl:"https://easy-flags.orangeember.com/api",debug:!1,...e}}log(...e){this.config.debug&&console.log("[EasyFlags]",...e)}async evaluate(e,t){try{let n=`${this.config.baseUrl}/api/features/${e}/evaluate`,a=new URLSearchParams;t.userId&&a.append("userId",t.userId),t.context&&a.append("context",JSON.stringify(t.context));let c=`${n}?${a.toString()}`,u=c.length>2048,r={headers:{"x-api-key":this.config.apiKey,"x-space-id":this.config.spaceId,"x-environment-id":this.config.environmentId,"Content-Type":"application/json"}};u?(r.method="POST",r.body=JSON.stringify({userId:t.userId,context:t.context})):r.method="GET";let o=await fetch(u?n:c,r);return o.ok?(await o.json()).value:(this.log(`Evaluation failed: ${o.status} ${o.statusText}`),t.defaultValue)}catch(n){return this.log("Evaluation error:",n),t.defaultValue}}};0&&(module.exports={EasyFlagsClient});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts"],"sourcesContent":["export * from './client'\nexport type * from './types'\n","import type { EasyFlagsConfig, EvaluationOptions, EvaluationResult } from './types'\n\nexport class EasyFlagsClient {\n  private readonly config: EasyFlagsConfig\n\n  constructor(config: EasyFlagsConfig) {\n    this.config = {\n      baseUrl: 'https://easy-flags.orangeember.com/api',\n      debug: false,\n      ...config\n    }\n  }\n\n  private log(...args: any[]) {\n    if (this.config.debug) {\n      console.log('[EasyFlags]', ...args)\n    }\n  }\n\n  async evaluate<T = any>(featureKey: string, options: EvaluationOptions<T>): Promise<T> {\n    try {\n      const baseUrl = `${this.config.baseUrl}/api/features/${featureKey}/evaluate`\n      const queryParams = new URLSearchParams()\n      if (options.userId) queryParams.append('userId', options.userId)\n      if (options.context) queryParams.append('context', JSON.stringify(options.context))\n\n      const fullUrl = `${baseUrl}?${queryParams.toString()}`\n      const isLarge = fullUrl.length > 2048\n\n      const fetchOptions: RequestInit = {\n        headers: {\n          'x-api-key': this.config.apiKey,\n          'x-space-id': this.config.spaceId,\n          'x-environment-id': this.config.environmentId,\n          'Content-Type': 'application/json'\n        }\n      }\n\n      if (isLarge) {\n        fetchOptions.method = 'POST'\n        fetchOptions.body = JSON.stringify({\n          userId: options.userId,\n          context: options.context\n        })\n      } else {\n        fetchOptions.method = 'GET'\n      }\n\n      const url = isLarge ? baseUrl : fullUrl\n      const response = await fetch(url, fetchOptions)\n\n      if (!response.ok) {\n        this.log(`Evaluation failed: ${response.status} ${response.statusText}`)\n        return options.defaultValue\n      }\n\n      const data: EvaluationResult<T> = await response.json()\n      return data.value\n    } catch (error) {\n      this.log('Evaluation error:', error)\n      return options.defaultValue\n    }\n  }\n}\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,qBAAAE,IAAA,eAAAC,EAAAH,GCEO,IAAMI,EAAN,KAAsB,CAG3B,YAAYC,EAAyB,CACnC,KAAK,OAAS,CACZ,QAAS,yCACT,MAAO,GACP,GAAGA,CACL,CACF,CAEQ,OAAOC,EAAa,CACtB,KAAK,OAAO,OACd,QAAQ,IAAI,cAAe,GAAGA,CAAI,CAEtC,CAEA,MAAM,SAAkBC,EAAoBC,EAA2C,CACrF,GAAI,CACF,IAAMC,EAAU,GAAG,KAAK,OAAO,OAAO,iBAAiBF,CAAU,YAC3DG,EAAc,IAAI,gBACpBF,EAAQ,QAAQE,EAAY,OAAO,SAAUF,EAAQ,MAAM,EAC3DA,EAAQ,SAASE,EAAY,OAAO,UAAW,KAAK,UAAUF,EAAQ,OAAO,CAAC,EAElF,IAAMG,EAAU,GAAGF,CAAO,IAAIC,EAAY,SAAS,CAAC,GAC9CE,EAAUD,EAAQ,OAAS,KAE3BE,EAA4B,CAChC,QAAS,CACP,YAAa,KAAK,OAAO,OACzB,aAAc,KAAK,OAAO,QAC1B,mBAAoB,KAAK,OAAO,cAChC,eAAgB,kBAClB,CACF,EAEID,GACFC,EAAa,OAAS,OACtBA,EAAa,KAAO,KAAK,UAAU,CACjC,OAAQL,EAAQ,OAChB,QAASA,EAAQ,OACnB,CAAC,GAEDK,EAAa,OAAS,MAIxB,IAAMC,EAAW,MAAM,MADXF,EAAUH,EAAUE,EACEE,CAAY,EAE9C,OAAKC,EAAS,IAKoB,MAAMA,EAAS,KAAK,GAC1C,OALV,KAAK,IAAI,sBAAsBA,EAAS,MAAM,IAAIA,EAAS,UAAU,EAAE,EAChEN,EAAQ,aAKnB,OAASO,EAAO,CACd,YAAK,IAAI,oBAAqBA,CAAK,EAC5BP,EAAQ,YACjB,CACF,CACF","names":["index_exports","__export","EasyFlagsClient","__toCommonJS","EasyFlagsClient","config","args","featureKey","options","baseUrl","queryParams","fullUrl","isLarge","fetchOptions","response","error"]}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+var l=class{constructor(t){this.config={baseUrl:"https://easy-flags.orangeember.com/api",debug:!1,...t}}log(...t){this.config.debug&&console.log("[EasyFlags]",...t)}async evaluate(t,e){try{let a=`${this.config.baseUrl}/api/features/${t}/evaluate`,r=new URLSearchParams;e.userId&&r.append("userId",e.userId),e.context&&r.append("context",JSON.stringify(e.context));let o=`${a}?${r.toString()}`,i=o.length>2048,s={headers:{"x-api-key":this.config.apiKey,"x-space-id":this.config.spaceId,"x-environment-id":this.config.environmentId,"Content-Type":"application/json"}};i?(s.method="POST",s.body=JSON.stringify({userId:e.userId,context:e.context})):s.method="GET";let n=await fetch(i?a:o,s);return n.ok?(await n.json()).value:(this.log(`Evaluation failed: ${n.status} ${n.statusText}`),e.defaultValue)}catch(a){return this.log("Evaluation error:",a),e.defaultValue}}};export{l as EasyFlagsClient};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type { EasyFlagsConfig, EvaluationOptions, EvaluationResult } from './types'\n\nexport class EasyFlagsClient {\n  private readonly config: EasyFlagsConfig\n\n  constructor(config: EasyFlagsConfig) {\n    this.config = {\n      baseUrl: 'https://easy-flags.orangeember.com/api',\n      debug: false,\n      ...config\n    }\n  }\n\n  private log(...args: any[]) {\n    if (this.config.debug) {\n      console.log('[EasyFlags]', ...args)\n    }\n  }\n\n  async evaluate<T = any>(featureKey: string, options: EvaluationOptions<T>): Promise<T> {\n    try {\n      const baseUrl = `${this.config.baseUrl}/api/features/${featureKey}/evaluate`\n      const queryParams = new URLSearchParams()\n      if (options.userId) queryParams.append('userId', options.userId)\n      if (options.context) queryParams.append('context', JSON.stringify(options.context))\n\n      const fullUrl = `${baseUrl}?${queryParams.toString()}`\n      const isLarge = fullUrl.length > 2048\n\n      const fetchOptions: RequestInit = {\n        headers: {\n          'x-api-key': this.config.apiKey,\n          'x-space-id': this.config.spaceId,\n          'x-environment-id': this.config.environmentId,\n          'Content-Type': 'application/json'\n        }\n      }\n\n      if (isLarge) {\n        fetchOptions.method = 'POST'\n        fetchOptions.body = JSON.stringify({\n          userId: options.userId,\n          context: options.context\n        })\n      } else {\n        fetchOptions.method = 'GET'\n      }\n\n      const url = isLarge ? baseUrl : fullUrl\n      const response = await fetch(url, fetchOptions)\n\n      if (!response.ok) {\n        this.log(`Evaluation failed: ${response.status} ${response.statusText}`)\n        return options.defaultValue\n      }\n\n      const data: EvaluationResult<T> = await response.json()\n      return data.value\n    } catch (error) {\n      this.log('Evaluation error:', error)\n      return options.defaultValue\n    }\n  }\n}\n"],"mappings":"AAEO,IAAMA,EAAN,KAAsB,CAG3B,YAAYC,EAAyB,CACnC,KAAK,OAAS,CACZ,QAAS,yCACT,MAAO,GACP,GAAGA,CACL,CACF,CAEQ,OAAOC,EAAa,CACtB,KAAK,OAAO,OACd,QAAQ,IAAI,cAAe,GAAGA,CAAI,CAEtC,CAEA,MAAM,SAAkBC,EAAoBC,EAA2C,CACrF,GAAI,CACF,IAAMC,EAAU,GAAG,KAAK,OAAO,OAAO,iBAAiBF,CAAU,YAC3DG,EAAc,IAAI,gBACpBF,EAAQ,QAAQE,EAAY,OAAO,SAAUF,EAAQ,MAAM,EAC3DA,EAAQ,SAASE,EAAY,OAAO,UAAW,KAAK,UAAUF,EAAQ,OAAO,CAAC,EAElF,IAAMG,EAAU,GAAGF,CAAO,IAAIC,EAAY,SAAS,CAAC,GAC9CE,EAAUD,EAAQ,OAAS,KAE3BE,EAA4B,CAChC,QAAS,CACP,YAAa,KAAK,OAAO,OACzB,aAAc,KAAK,OAAO,QAC1B,mBAAoB,KAAK,OAAO,cAChC,eAAgB,kBAClB,CACF,EAEID,GACFC,EAAa,OAAS,OACtBA,EAAa,KAAO,KAAK,UAAU,CACjC,OAAQL,EAAQ,OAChB,QAASA,EAAQ,OACnB,CAAC,GAEDK,EAAa,OAAS,MAIxB,IAAMC,EAAW,MAAM,MADXF,EAAUH,EAAUE,EACEE,CAAY,EAE9C,OAAKC,EAAS,IAKoB,MAAMA,EAAS,KAAK,GAC1C,OALV,KAAK,IAAI,sBAAsBA,EAAS,MAAM,IAAIA,EAAS,UAAU,EAAE,EAChEN,EAAQ,aAKnB,OAASO,EAAO,CACd,YAAK,IAAI,oBAAqBA,CAAK,EAC5BP,EAAQ,YACjB,CACF,CACF","names":["EasyFlagsClient","config","args","featureKey","options","baseUrl","queryParams","fullUrl","isLarge","fetchOptions","response","error"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@orange-ember/easy-flags-sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for Easy Flags management platform.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "sdk",
+    "typescript",
+    "javascript",
+    "node",
+    "browser",
+    "edge",
+    "orange-ember",
+    "easy-flags"
+  ],
+  "author": "Seobryn <ing.jose.joya@gmail.com>",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "eslint": "^9.39.4",
+    "eslint-config-love": "^151.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.24.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.8.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.4.5",
+    "vitest": "^4.1.2"
+  },
+  "lint-staged": {
+    "*.{js,mjs,ts}": [
+      "eslint --fix",
+      "prettier --write",
+      "vitest related --run --passWithNoTests=false"
+    ]
+  }
+}