@guidelytech/sdk-core 0.6.2 → 0.7.0

package/dist/index.d.cts

@@ -1,15 +1,17 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
 export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { j as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, k as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-d4eOerxi.cjs';
-export { E as EventQueue, b as EventQueueOptions, l as GuideStepInfo, d as GuidelyEnvironment, m as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-d4eOerxi.cjs';
+import { j as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, k as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-DbKQPvFt.cjs';
+export { E as EventQueue, b as EventQueueOptions, l as GuideStepInfo, d as GuidelyEnvironment, m as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-DbKQPvFt.cjs';
 export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.cjs';
 export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-C3faAYb7.cjs';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.6.2";
+declare const SDK_VERSION = "0.7.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -66,7 +68,12 @@ declare class GuidelyClient {
     private initialPageViewSent;
     private pageViewUrl;
     private pageLeft;
+    /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
+    readonly flags: FlagsClient;
+    /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
+    private exposures;
     constructor(options: GuidelyOptions);
+    private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
     init(): Promise<void>;
     /** Resolves once the client is ready (alias of `init()`). */
@@ -209,6 +216,19 @@ declare class GuidelyClient {
     closeMessenger(): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
+    /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
+    isFeatureEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value for the current user; `fallback` when missing or of a different type. */
+    getFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    /** Flag value plus why it was served (reason, rule, variation, experiment). */
+    getFeatureDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Calls `cb` whenever flag values may have changed (new rules, identity, page, overrides). Returns an unsubscribe function. */
+    onFlagsChange(cb: () => void): () => void;
+    /** Attributes flags are evaluated with: identity, traits, account, audiences, page and device. */
+    private flagContext;
+    private syncFlagAttributes;
+    /** `experiment_viewed`, once per session and assignment, through the event queue (consent applies). */
+    private trackExposure;
     on<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): () => void;
     off<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): void;
     /** Snapshot for debugging / devtools. */
@@ -241,6 +261,7 @@ declare class GuidelyClient {
         pendingEvents: number;
         authoring: boolean;
         capture: boolean;
+        flagsReady: boolean;
     };
     private maybeStartAuthoring;
     /** Authoring or capture started / ended: pause everything a visitor would see or be recorded by. */

package/dist/index.d.ts

@@ -1,15 +1,17 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
 export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { j as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, k as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-RyeRQd9f.js';
-export { E as EventQueue, b as EventQueueOptions, l as GuideStepInfo, d as GuidelyEnvironment, m as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-RyeRQd9f.js';
+import { j as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, k as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-DqhNl5Am.js';
+export { E as EventQueue, b as EventQueueOptions, l as GuideStepInfo, d as GuidelyEnvironment, m as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, g as isFrequencyEligible, h as isWithinSchedule } from './types-DqhNl5Am.js';
 export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.js';
 export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-Dqd7up2n.js';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.6.2";
+declare const SDK_VERSION = "0.7.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -66,7 +68,12 @@ declare class GuidelyClient {
     private initialPageViewSent;
     private pageViewUrl;
     private pageLeft;
+    /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
+    readonly flags: FlagsClient;
+    /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
+    private exposures;
     constructor(options: GuidelyOptions);
+    private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
     init(): Promise<void>;
     /** Resolves once the client is ready (alias of `init()`). */
@@ -209,6 +216,19 @@ declare class GuidelyClient {
     closeMessenger(): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
+    /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
+    isFeatureEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value for the current user; `fallback` when missing or of a different type. */
+    getFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    /** Flag value plus why it was served (reason, rule, variation, experiment). */
+    getFeatureDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Calls `cb` whenever flag values may have changed (new rules, identity, page, overrides). Returns an unsubscribe function. */
+    onFlagsChange(cb: () => void): () => void;
+    /** Attributes flags are evaluated with: identity, traits, account, audiences, page and device. */
+    private flagContext;
+    private syncFlagAttributes;
+    /** `experiment_viewed`, once per session and assignment, through the event queue (consent applies). */
+    private trackExposure;
     on<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): () => void;
     off<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): void;
     /** Snapshot for debugging / devtools. */
@@ -241,6 +261,7 @@ declare class GuidelyClient {
         pendingEvents: number;
         authoring: boolean;
         capture: boolean;
+        flagsReady: boolean;
     };
     private maybeStartAuthoring;
     /** Authoring or capture started / ended: pause everything a visitor would see or be recorded by. */

package/dist/index.js

@@ -31,6 +31,7 @@ import {
   waitForTarget
 } from "@guidelytech/guide-runtime";
 import { createScope } from "@guidelytech/guide-runtime";
+import { createFlagsClient } from "@guidelytech/flags";
 
 // src/authoring.ts
 import { highlightSelectors, previewStep, runGuide, startAuthoring } from "@guidelytech/guide-runtime";
@@ -1012,7 +1013,7 @@ var loadRecorder = async () => (await import("./recorder.js")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.6.2";
+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;
@@ -1082,6 +1083,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) => {
@@ -1140,6 +1145,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 createFlagsClient({ ...base, overrideBehaviour: "localOnly", offline: true, reportUsage: false, trackExposures: false, storage: false, logger: null });
+    const o = opts ?? {};
+    return 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
@@ -1340,6 +1378,7 @@ var GuidelyClient = class _GuidelyClient {
     this.replay = null;
     this.queue.flushSync();
     this.queue.destroy();
+    this.flags.destroy();
     this.emitter.clear();
     destroyHost();
     if (current === this) current = null;
@@ -1353,6 +1392,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: sanitizeProperties(this.user.traits) } });
     await this.syncIdentify();
     this.emitter.emit("identify", { userId: this.user.id, anonymousId: this.anonymousId });
@@ -1393,6 +1433,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));
@@ -1404,6 +1445,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);
@@ -1412,6 +1454,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);
@@ -1437,6 +1480,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();
@@ -1509,6 +1554,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);
@@ -2440,6 +2486,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);
   }
@@ -2465,7 +2563,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()
     };
   }
   // ---------------------------------------------------------------------------