@guidelytech/sdk-core 0.6.1 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guidely
+
+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

@@ -51,6 +51,7 @@ The module is safe to import during SSR (nothing touches `window` at module scop
 | `user` | — | `{ id, traits?, account? }` to identify immediately. |
 | `fetch` | global | Custom `fetch` (tests, polyfills). |
 | `disableAuthoring` | `false` | Ignore `?guidely_authoring=` in the URL. |
+| `flags` | on | Feature flags (same key and API URL). `false` turns them off; an object passes [flags client options](../flags/README.md#options), e.g. `{ payload }` (server-rendered bootstrap), `{ attributes }`, `{ remoteEval: true }`, `{ pollingMode: "stream" }`. |
 
 ## API
 
@@ -86,6 +87,10 @@ event, never thrown into the host application.
 | `getState()` | Debug snapshot: ready flag, ids, config version, active/queued guides, widgets, state, pending events. |
 | `destroy()` | Full cleanup: guides, widgets, listeners, timers, the `#guidely-root` host; flushes pending events via `sendBeacon`. A new client can be created afterwards. |
 | `GuidelyClient.init(options)` / `GuidelyClient.get()` | Singleton helpers used by the embed (`window.Guidely.init/get`). |
+| `isFeatureEnabled(key, fallback = false)` | Boolean flag for the current user (`fallback` until loaded, when missing or not a boolean). |
+| `getFeatureValue(key, fallback)` / `getFeatureDetails(key, fallback)` | Flag value / value plus reason, rule, variation and experiment. |
+| `onFlagsChange(cb): () => void` | Called whenever flag values may have changed (new rules, identify, navigation, overrides). |
+| `flags` | The [flags client](../flags/README.md): `isEnabled`, `getValue`, `getAll`, `setAttributes`, `setOverrides`, `ready`, `subscribe`… |
 
 ### Events
 
@@ -93,7 +98,26 @@ event, never thrown into the host application.
 `guide:complete(guide)`, `guide:dismiss(guide)`, `guide:skip(guide)`,
 `checklist:task({ guide, task, progress })`, `checklist:complete(guide)`,
 `survey:submit({ guide, answers, responseId })`, `resource-center:open()`, `error(Error)`,
-`track(sdkEvent)`, `identify({ userId, anonymousId })`, `authoring({ active })`.
+`track(sdkEvent)`, `identify({ userId, anonymousId })`, `authoring({ active })`, `flags:ready()`,
+`flags:change()`.
+
+## Feature flags
+
+```ts
+if (guidely.isFeatureEnabled("new-checkout")) showNewCheckout();
+const color = guidely.getFeatureValue("checkout-button-color", "blue");
+guidely.onFlagsChange(() => rerender());
+guidely.flags.updateAttributes({ cohort: "beta" }); // extra attributes, kept across identify()
+```
+
+Flags load in parallel with the guide config, with the same public key, and the last payload is
+cached in storage (`guidely:flags:<key>`). Attributes are maintained for you: `id` (the identified
+user id, else the anonymous id), `anonymousId`, every identify trait, `account` (`{ id, …traits }`),
+`$audiences` (audience ids from identify), `url`, `path`, `deviceType`, `browser`, `os`, `locale`,
+`environment` and `platform: "web"`; they update on `identify`, `updateTraits`, `setAccount`,
+`reset` and navigation. Experiment exposures are tracked as `experiment_viewed` events
+(`experimentKey`, `variationId`, `variationName`, `flagKey`, `hashAttribute`) once per session,
+through the event queue, so consent and `analytics: false` apply.
 
 ## Behaviour
 
@@ -147,7 +171,7 @@ Messages posted to the opener: `guidely:authoring-ready { sessionId, url }`, `gu
 ## Storage keys
 
 `guidely:anon`, `guidely:seen`, `guidely:config:<key>`, `guidely:etag:<key>`, `guidely:state:<key>`,
-`guidely:user:<key>`, `guidely:queue:<key>` (local/session storage per `storage` option);
+`guidely:user:<key>`, `guidely:queue:<key>`, `guidely:flags:<key>` (local/session storage per `storage` option);
 `guidely:session`, `guidely:active`, `guidely:authoring` (sessionStorage).
 
 ## Network recording (session replay)
@@ -181,11 +205,12 @@ lazily loaded recorder chunk; the base bundle does not grow.
 
 | Bundle | minified | min+gz |
 |---|---|---|
-| sdk-core + guide-runtime + floating-ui + `@guidelytech/shared/runtime` (everything an app ships) | 142 kB | **44.4 kB** |
+| sdk-core + guide-runtime + floating-ui + `@guidelytech/flags` (everything an app ships, excluding `@guidelytech/shared`) | 195 kB | **61.4 kB** |
 | Scout messenger chunk (`@guidelytech/guide-runtime/messenger`, loaded on demand) | 26 kB | 8.8 kB |
 | Session-replay chunk (`./recorder`: rrweb + replay controller + network recording, loaded only when a session is recorded) | 94 kB | 30 kB |
 | script-tag build `guidely.js` (authoring schemas and messenger inlined) | 244 kB | ~71 kB |
 
 The SDK imports only the zod-free `@guidelytech/shared/runtime` entry; the Zod schemas are loaded
-lazily and only when the page enters authoring mode. Budget: 45 kB min+gz for the npm runtime and
+lazily and only when the page enters authoring mode. Feature flags (client + evaluator) add
+~13 kB min+gz. Budget: 45 kB min+gz for the npm runtime and
 15 kB for the messenger chunk, 80 kB for the session-replay chunk.

package/dist/headless.d.cts

@@ -1,6 +1,7 @@
 export { A as Api, a as ApiResponse, F as FetchLike, K as KEYS, b as KeyValueStore, c as backoffMs, m as memoryStore, p as postWithRetry, r as readJson, s as sleep, w as writeJson } from './http-47tiAlOM.cjs';
-export { C as ChecklistProgressState, a as ConsentState, E as EventQueue, b as EventQueueOptions, G as GuideLocalState, c as GuidelyAccount, d as GuidelyEnvironment, e as GuidelyUser, P as PersistedState, S as SessionState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-d4eOerxi.cjs';
+export { C as ChecklistProgressState, a as ConsentState, E as EventQueue, b as EventQueueOptions, G as GuideLocalState, c as GuidelyAccount, d as GuidelyEnvironment, e as GuidelyUser, P as PersistedState, S as SessionState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-DbKQPvFt.cjs';
 import '@guidelytech/shared';
+import '@guidelytech/flags';
 
 type AnyFn = (...args: any[]) => void;
 /** Tiny typed event emitter. Listener errors are reported, never thrown into the caller. */

package/dist/headless.d.ts

@@ -1,6 +1,7 @@
 export { A as Api, a as ApiResponse, F as FetchLike, K as KEYS, b as KeyValueStore, c as backoffMs, m as memoryStore, p as postWithRetry, r as readJson, s as sleep, w as writeJson } from './http-47tiAlOM.js';
-export { C as ChecklistProgressState, a as ConsentState, E as EventQueue, b as EventQueueOptions, G as GuideLocalState, c as GuidelyAccount, d as GuidelyEnvironment, e as GuidelyUser, P as PersistedState, S as SessionState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-RyeRQd9f.js';
+export { C as ChecklistProgressState, a as ConsentState, E as EventQueue, b as EventQueueOptions, G as GuideLocalState, c as GuidelyAccount, d as GuidelyEnvironment, e as GuidelyUser, P as PersistedState, S as SessionState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-DqhNl5Am.js';
 import '@guidelytech/shared';
+import '@guidelytech/flags';
 
 type AnyFn = (...args: any[]) => void;
 /** Tiny typed event emitter. Listener errors are reported, never thrown into the caller. */

package/dist/index.cjs

@@ -60,6 +60,7 @@ module.exports = __toCommonJS(index_exports);
 var import_runtime13 = require("@guidelytech/shared/runtime");
 var import_guide_runtime4 = require("@guidelytech/guide-runtime");
 var import_guide_runtime5 = require("@guidelytech/guide-runtime");
+var import_flags = require("@guidelytech/flags");
 
 // src/authoring.ts
 var import_guide_runtime = require("@guidelytech/guide-runtime");
@@ -1456,7 +1457,7 @@ var loadRecorder = async () => (await import("./recorder.cjs")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.6.1";
+var SDK_VERSION = "0.7.0";
 var DEFAULT_API_URL = "https://api.guidely.app";
 var PAGE_SCOPED = /* @__PURE__ */ new Set(["page_load", "url_match", "element_click", "element_visible", "delay"]);
 var DAY_MS = 24 * 60 * 60 * 1e3;
@@ -1526,6 +1527,10 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "initialPageViewSent", false);
     __publicField(this, "pageViewUrl", null);
     __publicField(this, "pageLeft", false);
+    /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
+    __publicField(this, "flags");
+    /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
+    __publicField(this, "exposures", /* @__PURE__ */ new Set());
     __publicField(this, "customListeners", /* @__PURE__ */ new Map());
     __publicField(this, "eventBus", {
       on: (name, cb) => {
@@ -1584,6 +1589,39 @@ var GuidelyClient = class _GuidelyClient {
       onError: (err) => this.reportError(err)
     });
     if (options.user) this.user = { ...options.user };
+    this.flags = this.createFlags(options.flags);
+  }
+  createFlags(opts) {
+    const base = { sdkKey: this.options.projectId, apiUrl: this.options.apiUrl, fetch: this.options.fetch, sdk: { name: SDK_NAME, version: SDK_VERSION } };
+    if (opts === false) return (0, import_flags.createFlagsClient)({ ...base, overrideBehaviour: "localOnly", offline: true, reportUsage: false, trackExposures: false, storage: false, logger: null });
+    const o = opts ?? {};
+    return (0, import_flags.createFlagsClient)({
+      ...base,
+      storage: { getItem: (k) => this.store.get(k), setItem: (k, v) => this.store.set(k, v), removeItem: (k) => this.store.remove(k) },
+      reportUsage: this.options.analytics,
+      // Failures surface through onError (and `debug` logs); development warnings (unknown flag keys) reach the console.
+      logger: { warn: (...a) => console.warn("[Guidely]", ...a), error: (...a) => this.log(...a) },
+      ...o,
+      contextAttributes: this.flagContext(),
+      // Exposures travel through the event pipeline (with the session) as `experiment_viewed`.
+      trackExposures: false,
+      onFlagEvaluated: (result) => {
+        this.trackExposure(result);
+        o.onFlagEvaluated?.(result);
+      },
+      onReady: () => {
+        this.emitter.emit("flags:ready");
+        o.onReady?.();
+      },
+      onChange: (data) => {
+        this.emitter.emit("flags:change");
+        o.onChange?.(data);
+      },
+      onError: (err) => {
+        this.reportError(err);
+        o.onError?.(err);
+      }
+    });
   }
   // ---------------------------------------------------------------------------
   // Lifecycle
@@ -1784,6 +1822,7 @@ var GuidelyClient = class _GuidelyClient {
     this.replay = null;
     this.queue.flushSync();
     this.queue.destroy();
+    this.flags.destroy();
     this.emitter.clear();
     (0, import_guide_runtime4.destroyHost)();
     if (current === this) current = null;
@@ -1797,6 +1836,7 @@ var GuidelyClient = class _GuidelyClient {
     this.identitySettled = true;
     this.user = { id: String(userId), traits: { ...this.user?.id === String(userId) ? this.user.traits : {}, ...traits || {} }, account: account ?? (this.user?.id === String(userId) ? this.user.account : void 0) };
     writeJson(this.store, KEYS.user(this.options.projectId), this.user);
+    this.syncFlagAttributes();
     this.enqueue("identify", { properties: { traits: (0, import_runtime13.sanitizeProperties)(this.user.traits) } });
     await this.syncIdentify();
     this.emitter.emit("identify", { userId: this.user.id, anonymousId: this.anonymousId });
@@ -1837,6 +1877,7 @@ var GuidelyClient = class _GuidelyClient {
     };
     if (data.firstSeenAt && Date.now() - Date.parse(data.firstSeenAt) > 6e4) this.firstVisit = false;
     this.persistState();
+    this.syncFlagAttributes();
     this.widgets.forEach((w, id) => {
       const g = this.findGuide(id);
       if (w.checklist && g) w.checklist.setProgress(this.getChecklistProgress(g.id));
@@ -1848,6 +1889,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.user) {
       this.user = { id: "", account };
       writeJson(this.store, KEYS.user(this.options.projectId), this.user);
+      this.syncFlagAttributes();
       return;
     }
     await this.identify(this.user.id, void 0, account);
@@ -1856,6 +1898,7 @@ var GuidelyClient = class _GuidelyClient {
   async updateTraits(traits) {
     if (!this.user?.id) {
       this.user = { id: "", traits: { ...this.user?.traits || {}, ...traits } };
+      this.syncFlagAttributes();
       return;
     }
     await this.identify(this.user.id, traits, this.user.account);
@@ -1881,6 +1924,8 @@ var GuidelyClient = class _GuidelyClient {
     this.widgets.clear();
     forgetConversations(this.store, this.options.projectId);
     this.destroyMessenger();
+    this.exposures.clear();
+    this.syncFlagAttributes();
     this.emitter.emit("identify", { userId: null, anonymousId: this.anonymousId });
     if (this.isReady) {
       this.renderPersistentWidgets();
@@ -1953,6 +1998,7 @@ var GuidelyClient = class _GuidelyClient {
     if (this.destroyed) return;
     const changed = url !== this.lastUrl;
     this.lastUrl = url;
+    if (changed) this.syncFlagAttributes();
     if (!explicit && changed) {
       this.leavePage(url);
       this.trackPageView(url);
@@ -2884,6 +2930,58 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.config?.messenger?.enabled) return;
     void this.loadMessenger().then((m) => m?.showNewMessage(text));
   }
+  // ---------------------------------------------------------------------------
+  // Feature flags
+  // ---------------------------------------------------------------------------
+  /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
+  isFeatureEnabled(key, fallback = false) {
+    return this.flags.isEnabled(key, fallback);
+  }
+  /** Flag value for the current user; `fallback` when missing or of a different type. */
+  getFeatureValue(key, fallback) {
+    return this.flags.getValue(key, fallback);
+  }
+  /** Flag value plus why it was served (reason, rule, variation, experiment). */
+  getFeatureDetails(key, fallback) {
+    return this.flags.getDetails(key, fallback);
+  }
+  /** Calls `cb` whenever flag values may have changed (new rules, identity, page, overrides). Returns an unsubscribe function. */
+  onFlagsChange(cb) {
+    return this.flags.subscribe(cb);
+  }
+  /** Attributes flags are evaluated with: identity, traits, account, audiences, page and device. */
+  flagContext() {
+    const device = detectDevice(navigator.userAgent, window.innerWidth);
+    const account = this.user?.account;
+    return {
+      url: location.href,
+      path: location.pathname,
+      deviceType: device.type,
+      browser: device.browser,
+      os: device.os,
+      locale: navigator.language || void 0,
+      environment: this.options.environment,
+      platform: "web",
+      ...this.user?.traits ?? {},
+      id: this.user?.id || this.anonymousId,
+      anonymousId: this.anonymousId,
+      account: account ? { ...account.traits ?? {}, id: account.id } : void 0,
+      $audiences: [...this.state.audienceIds]
+    };
+  }
+  syncFlagAttributes() {
+    if (!this.destroyed) this.flags?.setContextAttributes(this.flagContext());
+  }
+  /** `experiment_viewed`, once per session and assignment, through the event queue (consent applies). */
+  trackExposure(result) {
+    const exp = result.inExperiment ? result.experiment : void 0;
+    if (!exp || this.destroyed) return;
+    const key = `${this.session.id}|${exp.key}|${exp.hashValue}|${exp.variationId}`;
+    if (this.exposures.has(key)) return;
+    if (this.exposures.size > 500) this.exposures.clear();
+    this.exposures.add(key);
+    this.enqueue("experiment_viewed", { properties: { experimentKey: exp.key, variationId: exp.variationId, flagKey: result.key, hashAttribute: exp.hashAttribute, ...exp.variationName ? { variationName: exp.variationName } : {} } });
+  }
   on(event, cb) {
     return this.emitter.on(event, cb);
   }
@@ -2909,7 +3007,8 @@ var GuidelyClient = class _GuidelyClient {
       session: this.session,
       pendingEvents: this.queue.size,
       authoring: !!this.authoring?.isActive(),
-      capture: !!this.capture?.isActive()
+      capture: !!this.capture?.isActive(),
+      flagsReady: this.flags.isReady()
     };
   }
   // ---------------------------------------------------------------------------