@sessionsight/flags 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SessionSight
+
+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,109 @@
+# @sessionsight/flags
+
+Server-side SDK for evaluating feature flags with segment-based targeting in SessionSight.
+
+## Installation
+
+```bash
+npm install @sessionsight/flags
+```
+
+## Quick Start
+
+```typescript
+import FeatureFlags from '@sessionsight/flags';
+
+await FeatureFlags.init({
+  secretApiKey: 'sessionsight_sec_your_secret_key',
+  propertyId: 'your-property-id',
+  environment: 'production',
+});
+
+// Boolean flag
+const showBeta = FeatureFlags.getBooleanFlag('beta-ui', false);
+
+// String flag
+const bannerText = FeatureFlags.getStringFlag('banner-message', 'Welcome!');
+```
+
+## API Reference
+
+### `FeatureFlags.init(config, context?)`
+
+Initialize the SDK. Fetches flag configuration and evaluates flags. Returns a Promise that must be awaited before calling other methods.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `secretApiKey` | `string` | Yes | - | Your secret API key (`sessionsight_sec_...`) |
+| `propertyId` | `string` | Yes | - | The property ID to evaluate flags for |
+| `environment` | `string` | Yes | - | Environment name (e.g., `production`, `staging`) |
+| `apiUrl` | `string` | No | `https://api.sessionsight.com` | Custom API endpoint |
+
+The optional `context` parameter allows passing an evaluation context on init:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `userId` | `string` | Your user's ID. Used for percentage rollouts and user targeting. |
+| `visitorId` | `string` | SessionSight visitor ID. Enables segment-based targeting via `segment_match` rules. |
+| Custom properties | `string \| number \| boolean` | Any additional properties for targeting rules. |
+
+### `FeatureFlags.getBooleanFlag(key, defaultValue)`
+
+Get a boolean flag value. Returns `defaultValue` if the flag doesn't exist, is disabled, or hasn't been initialized.
+
+```typescript
+const showFeature = FeatureFlags.getBooleanFlag('new-feature', false);
+```
+
+### `FeatureFlags.getStringFlag(key, defaultValue)`
+
+Get a string flag value. Returns `defaultValue` if the flag doesn't exist, is disabled, or hasn't been initialized.
+
+```typescript
+const theme = FeatureFlags.getStringFlag('theme', 'light');
+```
+
+### `FeatureFlags.refresh(context?)`
+
+Re-evaluate flags with a new context. Use this for per-request targeting with visitor or user attributes.
+
+```typescript
+await FeatureFlags.refresh({
+  visitorId: 'visitor-uuid',
+  userId: 'user-123',
+  plan: 'enterprise',
+});
+const hasAccess = FeatureFlags.getBooleanFlag('advanced-analytics', false);
+```
+
+### `FeatureFlags.destroy()`
+
+Tear down the SDK instance. Call this during cleanup if needed.
+
+## Per-Request Targeting
+
+For web applications serving multiple users, call `refresh()` with the current user's context on each request:
+
+```typescript
+// Express middleware example
+app.use(async (req, res, next) => {
+  await FeatureFlags.refresh({
+    visitorId: req.cookies.ss_vid,
+    userId: req.user?.id,
+  });
+  next();
+});
+```
+
+The `visitorId` comes from the `ss_vid` cookie set by the Insights SDK on the frontend. Pass it to enable segment-based targeting rules configured in the SessionSight dashboard.
+
+## Authentication
+
+This SDK uses your **secret API key** (`sessionsight_sec_...`), not the public key. The secret key should only be used in server-side code. Never expose it in client-side JavaScript.
+
+## Build Outputs
+
+| File | Format | Usage |
+| --- | --- | --- |
+| `dist/index.js` | ESM | `import FeatureFlags from '@sessionsight/flags'` |
+| `dist/index.d.ts` | Types | TypeScript type definitions |

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sessionsight/flags",
+  "version": "1.0.0",
+  "description": "Feature flags SDK for SessionSight.",
+  "author": "SessionSight",
+  "license": "MIT",
+  "homepage": "https://sessionsight.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SessionSight/sdks.git",
+    "directory": "packages/flags"
+  },
+  "bugs": {
+    "url": "https://github.com/SessionSight/sdks/issues"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "sessionsight"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --format esm && bun x tsc --emitDeclarationOnly --declaration --outDir dist"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@sessionsight/sdk-shared": "workspace:*"
+  }
+}

package/src/client.ts

@@ -0,0 +1,118 @@
+import type { FeatureFlagConfig, FlagEvaluationContext, EvaluatedFlags, FlagListResult } from './types.js';
+import { normalizeApiUrl, setRegistryValue } from '@sessionsight/sdk-shared';
+
+const FETCH_TIMEOUT_MS = 10_000;
+
+function fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timer));
+}
+
+export class FeatureFlagClient {
+  private apiUrl: string;
+  private secretApiKey: string;
+  private propertyId: string;
+  private environment: string;
+  private flags: EvaluatedFlags = {};
+  private context: FlagEvaluationContext = {};
+  private initialized = false;
+
+  constructor(config: FeatureFlagConfig) {
+    if (typeof window !== 'undefined' && !('process' in globalThis)) {
+      throw new Error('@sessionsight/flags is a server-side SDK and cannot be used in the browser.');
+    }
+    if (!config.secretApiKey?.trim()) throw new Error('@sessionsight/flags: secretApiKey is required.');
+    if (!config.propertyId?.trim()) throw new Error('@sessionsight/flags: propertyId is required.');
+    if (!config.environment?.trim()) throw new Error('@sessionsight/flags: environment is required.');
+    this.secretApiKey = config.secretApiKey;
+    this.propertyId = config.propertyId;
+    this.environment = config.environment;
+    this.apiUrl = normalizeApiUrl(config.apiUrl || '');
+  }
+
+  async init(context?: FlagEvaluationContext): Promise<void> {
+    if (context) this.context = context;
+    await this.fetchFlags();
+    this.initialized = true;
+  }
+
+  getBooleanFlag(key: string, defaultValue: boolean): boolean {
+    const flag = this.flags[key];
+    if (!flag || flag.type !== 'boolean') return defaultValue;
+    return typeof flag.value === 'boolean' ? flag.value : defaultValue;
+  }
+
+  getStringFlag(key: string, defaultValue: string): string {
+    const flag = this.flags[key];
+    if (!flag || flag.type !== 'string') return defaultValue;
+    return typeof flag.value === 'string' ? flag.value : defaultValue;
+  }
+
+  async refresh(context?: FlagEvaluationContext): Promise<void> {
+    if (context) this.context = { ...this.context, ...context };
+    await this.fetchFlags();
+  }
+
+  async getFlags(): Promise<FlagListResult> {
+    try {
+      const res = await fetchWithTimeout(`${this.apiUrl}/v1/flags/list?propertyId=${encodeURIComponent(this.propertyId)}`, {
+        method: 'GET',
+        headers: { 'x-api-key': this.secretApiKey },
+      });
+
+      if (!res.ok) {
+        console.warn(`[SessionSight Flags] Failed to list flags: ${res.status}`);
+        return { flags: [] };
+      }
+
+      const data = await res.json();
+      return { flags: data.flags || [] };
+    } catch (err) {
+      console.warn('[SessionSight Flags] Failed to list flags:', err);
+      return { flags: [] };
+    }
+  }
+
+  destroy(): void {
+    this.flags = {};
+    this.context = {};
+    this.initialized = false;
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  private async fetchFlags(): Promise<void> {
+    try {
+      const res = await fetchWithTimeout(`${this.apiUrl}/v1/flags/evaluate`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.secretApiKey,
+        },
+        body: JSON.stringify({
+          propertyId: this.propertyId,
+          environment: this.environment,
+          context: this.context,
+        }),
+      });
+
+      if (!res.ok) {
+        console.warn(`[SessionSight Flags] Failed to fetch flags: ${res.status}`);
+        return;
+      }
+
+      const data = await res.json();
+      this.flags = data.flags || {};
+
+      // Write opaque evaluation token to cross-SDK registry for insights SDK to pick up
+      if (data.evaluationToken) {
+        setRegistryValue('flagEvaluationToken', data.evaluationToken);
+      }
+    } catch (err) {
+      console.warn('[SessionSight Flags] Failed to fetch flags:', err);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+import { FeatureFlagClient } from './client.js';
+import type { FeatureFlagConfig, FlagEvaluationContext } from './types.js';
+
+export { FeatureFlagClient };
+export type { FeatureFlagConfig, FlagEvaluationContext, EvaluatedFlag, EvaluatedFlags } from './types.js';
+
+let instance: FeatureFlagClient | null = null;
+
+const FeatureFlags = {
+  async init(config: FeatureFlagConfig, context?: FlagEvaluationContext): Promise<void> {
+    if (instance) {
+      console.warn('[SessionSight Flags] Already initialized. Call destroy() first.');
+      return;
+    }
+    instance = new FeatureFlagClient(config);
+    await instance.init(context);
+  },
+
+  getBooleanFlag(key: string, defaultValue: boolean): boolean {
+    if (!instance) {
+      console.warn('[SessionSight Flags] Not initialized. Call init() first.');
+      return defaultValue;
+    }
+    return instance.getBooleanFlag(key, defaultValue);
+  },
+
+  getStringFlag(key: string, defaultValue: string): string {
+    if (!instance) {
+      console.warn('[SessionSight Flags] Not initialized. Call init() first.');
+      return defaultValue;
+    }
+    return instance.getStringFlag(key, defaultValue);
+  },
+
+  async refresh(context?: FlagEvaluationContext): Promise<void> {
+    if (!instance) {
+      console.warn('[SessionSight Flags] Not initialized. Call init() first.');
+      return;
+    }
+    await instance.refresh(context);
+  },
+
+  destroy(): void {
+    if (instance) {
+      instance.destroy();
+      instance = null;
+    }
+  },
+};
+
+export default FeatureFlags;

package/src/types.ts

@@ -0,0 +1,36 @@
+export interface FeatureFlagConfig {
+  secretApiKey: string;
+  propertyId: string;
+  environment: string;
+  apiUrl?: string;
+}
+
+export interface FlagEvaluationContext {
+  userId?: string;
+  /** Set visitorId to enable segment-based targeting via segment_match rules */
+  visitorId?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface EvaluatedFlag {
+  value: string | boolean;
+  type: 'boolean' | 'string';
+}
+
+export interface EvaluatedFlags {
+  [flagKey: string]: EvaluatedFlag;
+}
+
+export interface FlagDefinition {
+  id: string;
+  key: string;
+  name: string;
+  description?: string;
+  type: 'boolean' | 'string';
+  defaultValue: string | boolean;
+  createdAt: number;
+}
+
+export interface FlagListResult {
+  flags: FlagDefinition[];
+}

package/test/client.test.ts

@@ -0,0 +1,215 @@
+import { test, expect, describe, beforeEach, mock } from 'bun:test';
+import { FeatureFlagClient } from '../src/client';
+
+// Mock global fetch
+const mockFetch = mock(() => Promise.resolve(new Response()));
+
+globalThis.fetch = mockFetch as any;
+
+function mockFetchResponse(data: any, status = 200) {
+  mockFetch.mockResolvedValue(new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  }));
+}
+
+describe('FeatureFlagClient', () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  test('init fetches flags and marks as initialized', async () => {
+    mockFetchResponse({
+      flags: {
+        'dark-mode': { value: true, type: 'boolean' },
+        'variant': { value: 'b', type: 'string' },
+      },
+    });
+
+    const client = new FeatureFlagClient({
+      secretApiKey: 'test-key',
+      environment: 'production',
+      propertyId: 'test-prop',
+      apiUrl: 'http://localhost:3001',
+    });
+
+    expect(client.isInitialized()).toBe(false);
+    await client.init({ userId: 'u1' });
+    expect(client.isInitialized()).toBe(true);
+
+    // Verify fetch was called correctly
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, opts] = mockFetch.mock.calls[0] as any[];
+    expect(url).toBe('http://localhost:3001/v1/flags/evaluate');
+    expect(opts.method).toBe('POST');
+    expect(opts.headers['x-api-key']).toBe('test-key');
+    const body = JSON.parse(opts.body);
+    expect(body.environment).toBe('production');
+    expect(body.context.userId).toBe('u1');
+  });
+
+  test('getBooleanFlag returns value when type matches', async () => {
+    mockFetchResponse({
+      flags: { 'dark-mode': { value: true, type: 'boolean' } },
+    });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getBooleanFlag('dark-mode', false)).toBe(true);
+  });
+
+  test('getBooleanFlag returns default when flag missing', async () => {
+    mockFetchResponse({ flags: {} });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getBooleanFlag('missing', false)).toBe(false);
+  });
+
+  test('getBooleanFlag returns default when type is string', async () => {
+    mockFetchResponse({
+      flags: { 'variant': { value: 'a', type: 'string' } },
+    });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getBooleanFlag('variant', false)).toBe(false);
+  });
+
+  test('getStringFlag returns value when type matches', async () => {
+    mockFetchResponse({
+      flags: { 'variant': { value: 'checkout-b', type: 'string' } },
+    });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getStringFlag('variant', 'control')).toBe('checkout-b');
+  });
+
+  test('getStringFlag returns default when flag missing', async () => {
+    mockFetchResponse({ flags: {} });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getStringFlag('missing', 'default')).toBe('default');
+  });
+
+  test('getStringFlag returns default when type is boolean', async () => {
+    mockFetchResponse({
+      flags: { 'toggle': { value: true, type: 'boolean' } },
+    });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getStringFlag('toggle', 'fallback')).toBe('fallback');
+  });
+
+  test('refresh re-fetches flags with updated context', async () => {
+    mockFetchResponse({ flags: { 'f': { value: false, type: 'boolean' } } });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init({ userId: 'u1' });
+
+    mockFetchResponse({ flags: { 'f': { value: true, type: 'boolean' } } });
+    await client.refresh({ userId: 'u2' });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(client.getBooleanFlag('f', false)).toBe(true);
+
+    // Verify second call has updated context
+    const [, opts] = mockFetch.mock.calls[1] as any[];
+    const body = JSON.parse(opts.body);
+    expect(body.context.userId).toBe('u2');
+  });
+
+  test('destroy clears state', async () => {
+    mockFetchResponse({ flags: { 'f': { value: true, type: 'boolean' } } });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init();
+
+    expect(client.getBooleanFlag('f', false)).toBe(true);
+    expect(client.isInitialized()).toBe(true);
+
+    client.destroy();
+
+    expect(client.isInitialized()).toBe(false);
+    expect(client.getBooleanFlag('f', false)).toBe(false);
+  });
+
+  test('handles fetch failure gracefully', async () => {
+    mockFetch.mockRejectedValue(new Error('network error'));
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init(); // should not throw
+
+    // Returns defaults since no flags were loaded
+    expect(client.getBooleanFlag('anything', true)).toBe(true);
+  });
+
+  test('handles non-ok response gracefully', async () => {
+    mockFetch.mockResolvedValue(new Response('', { status: 500 }));
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001' });
+    await client.init(); // should not throw
+
+    expect(client.getStringFlag('anything', 'default')).toBe('default');
+  });
+
+  test('strips trailing slash from apiUrl', async () => {
+    mockFetchResponse({ flags: {} });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop', apiUrl: 'http://localhost:3001/' });
+    await client.init();
+
+    const [url] = mockFetch.mock.calls[0] as any[];
+    expect(url).toBe('http://localhost:3001/v1/flags/evaluate');
+  });
+
+  test('getFlags returns flag definitions', async () => {
+    const flagsData = {
+      flags: [
+        { id: 'f1', key: 'dark-mode', name: 'Dark Mode', type: 'boolean', defaultValue: false, createdAt: 1000 },
+        { id: 'f2', key: 'cta-color', name: 'CTA Color', type: 'string', defaultValue: 'blue', createdAt: 2000 },
+      ],
+    };
+    mockFetchResponse(flagsData);
+
+    const client = new FeatureFlagClient({ secretApiKey: 'test-key', environment: 'prod', propertyId: 'prop-1', apiUrl: 'http://localhost:3001' });
+    const result = await client.getFlags();
+
+    expect(result.flags).toHaveLength(2);
+    expect(result.flags[0].key).toBe('dark-mode');
+    expect(result.flags[1].key).toBe('cta-color');
+
+    const [url, opts] = mockFetch.mock.calls[0] as any[];
+    expect(url).toBe('http://localhost:3001/v1/flags/list?propertyId=prop-1');
+    expect(opts.method).toBe('GET');
+    expect(opts.headers['x-api-key']).toBe('test-key');
+  });
+
+  test('getFlags returns empty array on failure', async () => {
+    mockFetch.mockRejectedValue(new Error('network error'));
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'p1', apiUrl: 'http://localhost:3001' });
+    const result = await client.getFlags();
+
+    expect(result.flags).toEqual([]);
+  });
+
+  test('defaults apiUrl to production', async () => {
+    mockFetchResponse({ flags: {} });
+
+    const client = new FeatureFlagClient({ secretApiKey: 'k', environment: 'prod', propertyId: 'test-prop' });
+    await client.init();
+
+    const [url] = mockFetch.mock.calls[0] as any[];
+    expect(url).toBe('https://api.sessionsight.com/v1/flags/evaluate');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "noEmit": false,
+    "rootDir": "./src",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*.ts"]
+}