@togglely/sdk-core 1.1.11 → 1.2.0

package/README.md

@@ -1,8 +1,15 @@
-# @togglely/sdk-core
+# Togglely Core SDK
 
-Core SDK for Togglely - Framework agnostic feature toggles.
+Framework-agnostic core SDK for [Togglely](https://togglely.io) feature flag management with offline support and multi-brand/tenant capabilities.
 
-No automatic polling - fetch once on init (configurable) and refresh manually or use WebSockets.
+## Features
+
+- 🚀 **Real-time flag evaluation** - Fetch flags from your Togglely instance
+- 💾 **Offline-first support** - JSON file, environment variables, or inline fallback
+- 🏢 **Multi-brand/tenant** - Support for multi-tenant projects
+- 🔒 **Type-safe** - Full TypeScript support
+- ⚡ **Lightweight** - Minimal bundle size
+- 🔧 **CLI tool** - Build-time JSON generation for offline deployment
 
 ## Installation
 
@@ -10,89 +17,275 @@ No automatic polling - fetch once on init (configurable) and refresh manually or
 npm install @togglely/sdk-core
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { TogglelyClient } from '@togglely/sdk-core';
 
 const client = new TogglelyClient({
   apiKey: 'your-api-key',
+  project: 'my-project',
   environment: 'production',
-  baseUrl: 'https://your-togglely-instance.com'
+  baseUrl: 'https://togglely.io',
 });
 
-// Check if feature is enabled
-const isEnabled = await client.isEnabled('new-feature', false);
+// Check if a feature is enabled
+const isEnabled = await client.isEnabled('new-feature');
+if (isEnabled) {
+  // Show new feature
+}
+
+// Get typed values
+const message = await client.getString('welcome-message', 'Hello!');
+const timeout = await client.getNumber('api-timeout', 5000);
+const config = await client.getJSON('app-config', { theme: 'dark' });
+```
 
-// Get string value
-const message = await client.getString('welcome-message', 'Hello');
+## Configuration
+
+```typescript
+interface TogglelyConfig {
+  apiKey: string;           // Your API key from Togglely dashboard
+  project: string;          // Project key
+  environment: string;      // Environment key (e.g., 'development', 'production')
+  baseUrl: string;          // Your Togglely instance URL
+  timeout?: number;         // Request timeout in ms (default: 5000)
+  offlineFallback?: boolean; // Enable offline fallback (default: true)
+  offlineJsonPath?: string; // Path to offline JSON file
+  offlineToggles?: object;  // Inline offline toggles
+  brandKey?: string;        // Brand key for multi-brand projects
+  tenantId?: string;        // Tenant ID (alias for brandKey)
+  context?: object;         // Initial targeting context
+}
+```
 
-// Get number value
-const limit = await client.getNumber('max-items', 10);
+## Multi-Brand / Multi-Tenant Support
 
-// Get JSON value
-const config = await client.getJSON('app-config', {});
+For projects with multiple brands or tenants:
 
-// Set context (useful for multi-tenant and targeting)
-client.setContext({ 
-  userId: 'user-123', 
-  tenantId: 'customer-abc', 
-  plan: 'premium' 
+```typescript
+const client = new TogglelyClient({
+  apiKey: 'your-api-key',
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  tenantId: 'brand-a',  // or brandKey: 'brand-a'
 });
+```
+
+## Offline Fallback
+
+The SDK supports multiple offline fallback methods (in priority order):
 
-// Flags will now be evaluated against this context
-const isPremiumFeature = await client.isEnabled('premium-feature', false);
+### 1. Inline Toggles (Config)
 
-// Listen to events
-client.on('ready', () => console.log('Toggles loaded!'));
-client.on('offline', () => console.log('Using offline toggles'));
+```typescript
+const client = new TogglelyClient({
+  apiKey: 'your-api-key',
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  offlineToggles: {
+    'new-feature': { value: true, enabled: true },
+    'api-timeout': { value: 5000, enabled: true, flagType: 'NUMBER' },
+  },
+});
 ```
 
-## Offline Mode
+### 2. JSON File
 
-The SDK automatically falls back to environment variables when the service is unavailable.
+Generate a JSON file at build time (see CLI section below):
+
+```typescript
+const client = new TogglelyClient({
+  apiKey: 'your-api-key',
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  offlineJsonPath: '/toggles.json',  // Will be fetched if API fails
+});
+```
 
-### Environment Variables
+### 3. Environment Variables (Node.js)
 
 ```bash
 TOGGLELY_NEW_FEATURE=true
-TOGGLELY_MAX_ITEMS=100
+TOGGLELY_API_TIMEOUT=5000
+```
+
+```typescript
+const client = new TogglelyClient({
+  apiKey: 'your-api-key',
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  envPrefix: 'TOGGLELY_',  // Default prefix
+});
 ```
 
-### Browser Global
+### 4. Window Object (Browser)
 
 ```html
 <script>
   window.__TOGGLELY_TOGGLES = {
-    'new-feature': true,
-    'max-items': 100
+    'new-feature': { value: true, enabled: true },
+    'api-timeout': { value: 5000, enabled: true },
   };
 </script>
 ```
 
-## API
+## Build-Time JSON Generation (CLI)
+
+Install the CLI tool globally or use npx:
+
+```bash
+# Install globally
+npm install -g @togglely/sdk-core
+
+# Or use with npx
+npx @togglely/sdk-core togglely-pull --apiKey=xxx --project=xxx --environment=xxx
+```
+
+### CLI Usage
+
+```bash
+# Basic usage
+togglely-pull \
+  --apiKey=tk_your_api_key \
+  --project=my-project \
+  --environment=production \
+  --output=./public/toggles.json
+
+# With tenant/brand
+togglely-pull \
+  --apiKey=tk_your_api_key \
+  --project=my-project \
+  --environment=production \
+  --tenantId=brand-a \
+  --output=./toggles.json
+
+# Different output formats
+togglely-pull --format=json  # JSON file (default)
+togglely-pull --format=env   # .env file
+togglely-pull --format=js    # JavaScript module
+
+# Using environment variables
+export TOGGLELY_APIKEY=tk_your_api_key
+export TOGGLELY_PROJECT=my-project
+export TOGGLELY_ENVIRONMENT=production
+togglely-pull --output=./toggles.json
+
+# Using config file
+togglely-pull --config=./togglely.config.js
+```
+
+### Config File (togglely.config.js)
+
+```javascript
+module.exports = {
+  apiKey: process.env.TOGGLELY_APIKEY,
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  tenantId: process.env.BRAND_KEY,
+  output: './public/toggles.json',
+  format: 'json',
+};
+```
+
+### Build Script Integration
+
+Add to your build process:
+
+```json
+{
+  "scripts": {
+    "build": "togglely-pull && vite build",
+    "build:staging": "togglely-pull --environment=staging && vite build",
+    "build:prod": "togglely-pull --environment=production && vite build"
+  }
+}
+```
+
+## Targeting Context
+
+Set user context for advanced targeting rules:
+
+```typescript
+const client = new TogglelyClient({
+  apiKey: 'your-api-key',
+  project: 'my-project',
+  environment: 'production',
+  baseUrl: 'https://togglely.io',
+  context: {
+    userId: 'user-123',
+    email: 'user@example.com',
+    country: 'DE',
+    region: 'EU',
+  },
+});
+
+// Or update context later
+client.setContext({
+  userId: 'user-456',
+  country: 'US',
+});
+```
+
+## Events
+
+Listen to SDK events:
+
+```typescript
+// When flags are first loaded
+client.on('ready', (state) => {
+  console.log('Togglely is ready!');
+});
+
+// When flags are updated
+client.on('update', (state) => {
+  console.log('Flags updated!');
+});
 
-### `TogglelyClient(config)`
+// When going offline
+client.on('offline', (state) => {
+  console.log('Using offline mode');
+});
 
-Creates a new Togglely client.
+// When coming back online
+client.on('online', (state) => {
+  console.log('Back online!');
+});
+
+// On error
+client.on('error', (state) => {
+  console.error('Error:', state.lastError);
+});
+```
 
-**Config options:**
-- `apiKey` (string, required): Your API key
-- `environment` (string, required): Environment name
-- `baseUrl` (string, required): Togglely instance URL
-- `timeout` (number, default: 5000): Request timeout in ms
-- `offlineFallback` (boolean, default: true): Enable offline mode
-- `envPrefix` (string, default: 'TOGGLELY_'): Environment variable prefix
-- `autoFetch` (boolean, default: true): Fetch toggles on init
+## API Reference
 
 ### Methods
 
-- `isEnabled(key, defaultValue)`: Check if a boolean toggle is enabled
-- `getString(key, defaultValue)`: Get a string toggle value
-- `getNumber(key, defaultValue)`: Get a number toggle value
-- `getJSON(key, defaultValue)`: Get a JSON toggle value
-- `getAllToggles()`: Get all toggles
-- `setContext(context)`: Set evaluation context (userId, email, etc.)
-- `refresh()`: Manually refresh toggles
-- `destroy()`: Cleanup resources
-- `on(event, handler)`: Listen to events ('ready', 'update', 'error', 'offline', 'online')
+- `isEnabled(key, defaultValue?)` - Check boolean flag
+- `getString(key, defaultValue?)` - Get string value
+- `getNumber(key, defaultValue?)` - Get number value
+- `getJSON(key, defaultValue?)` - Get JSON value
+- `getValue(key)` - Get raw toggle value
+- `getAllToggles()` - Get all cached toggles
+- `setContext(context)` - Set targeting context
+- `getContext()` - Get current context
+- `refresh()` - Manually refresh flags
+- `on(event, handler)` - Subscribe to events
+- `off(event, handler)` - Unsubscribe from events
+- `destroy()` - Cleanup
+
+### State
+
+- `isReady()` - Check if initial load completed
+- `isOffline()` - Check if in offline mode
+- `getState()` - Get full state object
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Togglely CLI - Build-time JSON generator
+ *
+ * Usage:
+ *   togglely-pull --apiKey=xxx --project=xxx --environment=xxx --output=./toggles.json
+ *   togglely-pull --config=./togglely.config.js
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG"}

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Togglely CLI - Build-time JSON generator
+ *
+ * Usage:
+ *   togglely-pull --apiKey=xxx --project=xxx --environment=xxx --output=./toggles.json
+ *   togglely-pull --config=./togglely.config.js
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const config = {};
+    for (const arg of args) {
+        if (arg.startsWith('--apiKey=')) {
+            config.apiKey = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--project=')) {
+            config.project = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--environment=')) {
+            config.environment = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--baseUrl=')) {
+            config.baseUrl = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--tenantId=')) {
+            config.tenantId = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--output=')) {
+            config.output = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--format=')) {
+            config.format = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--config=')) {
+            const configPath = arg.split('=')[1];
+            if (fs.existsSync(configPath)) {
+                const fileConfig = require(path.resolve(configPath));
+                Object.assign(config, fileConfig);
+            }
+            else {
+                console.error(`Config file not found: ${configPath}`);
+                process.exit(1);
+            }
+        }
+    }
+    return config;
+}
+function loadEnvFile() {
+    const envConfig = {};
+    // Try to load from .env file
+    const envPaths = ['.env', '.env.local', '.env.production', '.env.development'];
+    for (const envPath of envPaths) {
+        if (fs.existsSync(envPath)) {
+            const content = fs.readFileSync(envPath, 'utf-8');
+            const lines = content.split('\n');
+            for (const line of lines) {
+                const match = line.match(/^TOGGLELY_(\w+)=(.+)$/);
+                if (match) {
+                    const key = match[1].toLowerCase();
+                    const value = match[2].replace(/^["']|["']$/g, '');
+                    if (key === 'apikey')
+                        envConfig.apiKey = value;
+                    if (key === 'project')
+                        envConfig.project = value;
+                    if (key === 'environment')
+                        envConfig.environment = value;
+                    if (key === 'baseurl')
+                        envConfig.baseUrl = value;
+                    if (key === 'tenantid')
+                        envConfig.tenantId = value;
+                }
+            }
+        }
+    }
+    return envConfig;
+}
+async function fetchToggles(config) {
+    const params = new URLSearchParams();
+    params.set('apiKey', config.apiKey);
+    if (config.tenantId)
+        params.set('tenantId', config.tenantId);
+    const url = `${config.baseUrl}/sdk/flags/${config.project}/${config.environment}?${params.toString()}`;
+    console.log(`Fetching toggles from: ${url.replace(config.apiKey, '***')}`);
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return response.json();
+}
+function generateOutput(data, format) {
+    switch (format) {
+        case 'env':
+            return Object.entries(data)
+                .map(([key, value]) => {
+                const envKey = `TOGGLELY_${key.toUpperCase().replace(/-/g, '_')}`;
+                const envValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+                return `${envKey}=${envValue}`;
+            })
+                .join('\n');
+        case 'js':
+            return `// Auto-generated by Togglely CLI
+module.exports = ${JSON.stringify(data, null, 2)};
+`;
+        case 'json':
+        default:
+            return JSON.stringify(data, null, 2);
+    }
+}
+async function main() {
+    console.log('🚀 Togglely CLI - Build-time JSON Generator\n');
+    const argsConfig = parseArgs();
+    const envConfig = loadEnvFile();
+    // Merge configs (args > env > defaults)
+    const config = {
+        baseUrl: 'https://togglely.io',
+        output: './togglely-toggles.json',
+        format: 'json',
+        ...envConfig,
+        ...argsConfig,
+    };
+    // Validate required fields
+    if (!config.apiKey || !config.project || !config.environment) {
+        console.error('❌ Missing required parameters:');
+        console.error('   --apiKey=<key>');
+        console.error('   --project=<project-key>');
+        console.error('   --environment=<environment-key>');
+        console.error('\nOr use environment variables:');
+        console.error('   TOGGLELY_APIKEY, TOGGLELY_PROJECT, TOGGLELY_ENVIRONMENT');
+        console.error('\nOr use a config file:');
+        console.error('   --config=./togglely.config.js');
+        process.exit(1);
+    }
+    try {
+        const data = await fetchToggles(config);
+        const output = generateOutput(data, config.format);
+        // Ensure directory exists
+        const dir = path.dirname(config.output);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(config.output, output);
+        console.log(`✅ Successfully saved ${Object.keys(data).length} toggles to: ${config.output}`);
+        console.log(`\nToggles found:`);
+        Object.entries(data).forEach(([key, value]) => {
+            const status = value.enabled ? '✅' : '❌';
+            console.log(`   ${status} ${key}: ${JSON.stringify(value.value)}`);
+        });
+    }
+    catch (error) {
+        console.error(`❌ Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAY7B,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAuB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAwB,CAAC;QAC3D,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACvC,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;gBACrD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,0BAA0B,UAAU,EAAE,CAAC,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW;IAClB,MAAM,SAAS,GAAuB,EAAE,CAAC;IAEzC,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,CAAC,CAAC;IAE/E,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;gBAClD,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;oBACnC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;oBAEnD,IAAI,GAAG,KAAK,QAAQ;wBAAE,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC;oBAC/C,IAAI,GAAG,KAAK,SAAS;wBAAE,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;oBACjD,IAAI,GAAG,KAAK,aAAa;wBAAE,SAAS,CAAC,WAAW,GAAG,KAAK,CAAC;oBACzD,IAAI,GAAG,KAAK,SAAS;wBAAE,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;oBACjD,IAAI,GAAG,KAAK,UAAU;wBAAE,SAAS,CAAC,QAAQ,GAAG,KAAK,CAAC;gBACrD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,MAAiB;IAC3C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,MAAM,CAAC,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE7D,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,OAAO,cAAc,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IAEvG,OAAO,CAAC,GAAG,CAAC,0BAA0B,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IAE3E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,SAAS,cAAc,CAAC,IAAyB,EAAE,MAA2B;IAC5E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;iBACxB,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBACpB,MAAM,MAAM,GAAG,YAAY,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;gBAClE,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnF,OAAO,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC;YACjC,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhB,KAAK,IAAI;YACP,OAAO;mBACM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;CAC/C,CAAC;QAEE,KAAK,MAAM,CAAC;QACZ;YACE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;IAE7D,MAAM,UAAU,GAAG,SAAS,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,WAAW,EAAE,CAAC;IAEhC,wCAAwC;IACxC,MAAM,MAAM,GAAc;QACxB,OAAO,EAAE,qBAAqB;QAC9B,MAAM,EAAE,yBAAyB;QACjC,MAAM,EAAE,MAAM;QACd,GAAG,SAAS;QACZ,GAAG,UAAU;KACD,CAAC;IAEf,2BAA2B;IAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAC7D,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACnC,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACpD,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACjD,OAAO,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC5E,OAAO,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACzC,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAEnD,0BAA0B;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;QAED,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAExC,OAAO,CAAC,GAAG,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,gBAAgB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7F,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAChC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAgB,EAAE,EAAE;YAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YACzC,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IAEL,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,12 @@
 /**
- * Togglely Core SDK - Framework agnostic
+ * Togglely Core SDK - Framework agnostic feature flag management
  *
- * Supports offline fallback via environment variables
+ * Features:
+ * - Real-time feature flag evaluation
+ * - Offline fallback via JSON file, environment variables, or window object
+ * - Multi-brand/tenant support
+ * - Type-safe flag access
+ * - Build-time JSON generation for offline-first deployment
  */
 export interface TogglelyConfig {
     /** API Key from your Togglely dashboard */
@@ -14,8 +19,12 @@ export interface TogglelyConfig {
     baseUrl: string;
     /** Request timeout in milliseconds (default: 5000) */
     timeout?: number;
-    /** Enable offline mode fallback via environment variables (default: true) */
+    /** Enable offline fallback (default: true) */
     offlineFallback?: boolean;
+    /** Path to offline JSON file for fallback (optional) */
+    offlineJsonPath?: string;
+    /** Inline offline toggles data (optional) */
+    offlineToggles?: Record<string, ToggleValue>;
     /** Prefix for environment variables (default: 'TOGGLELY_') */
     envPrefix?: string;
     /** Auto-fetch toggles on init (default: true) */
@@ -37,6 +46,7 @@ export interface ToggleContext {
 export interface ToggleValue {
     value: any;
     enabled: boolean;
+    flagType?: 'BOOLEAN' | 'STRING' | 'NUMBER' | 'JSON';
 }
 export interface AllTogglesResponse {
     [key: string]: ToggleValue;
@@ -49,9 +59,6 @@ export interface TogglelyState {
 }
 export type TogglelyEventType = 'ready' | 'update' | 'error' | 'offline' | 'online';
 export type TogglelyEventHandler = (state: TogglelyState) => void;
-/**
- * Core Togglely Client
- */
 export declare class TogglelyClient {
     private config;
     private toggles;
@@ -69,19 +76,62 @@ export declare class TogglelyClient {
     getState(): TogglelyState;
     isReady(): boolean;
     isOffline(): boolean;
+    /**
+     * Check if a boolean feature flag is enabled
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag not found
+     * @returns Promise<boolean>
+     */
     isEnabled(key: string, defaultValue?: boolean): Promise<boolean>;
+    /**
+     * Get a string feature flag value
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag not found or disabled
+     * @returns Promise<string>
+     */
     getString(key: string, defaultValue?: string): Promise<string>;
+    /**
+     * Get a number feature flag value
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag not found or disabled
+     * @returns Promise<number>
+     */
     getNumber(key: string, defaultValue?: number): Promise<number>;
+    /**
+     * Get a JSON feature flag value
+     * @param key - The flag key
+     * @param defaultValue - Default value if flag not found or disabled
+     * @returns Promise<T>
+     */
     getJSON<T = any>(key: string, defaultValue?: T): Promise<T>;
+    /**
+     * Get raw toggle value
+     * @param key - The flag key
+     * @returns Promise<ToggleValue | null>
+     */
     getValue(key: string): Promise<ToggleValue | null>;
+    /**
+     * Get all toggles
+     * @returns Record<string, ToggleValue>
+     */
     getAllToggles(): Record<string, ToggleValue>;
     /**
-     * Load toggles from environment variables
-     * Format: TOGGLELY_<TOGGLE_KEY>=<value> or TOGGLELY_<TOGGLE_KEY>_ENABLED=true
+     * Load offline toggles from multiple sources (in priority order):
+     * 1. Inline offlineToggles from config
+     * 2. JSON file (if offlineJsonPath is set)
+     * 3. window.__TOGGLELY_TOGGLES (browser)
+     * 4. Environment variables (Node.js)
      */
     private loadOfflineToggles;
+    /**
+     * Load offline toggles from JSON file (async)
+     */
+    private loadOfflineJsonFile;
     private getOfflineToggle;
     private parseOfflineValue;
+    /**
+     * Refresh all toggles from the server
+     */
     refresh(): Promise<void>;
     forceOfflineMode(): void;
     forceOnlineMode(): void;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,GAAG,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;CACrD;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AACpF,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAIlE,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAMZ;IACF,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,KAAK,CAKX;IACF,OAAO,CAAC,aAAa,CAAgE;IACrF,OAAO,CAAC,oBAAoB,CAAkB;gBAElC,MAAM,EAAE,cAAc;IA0ClC,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAQvE,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAOlE,OAAO,CAAC,IAAI;IASZ,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAIxC,UAAU,IAAI,aAAa;IAI3B,YAAY,IAAI,IAAI;IAMpB,QAAQ,IAAI,aAAa;IAIzB,OAAO,IAAI,OAAO;IAIlB,SAAS,IAAI,OAAO;IAMpB;;;;;OAKG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAU7E;;;;;OAKG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAMxE;;;;;OAKG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAMvE;;;;;OAKG;IACG,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,CAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAe1E;;;;OAIG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAsDxD;;;OAGG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAU5C;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAiD1B;;OAEG;YACW,mBAAmB;IAiCjC,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAuD9B,gBAAgB,IAAI,IAAI;IAKxB,eAAe,IAAI,IAAI;IAQvB,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,gBAAgB;CAiBzB;AAID;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAE/E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,MAAM,GAAE,MAAoB,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAGD,eAAe,cAAc,CAAC"}