flagmint-js-sdk 2.0.0 → 2.2.0

package/README.md

@@ -137,8 +137,10 @@ After `ready()`:
 | `persistContext` | boolean | `false` | Persist context in the cache adapter |
 | `cacheAdapter` | CacheAdapter | localStorage helpers | Custom cache (Redis, files, …) |
 | `restEndpoint` | string | env default | Override the long-polling / evaluate URL |
-| `sseEndpoint` | string | env default | Override the SSE base URL (`/stream` and `/context`) |
-| `handshakeEndpoint` | string | env default | Override the ASL handshake URL. Use with `sseEndpoint` for self-hosted gateways |
+| `sseEndpoint` | string | env default | Override the SSE stream base URL (`/stream` only). Defaults to `stream.flagmint.com` / `staging-stream…` |
+| `flagsEndpoint` | string | from `restEndpoint` | Override the API base for `POST /context`. Needed when stream and API hosts differ |
+| `handshakeEndpoint` | string | env default | Override the ASL handshake URL. Use with `restEndpoint` / `sseEndpoint` for self-hosted gateways |
+| `restEndpoint` | string | env default | Override REST evaluate URL (also drives events + default context host) |
 | `env` | string | `NODE_ENV` | `development` \| `staging` \| `production` |
 | `wrapperInfo` | `{ name, version }` | native-js | Framework wrapper telemetry on the stream URL |
 | `previewMode` / `rawFlags` | | | Local-only evaluation, no network |
@@ -197,7 +199,9 @@ SSE `/context` changes **that connection’s** context. It is the right tool for
 
 # Tracking application errors
 
-`getFlag()` tells you what was served. `trackError()` tells Flagmint whether that variation hurt the user. Errors are attributed to the **currently served value** of the flag, batched, and posted to `POST /evaluator/events`. The call never throws.
+`getFlag()` tells you what was served and, when Analytics Tracking is on for that flag, queues a **debounced call-site evaluation** report (dashboard Evaluations). That report is not a billing meter.
+
+`trackError()` tells Flagmint whether that variation hurt the user. Errors are attributed to the **currently served value** of the flag, batched, and posted to `POST /evaluator/events`. The call never throws.
 
 Analytics must be enabled on the flag in the dashboard. The SDK skips `trackError` / `track` locally once the SSE `flags` packet includes `analytics` for that key. Older servers without the map still accept the POST and drop it at ingest.
 
@@ -214,17 +218,7 @@ try {
 
 `track(flagKey, eventName)` uses the same pipe for custom metrics (conversions, etc.). Only `kind: 'error'` is counted in app error rate today.
 
-### Manual verification
-
-The Flagmint dashboard evaluates its own flags with `flagmint-react-sdk` (`useFlag('homepage_variant')`). Boom that path, don't curl:
-
-1. Enable Analytics Tracking on `homepage_variant`.
-2. Run FF-EU on `:3000` and the dashboard (`npm run dev` in `flagmint`, port **5200**).
-3. Open [http://localhost:5200/?flagmint_boom=1](http://localhost:5200/?flagmint_boom=1).
 
-The homepage reads the served variant, then `trackError('homepage_variant', …)` (or POSTs `/evaluator/events` if this app still has js-sdk 1.x). Expect a **Flag error sent** toast. Metrics **App error rate** moves after the 5-minute flush.
-
-Other SDK flags: `?flagmint_boom=show_google_login` on `/login`. Production ignores the query param.
 
 ```tsx
 const enabled = useFlag('checkout_redesign', false);
@@ -283,18 +277,24 @@ The callback runs immediately with the current snapshot, then on every push. `de
 
 # Offline cache
 
-Enabled by default. On boot the SDK loads `flagmint_<apiKey>_flags` from localStorage (24h TTL). If the stream fails, those values stay in memory and `onError` fires.
+Enabled by default.
+
+- **Browser:** loads `flagmint_<apiKey>_flags` from localStorage (24h TTL). With `configSync`, also hydrates/persists `flagmint_<apiKey>_rules` (lease `expiresAt`, not wall-clock TTL).
+- **Node with no adapter:** config-sync rules still work **in memory** for that process (`RulesStore`). Helper persist is a no-op — restart → cold `fullConfig`. Plug in `setCacheStorage` / `setAsyncCacheStorage` or a custom `cacheAdapter` to survive restarts.
+- If the stream fails, the last in-memory snapshot stays and `onError` fires.
 
 ```ts
 cacheAdapter: {
   loadFlags(apiKey, ttl) { /* ... */ },
   saveFlags(apiKey, data) { /* ... */ },
   loadContext(apiKey) { /* ... */ },
-  saveContext(apiKey, ctx) { /* ... */ }
+  saveContext(apiKey, ctx) { /* ... */ },
+  loadRulesSnapshot(apiKey) { /* ... */ },   // configSync
+  saveRulesSnapshot(apiKey, snap) { /* ... */ },
 }
 ```
 
-Use `syncCache` in the browser and `asyncCache` (or your own) in Node / React Native.
+Use `syncCache` in the browser and `asyncCache` (or your own) in Node / React Native. See `sdk/core/helpers/Readme.md`.
 
 ---