impact-nova 2.2.7 → 2.2.9

package/dist/lib/guidance/analytics/analytics-adapter.d.ts

@@ -0,0 +1,16 @@
+import { GuidanceAnalyticsAdapter, GuidanceAnalyticsEvent } from '../types/guidance.types';
+export declare class NoopGuidanceAnalyticsAdapter implements GuidanceAnalyticsAdapter {
+    track(): void;
+}
+export declare class SamplingGuidanceAnalyticsAdapter implements GuidanceAnalyticsAdapter {
+    private readonly delegate;
+    private readonly stepSampleRate;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly eventQueue;
+    private flushTimer;
+    constructor(delegate: GuidanceAnalyticsAdapter, stepSampleRate?: number, batchSize?: number, flushIntervalMs?: number);
+    track(event: GuidanceAnalyticsEvent): void;
+    flush(): Promise<void>;
+}
+export declare const defaultGuidanceAnalyticsAdapter: NoopGuidanceAnalyticsAdapter;

package/dist/lib/guidance/analytics/analytics-adapter.js

@@ -0,0 +1,50 @@
+const h = /* @__PURE__ */ new Set([
+  "guide.started",
+  "guide.completed",
+  "guide.dismissed",
+  "guide.error",
+  "help_center.opened"
+]), l = /* @__PURE__ */ new Set(["step.viewed", "step.interacted"]);
+class u {
+  track() {
+  }
+}
+class n {
+  delegate;
+  stepSampleRate;
+  batchSize;
+  flushIntervalMs;
+  eventQueue = [];
+  flushTimer = null;
+  constructor(e, t = 0.25, i = 10, a = 5e3) {
+    this.delegate = e, this.stepSampleRate = t, this.batchSize = i, this.flushIntervalMs = a;
+  }
+  track(e) {
+    if (!(l.has(e.name) && Math.random() > this.stepSampleRate)) {
+      if (h.has(e.name)) {
+        this.delegate.track(e);
+        return;
+      }
+      if (this.eventQueue.push(e), this.eventQueue.length >= this.batchSize) {
+        this.flush();
+        return;
+      }
+      this.flushTimer || (this.flushTimer = setTimeout(() => {
+        this.flush();
+      }, this.flushIntervalMs));
+    }
+  }
+  async flush() {
+    this.flushTimer && (clearTimeout(this.flushTimer), this.flushTimer = null);
+    const e = this.eventQueue.splice(0);
+    for (const t of e)
+      this.delegate.track(t);
+    await this.delegate.flush?.();
+  }
+}
+const r = new u();
+export {
+  u as NoopGuidanceAnalyticsAdapter,
+  n as SamplingGuidanceAnalyticsAdapter,
+  r as defaultGuidanceAnalyticsAdapter
+};

package/dist/lib/guidance/engine/guidance-engine.d.ts

@@ -0,0 +1,74 @@
+import { GuidanceEngineConfig, GuidanceError, GuidanceEventHandler, GuidanceEventName, GuidanceSessionState, GuideManifest, RenderInstruction, Unsubscribe } from '../types/guidance.types';
+import { GuideRegistry } from './guide-registry';
+import { TriggerPluginRegistry } from '../triggers/trigger-registry';
+import { TargetResolver } from '../targets/target-resolver';
+import { GuidanceTargetRefRegistry } from '../targets/ref-registry';
+type Listener = () => void;
+export declare class GuidanceEngine {
+    private sessionState;
+    private readonly listeners;
+    private readonly eventHandlers;
+    private readonly guideRegistry;
+    private readonly triggerRegistry;
+    private readonly targetRefRegistry;
+    private readonly targetResolver;
+    private readonly guideQueue;
+    private previewMode;
+    private consentGranted;
+    private routePath;
+    private featureFlags;
+    private permissions;
+    private userSegments;
+    private customEvents;
+    private visitCounts;
+    private evaluationFrame;
+    private cachedRenderInstruction;
+    private readonly config;
+    constructor(config: GuidanceEngineConfig);
+    get state(): GuidanceSessionState;
+    get registry(): GuideRegistry;
+    get triggers(): TriggerPluginRegistry;
+    get targets(): GuidanceTargetRefRegistry;
+    get resolver(): TargetResolver;
+    subscribe(listener: Listener): Unsubscribe;
+    on(eventName: GuidanceEventName, handler: GuidanceEventHandler): Unsubscribe;
+    registerGuide(manifest: GuideManifest, routeScope?: string): void;
+    unregisterGuide(guideId: string): void;
+    unregisterRouteScope(routeScope: string): void;
+    setRoutePath(routePath: string): void;
+    setFeatureFlags(featureFlags: Record<string, boolean>): void;
+    setPermissions(permissions: string[]): void;
+    setUserSegments(userSegments: string[]): void;
+    emitCustomEvent(eventName: string): void;
+    grantConsent(): void;
+    setPreviewMode(enabled: boolean): void;
+    start(guideId: string, options?: {
+        manual?: boolean;
+    }): Promise<void>;
+    replay(guideId: string): Promise<void>;
+    dismiss(dismissMode?: 'session' | 'forever' | 'snoozed'): Promise<void>;
+    snooze(guideId?: string): Promise<void>;
+    advanceStep(): Promise<void>;
+    skipStep(): Promise<void>;
+    getRenderInstruction(): RenderInstruction | null;
+    private syncRenderInstructionCache;
+    evaluateTriggers(routeScope?: string): Promise<void>;
+    private activateGuide;
+    private completeGuide;
+    private canStartGuide;
+    private isGuideEligible;
+    private buildTriggerContext;
+    private enqueueGuide;
+    private dequeueNextGuide;
+    private loadSessionStats;
+    private saveSessionStats;
+    private hydrateVisitCounts;
+    private incrementVisitCount;
+    private scheduleEvaluation;
+    private setSession;
+    private notify;
+    private emitEvent;
+    private track;
+    reportError(error: GuidanceError): void;
+}
+export {};

package/dist/lib/guidance/engine/guidance-engine.js

@@ -0,0 +1,384 @@
+import { GuideRegistry as h } from "./guide-registry.js";
+import { getNextStepId as l, getStepIndex as p, getStepById as f, resolveLocalizedStepContent as S } from "./step-navigation.js";
+import { TriggerPluginRegistry as v } from "../triggers/trigger-registry.js";
+import { registerBuiltInTriggerPlugins as m } from "../triggers/built-in-triggers.js";
+import { TargetResolver as w, resolveTargetSynchronously as y, waitForTargetResolved as R } from "../targets/target-resolver.js";
+import { GuidanceTargetRefRegistry as I } from "../targets/ref-registry.js";
+import { buildGuidanceStorageKey as a, buildSessionStatsKey as u, createDefaultSessionStats as G } from "../storage/storage-keys.js";
+class P {
+  sessionState = { status: "idle" };
+  listeners = /* @__PURE__ */ new Set();
+  eventHandlers = /* @__PURE__ */ new Map();
+  guideRegistry = new h();
+  triggerRegistry = new v();
+  targetRefRegistry = new I();
+  targetResolver;
+  guideQueue = [];
+  previewMode = !1;
+  consentGranted = !0;
+  routePath = "/";
+  featureFlags = {};
+  permissions = [];
+  userSegments = [];
+  customEvents = /* @__PURE__ */ new Set();
+  visitCounts = {};
+  evaluationFrame = null;
+  cachedRenderInstruction = null;
+  config;
+  constructor(t) {
+    this.config = t, this.targetResolver = new w(this.targetRefRegistry), m(this.triggerRegistry), this.consentGranted = !t.consentRequired;
+  }
+  get state() {
+    return this.sessionState;
+  }
+  get registry() {
+    return this.guideRegistry;
+  }
+  get triggers() {
+    return this.triggerRegistry;
+  }
+  get targets() {
+    return this.targetRefRegistry;
+  }
+  get resolver() {
+    return this.targetResolver;
+  }
+  subscribe(t) {
+    return this.listeners.add(t), () => {
+      this.listeners.delete(t);
+    };
+  }
+  on(t, e) {
+    const s = this.eventHandlers.get(t) ?? /* @__PURE__ */ new Set();
+    return s.add(e), this.eventHandlers.set(t, s), () => {
+      s.delete(e);
+    };
+  }
+  registerGuide(t, e) {
+    this.guideRegistry.register(t, e), this.scheduleEvaluation();
+  }
+  unregisterGuide(t) {
+    this.guideRegistry.unregister(t);
+  }
+  unregisterRouteScope(t) {
+    this.guideRegistry.unregisterRouteScope(t), this.targetRefRegistry.clearScope(t);
+  }
+  setRoutePath(t) {
+    this.routePath = t, this.scheduleEvaluation();
+  }
+  setFeatureFlags(t) {
+    this.featureFlags = t;
+  }
+  setPermissions(t) {
+    this.permissions = t;
+  }
+  setUserSegments(t) {
+    this.userSegments = t;
+  }
+  emitCustomEvent(t) {
+    this.customEvents.add(t), this.scheduleEvaluation(), queueMicrotask(() => {
+      this.customEvents.delete(t);
+    });
+  }
+  grantConsent() {
+    this.consentGranted = !0;
+  }
+  setPreviewMode(t) {
+    this.previewMode = t;
+  }
+  async start(t, e) {
+    const s = this.guideRegistry.get(t);
+    if (!s) {
+      this.setSession({
+        status: "error",
+        guideId: t,
+        error: { code: "guide_not_found", message: `Guide not found: ${t}`, guideId: t }
+      });
+      return;
+    }
+    if (!this.consentGranted && !this.previewMode)
+      return;
+    if (this.sessionState.status === "active" && this.sessionState.guideId !== t) {
+      if (s.queueOnConflict) {
+        this.enqueueGuide(t);
+        return;
+      }
+      return;
+    }
+    await this.canStartGuide(t, e?.manual ?? !1) && await this.activateGuide(s, 0);
+  }
+  async replay(t) {
+    this.previewMode = !0, await this.start(t, { manual: !0 });
+  }
+  async dismiss(t = "session") {
+    const e = this.sessionState.guideId;
+    if (e) {
+      if (t === "forever" && await this.config.storage.set({
+        [a(this.config.tenantId, e, "dismissed")]: {
+          dismissed: !0,
+          timestamp: Date.now()
+        }
+      }), t === "snoozed") {
+        const s = await this.loadSessionStats();
+        s.snoozedUntil[e] = Date.now() + 1440 * 60 * 1e3, await this.saveSessionStats(s);
+      }
+      this.emitEvent("guideEnd", { guideId: e, reason: "dismissed" }), this.track("guide.dismissed", { guideId: e, dismissMode: t }), this.setSession({ status: "dismissed", guideId: e, dismissMode: t }), await this.dequeueNextGuide();
+    }
+  }
+  async snooze(t) {
+    (t ?? this.sessionState.guideId) && await this.dismiss("snoozed");
+  }
+  async advanceStep() {
+    const t = this.sessionState.guideId, e = this.sessionState.stepId;
+    if (!t || !e || this.sessionState.status !== "active")
+      return;
+    const s = this.guideRegistry.get(t);
+    if (!s)
+      return;
+    this.track("step.completed", { guideId: t, stepId: e });
+    const i = await l(
+      s,
+      e,
+      (r) => this.triggerRegistry.evaluateExpression(r, this.buildTriggerContext())
+    );
+    if (!i) {
+      await this.completeGuide(t);
+      return;
+    }
+    const n = p(s, i);
+    await this.activateGuide(s, n);
+  }
+  async skipStep() {
+    const t = this.sessionState.guideId, e = this.sessionState.stepId;
+    !t || !e || (this.track("step.skipped", { guideId: t, stepId: e }), await this.advanceStep());
+  }
+  getRenderInstruction() {
+    return this.cachedRenderInstruction;
+  }
+  syncRenderInstructionCache() {
+    if (this.sessionState.status !== "active" || !this.sessionState.guideId || this.sessionState.stepId === void 0 || this.sessionState.stepIndex === void 0) {
+      this.cachedRenderInstruction = null;
+      return;
+    }
+    const t = this.guideRegistry.get(this.sessionState.guideId), e = t ? f(t, this.sessionState.stepId) : void 0;
+    if (!t || !e) {
+      this.cachedRenderInstruction = null;
+      return;
+    }
+    this.cachedRenderInstruction = {
+      guideId: t.id,
+      stepId: e.id,
+      stepIndex: this.sessionState.stepIndex,
+      totalSteps: t.steps.length,
+      renderer: e.renderer,
+      content: S(t, e, this.config.locale),
+      target: this.sessionState.resolvedTarget ?? null,
+      skippable: e.skippable,
+      advanceOn: e.advanceOn
+    };
+  }
+  async evaluateTriggers(t) {
+    if (this.previewMode || this.sessionState.status === "active")
+      return;
+    const e = await this.loadSessionStats();
+    if (e.guidesShownThisSession >= this.config.maxGuidesPerSession || e.lastGuideEndedAt && Date.now() - e.lastGuideEndedAt < this.config.cooldownBetweenGuides)
+      return;
+    const s = t ? this.guideRegistry.getForRoute(t) : [], i = s.length > 0 ? s : this.guideRegistry.getAll();
+    await this.hydrateVisitCounts(i.map((o) => o.id));
+    const n = [];
+    for (const o of this.guideRegistry.getSortedByPriority(
+      i.map((d) => d.id)
+    ))
+      await this.isGuideEligible(o, e) && n.push(o);
+    if (!n.length)
+      return;
+    const r = n[0];
+    this.track("guide.triggered", { guideId: r.id }), await this.start(r.id);
+  }
+  async activateGuide(t, e) {
+    const s = t.steps[e];
+    if (!s) {
+      await this.completeGuide(t.id);
+      return;
+    }
+    let i = y(
+      this.targetResolver,
+      s.target
+    );
+    if (i?.element || (this.setSession({
+      status: "evaluating",
+      guideId: t.id,
+      stepIndex: e,
+      stepId: s.id
+    }), i = await R(
+      this.targetResolver,
+      s.target,
+      s.timeout ?? 5e3
+    )), !i?.element) {
+      this.setSession({
+        status: "blocked",
+        guideId: t.id,
+        stepIndex: e,
+        stepId: s.id,
+        reason: i ? "target_not_visible" : "target_not_found"
+      });
+      return;
+    }
+    if (e === 0) {
+      this.emitEvent("guideStart", { guideId: t.id, stepId: s.id }), this.track("guide.started", { guideId: t.id });
+      const n = await this.loadSessionStats();
+      n.guidesShownThisSession += 1, await this.saveSessionStats(n), await this.incrementVisitCount(t.id);
+    }
+    this.emitEvent("stepChange", { guideId: t.id, stepId: s.id }), this.track("step.viewed", { guideId: t.id, stepId: s.id }), this.setSession({
+      status: "active",
+      guideId: t.id,
+      stepIndex: e,
+      stepId: s.id,
+      resolvedTarget: {
+        ...i,
+        rect: i.element.getBoundingClientRect()
+      }
+    }), t.persistence.resumeOnRefresh && await this.config.storage.set({
+      [a(this.config.tenantId, t.id, "lastStep")]: {
+        stepId: s.id,
+        timestamp: Date.now()
+      }
+    });
+  }
+  async completeGuide(t) {
+    this.guideRegistry.get(t)?.persistence.mode === "showOnce" && await this.config.storage.set({
+      [a(this.config.tenantId, t, "dismissed")]: {
+        dismissed: !0,
+        timestamp: Date.now()
+      }
+    }), await this.config.storage.delete([
+      a(this.config.tenantId, t, "lastStep")
+    ]);
+    const s = await this.loadSessionStats();
+    s.lastGuideEndedAt = Date.now(), await this.saveSessionStats(s), this.emitEvent("guideEnd", { guideId: t, reason: "completed" }), this.track("guide.completed", { guideId: t }), this.setSession({ status: "completed", guideId: t }), await this.dequeueNextGuide();
+  }
+  async canStartGuide(t, e) {
+    if (e || this.previewMode)
+      return !0;
+    const s = this.guideRegistry.get(t);
+    if (!s)
+      return !1;
+    const i = await this.loadSessionStats();
+    return this.isGuideEligible(s, i);
+  }
+  async isGuideEligible(t, e) {
+    const s = a(
+      this.config.tenantId,
+      t.id,
+      "dismissed"
+    );
+    if ((await this.config.storage.get([s]))[s]?.dismissed && t.persistence.mode !== "replayable")
+      return !1;
+    const r = e.snoozedUntil[t.id];
+    if (r && Date.now() < r || (e.dismissedCounts[t.id] ?? 0) >= 3 && t.persistence.mode === "showOnce")
+      return !1;
+    if (t.persistence.schedule) {
+      const d = Date.now(), c = Date.parse(t.persistence.schedule.start), g = Date.parse(t.persistence.schedule.end);
+      if (d < c || d > g)
+        return !1;
+    }
+    return this.triggerRegistry.evaluateAll(
+      t.triggers,
+      this.buildTriggerContext()
+    );
+  }
+  buildTriggerContext() {
+    return {
+      routePath: this.routePath,
+      appVersion: this.config.appVersion,
+      featureFlags: this.featureFlags,
+      permissions: this.permissions,
+      userSegments: this.userSegments,
+      customEvents: this.customEvents,
+      visitCounts: this.visitCounts,
+      now: Date.now(),
+      previewMode: this.previewMode
+    };
+  }
+  enqueueGuide(t) {
+    this.guideQueue.includes(t) || (this.guideQueue.push(t), this.setSession({
+      status: "queued",
+      guideId: t,
+      position: this.guideQueue.indexOf(t) + 1
+    }), this.track("guide.queued", { guideId: t }));
+  }
+  async dequeueNextGuide() {
+    this.previewMode = !1;
+    const t = this.guideQueue.shift();
+    if (!t) {
+      this.setSession({ status: "idle" });
+      return;
+    }
+    await this.start(t);
+  }
+  async loadSessionStats() {
+    const t = u(this.config.tenantId);
+    return (await this.config.storage.get([t]))[t] ?? G();
+  }
+  async saveSessionStats(t) {
+    await this.config.storage.set({
+      [u(this.config.tenantId)]: t
+    });
+  }
+  async hydrateVisitCounts(t) {
+    if (!t.length)
+      return;
+    const e = t.map(
+      (i) => a(this.config.tenantId, i, "visitCount")
+    ), s = await this.config.storage.get(e);
+    for (const i of t) {
+      const n = a(
+        this.config.tenantId,
+        i,
+        "visitCount"
+      ), r = s[n];
+      typeof r == "number" && (this.visitCounts[i] = r);
+    }
+  }
+  async incrementVisitCount(t) {
+    const e = a(
+      this.config.tenantId,
+      t,
+      "visitCount"
+    ), n = ((await this.config.storage.get([e]))[e] ?? 0) + 1;
+    this.visitCounts[t] = n, await this.config.storage.set({ [e]: n });
+  }
+  scheduleEvaluation() {
+    typeof window > "u" || (this.evaluationFrame !== null && cancelAnimationFrame(this.evaluationFrame), this.evaluationFrame = requestAnimationFrame(() => {
+      this.evaluationFrame = null, this.evaluateTriggers(this.routePath);
+    }));
+  }
+  setSession(t) {
+    this.sessionState = t, this.syncRenderInstructionCache(), this.notify();
+  }
+  notify() {
+    for (const t of this.listeners)
+      t();
+  }
+  emitEvent(t, e) {
+    for (const s of this.eventHandlers.get(t) ?? [])
+      s(e);
+  }
+  track(t, e) {
+    this.config.analytics.track({
+      name: t,
+      properties: e,
+      timestamp: Date.now()
+    });
+  }
+  reportError(t) {
+    this.config.errorReporter?.report(t), this.track("guide.error", { ...t }), this.setSession({
+      status: "error",
+      guideId: t.guideId,
+      error: t
+    });
+  }
+}
+export {
+  P as GuidanceEngine
+};

package/dist/lib/guidance/engine/guide-registry.d.ts

@@ -0,0 +1,21 @@
+import { GuideManifest } from '../types/guidance.types';
+type GuideRegistryListener = () => void;
+export declare class GuideRegistry {
+    private readonly guides;
+    private readonly routeScopes;
+    private readonly registrationOrder;
+    private readonly listeners;
+    private registryVersion;
+    subscribe(listener: GuideRegistryListener): () => void;
+    getVersion(): number;
+    private notifyListeners;
+    register(manifest: GuideManifest, routeScope?: string): void;
+    unregister(guideId: string): void;
+    unregisterRouteScope(routeScope: string): void;
+    get(guideId: string): GuideManifest | undefined;
+    getAll(): GuideManifest[];
+    getForRoute(routeScope: string): GuideManifest[];
+    getSortedByPriority(guideIds?: string[]): GuideManifest[];
+    private enforceCapacity;
+}
+export {};

package/dist/lib/guidance/engine/guide-registry.js

@@ -0,0 +1,71 @@
+import { validateGuideManifest as o, sanitizeGuideManifest as n } from "./manifest-validator.js";
+const d = 50;
+class a {
+  guides = /* @__PURE__ */ new Map();
+  routeScopes = /* @__PURE__ */ new Map();
+  registrationOrder = [];
+  listeners = /* @__PURE__ */ new Set();
+  registryVersion = 0;
+  subscribe(e) {
+    return this.listeners.add(e), () => {
+      this.listeners.delete(e);
+    };
+  }
+  getVersion() {
+    return this.registryVersion;
+  }
+  notifyListeners() {
+    this.registryVersion += 1;
+    for (const e of this.listeners)
+      e();
+  }
+  register(e, t) {
+    const i = o(e);
+    if (i.length > 0)
+      throw new Error(
+        `Invalid guide manifest "${e.id}": ${i.join("; ")}`
+      );
+    const r = n(e);
+    if (this.guides.has(r.id) || this.registrationOrder.push(r.id), this.guides.set(r.id, r), t) {
+      const s = this.routeScopes.get(t) ?? /* @__PURE__ */ new Set();
+      s.add(r.id), this.routeScopes.set(t, s);
+    }
+    this.enforceCapacity(), this.notifyListeners();
+  }
+  unregister(e) {
+    this.guides.delete(e), this.registrationOrder.splice(this.registrationOrder.indexOf(e), 1);
+    for (const [t, i] of this.routeScopes.entries())
+      i.delete(e), i.size || this.routeScopes.delete(t);
+    this.notifyListeners();
+  }
+  unregisterRouteScope(e) {
+    const t = this.routeScopes.get(e);
+    if (t)
+      for (const i of Array.from(t))
+        this.unregister(i);
+  }
+  get(e) {
+    return this.guides.get(e);
+  }
+  getAll() {
+    return Array.from(this.guides.values());
+  }
+  getForRoute(e) {
+    const t = this.routeScopes.get(e);
+    return t ? Array.from(t).map((i) => this.guides.get(i)).filter((i) => !!i) : [];
+  }
+  getSortedByPriority(e) {
+    return (e ? e.map((i) => this.guides.get(i)).filter((i) => !!i) : this.getAll()).sort((i, r) => i.priority !== r.priority ? i.priority - r.priority : this.registrationOrder.indexOf(i.id) - this.registrationOrder.indexOf(r.id));
+  }
+  enforceCapacity() {
+    for (; this.guides.size > d; ) {
+      const e = this.registrationOrder.shift();
+      if (!e)
+        break;
+      this.unregister(e);
+    }
+  }
+}
+export {
+  a as GuideRegistry
+};

package/dist/lib/guidance/engine/manifest-validator.d.ts

@@ -0,0 +1,4 @@
+import { GuideManifest, StepContent } from '../types/guidance.types';
+export declare function sanitizeStepContent(content: StepContent): StepContent;
+export declare function sanitizeGuideManifest(manifest: GuideManifest): GuideManifest;
+export declare function validateGuideManifest(manifest: GuideManifest): string[];