@cognior/iap-sdk 0.2.2 → 0.2.8

package/dist/index.d.ts

@@ -46,8 +46,6 @@ interface EnhancedStepData {
     uxExperience?: {
         uxExperienceType: string;
         elementSelector?: string;
-        elementTrigger?: string;
-        elementLocation?: string;
         position?: {
             x: string;
             y: string;
@@ -67,22 +65,121 @@ interface FlowData {
         mode?: FlowExecutionMode;
         multiPage?: boolean;
         frequency?: {
-            type: 'OneTime' | 'Daily' | 'Weekly' | 'Monthly';
+            type: 'Always' | 'OneTime' | 'Recurring' | 'Daily' | 'Weekly' | 'Monthly';
             maxRuns: number;
         };
         frequencyType?: string;
     };
 }
 
-/**
- * Initialize DAP SDK with optional user context
- */
-declare function init(opts: {
+/** Options passed to {@link DapSDK.init}. */
+interface DapInitOptions {
+    /** URL to the DAP configuration JSON (required). */
     configUrl: string;
+    /** Enable verbose [DAP] console logging. Default: false. */
     debug?: boolean;
+    /** Logical screen/view identifier for location-based flow matching. */
     screenId?: string;
+    /** Authenticated user context. Can also be provided later via {@link DapSDK.setUser}. */
     user?: DapUser;
-}): Promise<void>;
+}
+/** A single step inside a {@link DapFlowDefinition}. */
+interface DapFlowStep {
+    id?: string;
+    /** Experience type: 'tooltip' | 'modal' | 'banner' | 'survey' | 'walkthrough' | etc. */
+    type: string;
+    trigger?: {
+        selector?: string;
+        type?: string;
+        placement?: string;
+    };
+    content: Record<string, any>;
+}
+/** An inline flow definition used with {@link DapSDK.executeFlow}. */
+interface DapFlowDefinition {
+    id: string;
+    name?: string;
+    steps: DapFlowStep[];
+    execution?: {
+        mode?: string;
+        multiPage?: boolean;
+        frequency?: {
+            type?: string;
+            maxRuns?: number;
+        };
+    };
+    /** @deprecated Use execution.mode instead. */
+    executionMode?: string;
+    /** @deprecated Use execution.multiPage instead. */
+    isMultiPage?: boolean;
+}
+/** The complete public API surface of the DAP SDK. */
+interface DapSDK {
+    /**
+     * Initialize the SDK. Must be called once before any other method.
+     * Fetches remote config, sets user/location context, and starts eligible flows.
+     *
+     * @example
+     * await dap.init({ configUrl: 'https://cdn.example.com/config.json', screenId: 'home' });
+     */
+    init(opts: DapInitOptions): Promise<void>;
+    /** Set (or replace) the authenticated user context. Triggers pending flows. */
+    setUser(user: DapUser): void;
+    /** Merge partial fields into the existing user context. */
+    updateUser(partialUser: Partial<DapUser>): void;
+    /** Return the current user, or null if not set. */
+    getUser(): DapUser | null;
+    /** Clear the user context. */
+    clearUser(): void;
+    /**
+     * Register a pre-fetched or locally-defined flow for later use via {@link startFlow}.
+     * The registry is capped at 50 entries; oldest entries are evicted when exceeded.
+     */
+    registerFlow(flowData: FlowData): void;
+    /**
+     * Start a flow by ID. Checks the in-memory registry first, then fetches from backend.
+     * Throws if the flow cannot be resolved.
+     */
+    startFlow(flowId: string): Promise<void>;
+    /**
+     * Execute an inline flow definition immediately without registering it.
+     * Ideal for A/B experiments, feature flags, and integration tests.
+     *
+     * @example
+     * await dap.executeFlow({
+     *   id: 'quick-tip',
+     *   steps: [{ type: 'tooltip', trigger: { selector: '#save-btn' }, content: { text: 'Save here!' } }]
+     * });
+     */
+    executeFlow(flow: DapFlowDefinition): Promise<void>;
+    /**
+     * Reset the run-count / completion record for a specific flow (or all flows)
+     * stored in localStorage.
+     *
+     * Use this when a flow that has reached its `maxRuns` limit should be allowed
+     * to run again — e.g. after a user logs out, completes an upgrade, or during
+     * development / testing.
+     *
+     * @param flowId - ID of the flow to reset. Omit to reset **all** flows.
+     *
+     * @example
+     * // Reset a single flow
+     * dap.resetFlowRuns('019cc85a-5712-7dcd-a17f-ef116293fa41');
+     *
+     * // Reset every flow (e.g. on sign-out)
+     * dap.resetFlowRuns();
+     */
+    resetFlowRuns(flowId?: string): void;
+}
+declare global {
+    interface Window {
+        DAP: DapSDK;
+    }
+}
+/**
+ * Initialize DAP SDK with optional user context
+ */
+declare function init(opts: DapInitOptions): Promise<void>;
 /**
  * Set user context and trigger flow re-evaluation
  */
@@ -99,15 +196,43 @@ declare function getUser(): DapUser | null;
  * Clear user context
  */
 declare function clearUser(): void;
-declare function runModalSequence(): void;
-declare function executeFlow(flow: any): Promise<void>;
 /**
- * Register a flow for later execution by ID
+ * Reset the run-count / completion record for a flow (or all flows) stored in localStorage.
+ *
+ * The engine tracks three keys per flow:
+ *   - `dap_flow_runs_<id>`        — cumulative run counter (OneTime / Recurring)
+ *   - `dap_flow_completed_<id>`   — completion marker (OneTime)
+ *   - `dap_flow_last_run_<id>`    — last-run timestamp (Daily / Weekly / Monthly)
+ *
+ * @param flowId - The flow ID to reset. Omit (or pass `undefined`) to reset ALL flows.
+ */
+declare function resetFlowRuns(flowId?: string): void;
+declare function executeFlow(flow: DapFlowDefinition): Promise<void>;
+/**
+ * Register a flow for later execution by ID.
+ * Evicts the oldest entry when the map exceeds MAX_REGISTERED_FLOWS to prevent
+ * unbounded growth in long-running SPAs.
  */
 declare function registerFlow(flowData: FlowData): void;
 /**
  * Start a flow by ID (from registered flows or backend)
  */
 declare function startFlow(flowId: string): Promise<void>;
+/**
+ * The DAP SDK singleton — the primary way to interact with the SDK.
+ *
+ * **ESM / bundler (React, Vue, Angular, etc.):**
+ * ```ts
+ * import { dap } from '@cognior/iap-sdk';
+ * await dap.init({ configUrl: 'https://cdn.example.com/config.json', screenId: 'home' });
+ * ```
+ *
+ * **Script tag (plain HTML):**
+ * ```html
+ * <script src="https://cdn.example.com/iap-sdk.umd.js"></script>
+ * <script>DAP.init({ configUrl: '...' });</script>
+ * ```
+ */
+declare const dap: DapSDK;
 
-export { type DapUser, clearUser, executeFlow, getUser, init, registerFlow, runModalSequence, setUser, startFlow, updateUser };
+export { type DapFlowDefinition, type DapFlowStep, type DapInitOptions, type DapSDK, type DapUser, type FlowData, clearUser, dap, executeFlow, getUser, init, registerFlow, resetFlowRuns, setUser, startFlow, updateUser };