@toglio/js 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,235 @@
+# @toglio/js
+
+[![npm version](https://img.shields.io/npm/v/@toglio/js)](https://www.npmjs.com/package/@toglio/js)
+[![license](https://img.shields.io/npm/l/@toglio/js)](https://github.com/rbragadev/toglio)
+
+JavaScript/TypeScript SDK for [Toglio](https://toglio.io) — evaluate feature flags in any JS runtime: browser, Node.js, Deno, or edge functions.
+
+## Installation
+
+```bash
+npm install @toglio/js
+# or
+yarn add @toglio/js
+# or
+pnpm add @toglio/js
+```
+
+## Quick Start
+
+```typescript
+import { FeatureFlagsClient } from '@toglio/js';
+
+const client = new FeatureFlagsClient({
+  baseUrl: 'https://api.toglio.io',
+  organization: 'my-org',
+  project: 'my-project',
+  environment: 'production',
+  apiKey: process.env.TOGLIO_SDK_TOKEN!,
+});
+
+await client.initialize();
+
+if (client.isEnabled('checkout.new-flow')) {
+  // new checkout
+}
+```
+
+## How It Works
+
+1. `initialize()` loads the flag cache from `localStorage` (instant), then fetches fresh flags from the server.
+2. All reads (`isEnabled`, `getString`, etc.) are **synchronous and sub-millisecond** — no `await` needed.
+3. A background poller refreshes flags every 30 seconds by default.
+4. If the server is unreachable, the SDK falls back to the local cache, then to the `defaults` you provided. **It never throws to your application.**
+
+## Configuration
+
+```typescript
+const client = new FeatureFlagsClient({
+  // Required
+  baseUrl: 'https://api.toglio.io',   // Your Toglio API URL
+  organization: 'my-org',             // Organization slug
+  project: 'my-project',              // Project slug
+  environment: 'production',          // Environment slug (dev / staging / production)
+  apiKey: 'sdk_token_here',           // SDK token from Settings → API Keys
+
+  // Optional
+  userId: 'user_123',                 // End-user ID — required for gradual rollout & targeting
+  attributes: {                       // End-user attributes for targeting rules
+    city: 'New York',
+    plan: 'pro',
+    role: 'admin',
+  },
+  pollingInterval: 30_000,            // Refresh interval in ms (0 = disable polling)
+  defaults: {                         // Fallback values when offline or flag not found
+    'checkout.new-flow': false,
+    'pricing.variant': 'control',
+  },
+  onChange: (changes) => {            // Called after each poll when flags change
+    console.log('Flags updated:', changes);
+  },
+});
+```
+
+## API Reference
+
+### `initialize(): Promise<void>`
+
+Fetches flags from the server and starts the background poller. Call once at app startup before reading any flags.
+
+```typescript
+await client.initialize();
+```
+
+### `isEnabled(key, defaultValue?): boolean`
+
+Returns `true` if the flag is enabled. Evaluates targeting rules if `userId` is set.
+
+```typescript
+client.isEnabled('dark-mode');           // false if not found
+client.isEnabled('dark-mode', true);     // true if not found
+```
+
+### `getString(key, defaultValue?): string`
+
+```typescript
+client.getString('ui.theme', 'light');   // 'dark' | 'light' | ...
+```
+
+### `getNumber(key, defaultValue?): number`
+
+```typescript
+client.getNumber('cart.max-items', 10);  // 5 | 10 | ...
+```
+
+### `getVariant(key, defaultValue?): string`
+
+Returns the active variant key for a `VARIANT` type flag. Evaluates targeting rules if `userId` is set.
+
+```typescript
+client.getVariant('pricing-page', 'control');  // 'control' | 'variant_a' | 'variant_b'
+```
+
+### `getVariantPayload(key): unknown`
+
+Returns the JSON payload attached to the active variant, or `null`.
+
+```typescript
+const payload = client.getVariantPayload('pricing-page');
+// { cta: 'Start free trial', color: '#4f46e5' }
+```
+
+### `getAll(): FlagMap`
+
+Returns all resolved flags as a plain object.
+
+```typescript
+const flags = client.getAll();
+// { 'dark-mode': true, 'pricing-page': 'variant_a', ... }
+```
+
+### `getStatus(): ClientStatus`
+
+```typescript
+const { initialized, lastFetchAt, fetchError } = client.getStatus();
+```
+
+### `addOnChange(callback): () => void`
+
+Subscribes to flag changes. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = client.addOnChange((changes) => {
+  changes.forEach(({ key, previous, current }) => {
+    console.log(`${key}: ${previous} → ${current}`);
+  });
+});
+
+// Later:
+unsubscribe();
+```
+
+### `destroy(): void`
+
+Stops the background poller. Call when shutting down the app.
+
+```typescript
+client.destroy();
+```
+
+## Targeting & Rollout
+
+### Gradual Rollout
+
+Set `userId` to enable deterministic rollout. The SDK sends it as `X-Toglio-User-Id` on every request. The server uses `flagKey + userId` to place users in stable buckets.
+
+```typescript
+const client = new FeatureFlagsClient({
+  // ...
+  userId: currentUser.id,  // stable identifier — not related to Toglio admin users
+});
+```
+
+- `rolloutPercentage = 100`: all users get the flag.
+- `rolloutPercentage = 0`: no users get the flag.
+- `1–99`: deterministic bucket per user.
+
+### Targeting Rules
+
+Set `attributes` to enable client-side targeting rule evaluation. Rules are created in the Toglio dashboard and shipped in the SDK response.
+
+```typescript
+const client = new FeatureFlagsClient({
+  // ...
+  userId: currentUser.id,
+  attributes: {
+    city: currentUser.city,         // string
+    tags: currentUser.tags,         // string[]
+    plan: currentUser.plan,
+  },
+});
+```
+
+Supported operators: `IN`, `NOT_IN`, `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `MATCHES_REGEX`.
+
+## SSR / Server-Side Usage
+
+The SDK uses `localStorage` for caching when available and silently skips it in environments where it is not (Node.js, edge runtimes). Everything else works the same.
+
+```typescript
+// pages/index.tsx (Next.js)
+export async function getServerSideProps() {
+  const client = new FeatureFlagsClient({ /* ... */ });
+  await client.initialize();
+
+  return {
+    props: {
+      showBanner: client.isEnabled('homepage.banner'),
+    },
+  };
+}
+```
+
+For server-side usage, set `pollingInterval: 0` to disable the poller and call `client.destroy()` after reading flags.
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  FeatureFlagsClientConfig,
+  FlagMap,
+  FlagValue,
+  FlagChange,
+  ClientStatus,
+} from '@toglio/js';
+```
+
+## React
+
+For React projects, use [`@toglio/react`](https://www.npmjs.com/package/@toglio/react) which provides a context Provider and hooks (`useFlag`, `useVariant`, `useFlagsReady`).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toglio/js",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Toglio — JavaScript/TypeScript SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",