flagmint-js-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Israel Edet
+
+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,136 @@
+# Flagmint JavaScript SDK
+
+This SDK provides a framework-agnostic client for evaluating feature flags, with pluggable caching (sync or async) and transport strategies (WebSocket or long-polling).
+
+## 📦 Installation
+
+```bash
+npm install flagmint-sdk
+# or
+yarn add flagmint-sdk
+```
+
+## 🛠️ FlagClientOptions
+
+| Option                | Type                                      | Default            | Description                                                           |
+| --------------------- | ----------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| `apiKey`              | `string`                                  | **Required**       | Your environment API key.                                             |
+| `context`             | `Record<string, any>`                     | `{}`               | Initial evaluation context (e.g. user attributes).                    |
+| `enableOfflineCache`  | `boolean`                                 | `false`             | Enable caching of flags locally.                                      |
+| `persistContext`      | `boolean`                                 | `false`            | Persist evaluation context across sessions.                           |                                        |
+| `cacheAdapter`        | `CacheAdapter<C>`                         | Sync `cacheHelper` | Custom cache implementation (see examples).                           |
+| `transportMode`       | `'auto' \| 'websocket' \| 'long-polling'` | `'auto'`           | How to fetch flags: prefer WebSocket, or use long-polling transport.  |
+| `onError`             | `(error: Error) => void`                  | —                  | Callback for transport or initialization errors.                      |
+| `previewMode`         | `boolean`                                 | `false`            | Evaluate using `rawFlags` only, bypassing remote fetch.               |
+| `rawFlags`            | `Record<string, FlagValue>`               | —                  | Local-only flag definitions used when `previewMode: true`.            |
+| `deferInitialization` | `boolean`                                 | `false`            | If `true`, client initialization is deferred until you call `init()`. |
+
+## 🔧 Cache Adapters
+
+### Sync (Browser / In-Memory)
+
+By default, the SDK uses a **sync** `localStorage`-based helper in browsers or a `Map` in Node.js:
+
+```ts
+import { FlagClient } from 'flagmint-sdk';
+// No setup needed for browser; for Node you can override:
+import { setCacheStorage } from 'flagmint-sdk/core/cacheHelper';
+setCacheStorage({
+  getItem:   key => myMap.get(key) ?? null,
+  setItem:   (key, val) => myMap.set(key, val),
+});
+```
+
+### Async (Redis / File System)
+
+Use the **async** helper for server-side or React Native:
+
+```ts
+import { FlagClient } from 'flagmint-sdk';
+import * as asyncCache from 'flagmint-sdk/core/cacheHelper.async';
+
+const client = new FlagClient({
+  apiKey: '...',
+  cacheAdapter: {
+    loadFlags:   asyncCache.loadCachedFlags,
+    saveFlags:   asyncCache.saveCachedFlags,
+    loadContext: asyncCache.loadCachedContext,
+    saveContext: asyncCache.saveCachedContext
+  }
+});
+```
+
+## 🌐 Transport Modes
+
+* **`'websocket'`**: Persistent WebSocket connection for live updates.
+* **`'long-polling'`**: HTTP requests held open by server until flags change.
+* **`'auto'`** (default): Try WebSocket, fallback to long-polling.
+
+```ts
+const client = new FlagClient({
+  apiKey: '...',
+  transportMode: 'long-polling'
+});
+```
+
+## ⚙️ Evaluation Helpers
+
+The SDK includes utilities to evaluate flag targeting rules and rollouts:
+
+### `evaluateFlagValue(flag, context)`
+
+```ts
+import { evaluateFlagValue } from 'flagmint-sdk/core/evaluation';
+
+const result = evaluateFlagValue(flagValue, userContext);
+```
+
+* Applies targeting rules (`segment` or attribute rules).
+* If matched, applies rollout (percentage or variant).
+* Returns flag’s value or `null` if not enabled.
+
+### `evaluateRollout(rollout, context)`
+
+```ts
+import { evaluateRollout } from 'flagmint-sdk/core/evaluation';
+
+const rolloutValue = evaluateRollout(rolloutConfig, userContext);
+```
+
+* Supports **percentage** rollouts using consistent hashing.
+* Supports **variant** distributions (A/B tests).
+
+### `rolloutUtils`
+
+* `hashToPercentage(value: string): number`
+* `pickVariant(value: string, variants: VariantRollout): T | null`
+
+These helpers underpin reliable, deterministic assignment of users to flag variants.
+
+## 🚀 Quick Start
+
+```ts
+import { FlagClient } from 'flagmint-sdk';
+
+const client = new FlagClient({
+  apiKey: 'ff_XXXX',
+  context: { user_id: 'user123', country: 'US' }
+});
+
+// wait until connected
+await client.ready();
+
+// get flag
+const showBanner = client.getFlag('show_banner', false);
+```
+
+## 📖 References
+
+* Core client: `@/core/client.ts`
+* Cache helpers: `@/core/helpers/cacheHelper.ts`, `asyncCacheHelper.ts`
+* Transports: `WebsocketTransport`, `LongPollingTransport`
+* Evaluation: `evaluateFlagValue`, `evaluateRollout`, `rolloutUtils`
+
+---
+
+*MIT © Flagmint Team*

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import { CacheAdapter, FeatureFlags } from '../core/helpers/types';
+import type { Transport } from '../core/transports/Transport';
+import { FlagValue } from '../core/evaluation/types';
+type TransportMode = 'auto' | 'websocket' | 'long-polling';
+export interface FlagClientOptions<C extends Record<string, any> = Record<string, any>> {
+    apiKey: string;
+    context?: C;
+    enableOfflineCache?: boolean;
+    persistContext?: boolean;
+    transport?: Transport<C, any>;
+    transportMode?: TransportMode;
+    onError?: (error: Error) => void;
+    previewMode?: boolean;
+    rawFlags?: Record<string, FlagValue>;
+    deferInitialization?: boolean;
+    cacheAdapter?: CacheAdapter<C>;
+}
+export declare class FlagClient<T = unknown, C extends Record<string, any> = Record<string, any>> {
+    private apiKey;
+    private context;
+    private flags;
+    private refreshIntervalId;
+    private enableOfflineCache;
+    private persistContext;
+    private cacheTTL;
+    private transport;
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private onError?;
+    private previewMode;
+    private rawFlags;
+    private cacheAdapter;
+    /**
+     * Creates a new FlagClient instance.
+     * @param options - Configuration options for the client.
+     */
+    constructor(options: FlagClientOptions<C>);
+    /**
+     * Initializes the client by loading cached flags and context, setting up the transport layer, and starting the auto-refresh timer if enabled.
+     * @param options - The options for initializing the client.
+     *
+     * @throws Will throw an error if initialization fails.
+     * @returns {Promise<void>} A promise that resolves when the client is ready.
+     * @private
+     */
+    private initialize;
+    /**
+     * Sets up the transport layer for the client.
+     * @param options - The options for the transport setup.
+     */
+    private setupTransport;
+    getFlag<K extends keyof FeatureFlags<T>>(key: K, fallback?: FeatureFlags<T>[K]): FeatureFlags<T>[K];
+    updateContext(context: C): void;
+    destroy(): void;
+    ready(): Promise<void>;
+    private evaluateLocally;
+}
+export {};

package/dist/evaluation/evaluateFlagValue.d.ts

@@ -0,0 +1,4 @@
+import { FlagValue, EvaluationContext, Segment } from '../../core/evaluation/types';
+export declare function evaluateFlagValue<T>(flag: FlagValue<T> & {
+    segmentsById?: Record<string, Segment>;
+}, context: EvaluationContext): T | null;

package/dist/evaluation/evaluateRollout.d.ts

@@ -0,0 +1,2 @@
+import type { Rollout, EvaluationContext } from '../../core/evaluation/types';
+export declare function evaluateRollout<T>(rollout: Rollout, context: EvaluationContext): T | null;

package/dist/evaluation/isInSegment.d.ts

@@ -0,0 +1,3 @@
+import { Segment, EvaluationContext, TargetingRule } from './types';
+export declare function evaluateRule(rule: TargetingRule, context: EvaluationContext): boolean;
+export declare function isInSegment(segment: Segment, context: EvaluationContext): boolean;

package/dist/evaluation/rolloutUtils.d.ts

@@ -0,0 +1,3 @@
+import type { VariantRollout } from './types';
+export declare function hashToPercentage(value: string): number;
+export declare function pickVariant(value: string, rollout: VariantRollout): string | number | boolean | null;

package/dist/evaluation/types.d.ts

@@ -0,0 +1,42 @@
+export type Operator = 'eq' | 'neq' | 'in' | 'nin' | 'gt' | 'lt' | 'exists' | 'not_exists';
+export interface Rule {
+    type: 'rule';
+    attribute: string;
+    operator: Operator;
+    value: string | string[];
+}
+export interface SegmentReference {
+    type: 'segment';
+    segment_id: string;
+}
+export type TargetingRule = Rule | SegmentReference;
+export interface PercentageRollout {
+    strategy: 'percentage';
+    percentage: number;
+    salt: string;
+}
+export interface VariantOption {
+    value: string | number | boolean;
+    weight: number;
+}
+export interface VariantRollout {
+    strategy: 'variant';
+    salt: string;
+    variants: VariantOption[];
+}
+export type EmptyRollout = Record<string, any>;
+export type Rollout = PercentageRollout | VariantRollout | EmptyRollout;
+export interface FlagValue<T = unknown> {
+    key?: string;
+    value: T;
+    type: 'boolean' | 'string' | 'number' | 'object';
+    targeting_rules?: TargetingRule[];
+    rollout?: Rollout;
+}
+export type EvaluationContext = Record<string, unknown>;
+export interface Segment {
+    id: string;
+    name: string;
+    description?: string;
+    rules: TargetingRule[];
+}