@digia-engage/core 1.1.0 → 2.0.0-rc.1

package/src/types.ts

@@ -12,7 +12,9 @@ export interface InAppPayload {
     cepContext: Record<string, unknown>;
 }
 
-// ─── Experience events ────────────────────────────────────────────────────────
+export type CampaignType = 'nudge' | 'guide' | 'inline' | 'survey';
+
+// ─── Experience events (CEP lifecycle — used by notifyEvent) ──────────────────
 
 /** The experience became visible to the user. */
 export interface ExperienceImpressed {
@@ -30,11 +32,35 @@ export interface ExperienceDismissed {
     readonly type: 'dismissed';
 }
 
+/** The user completed the experience (advanced past the final step). */
+export interface ExperienceCompleted {
+    readonly type: 'completed';
+}
+
 /** Discriminated union of all experience event types. */
 export type DigiaExperienceEvent =
     | ExperienceImpressed
     | ExperienceClicked
-    | ExperienceDismissed;
+    | ExperienceDismissed
+    | ExperienceCompleted;
+
+// ─── Guide lifecycle events (analytics — used by track()) ────────────────────
+
+export type DismissReason = 'user_close' | 'scrim_tap' | 'back_gesture' | 'auto_timeout';
+
+/**
+ * Rich internal event emitted by guide overlays.
+ * Carries all context needed to build the CEP analytics property schema.
+ * Not part of the public plugin API — converted to track() calls in Digia.ts.
+ */
+export type GuideLifecycleEvent =
+    | { type: 'viewed'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight' }
+    | { type: 'step_viewed'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight' }
+    | { type: 'clicked'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight'; ctaLabel: string; actionType: string; actionUrl?: string; elementId?: string }
+    | { type: 'step_clicked'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight'; ctaLabel: string; actionType: string; actionUrl?: string; elementId?: string }
+    | { type: 'dismissed'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight'; dismissReason: DismissReason }
+    | { type: 'step_dismissed'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight'; dismissReason: DismissReason }
+    | { type: 'completed'; stepIndex: number; stepTotal: number; anchorKey: string; displayStyle: 'tooltip' | 'spotlight' };
 
 /**
  * Delegate passed by the Digia SDK to each registered plugin via setup().
@@ -65,18 +91,63 @@ export interface DigiaPlugin {
      * analytics back to their CEP platform.
      */
     notifyEvent(event: DigiaExperienceEvent, payload: InAppPayload): void;
+    /**
+     * Called by the Digia SDK to record a named analytics event with properties.
+     * Implement this to forward Digia lifecycle events (e.g. "Digia Experience Viewed")
+     * to the CEP platform's custom event API.
+     */
+    track?(eventName: string, properties: Record<string, unknown>): void;
     /** Called by Digia.setCurrentScreen() — do not call manually. */
     forwardScreen(name: string): void;
     /** Called by Digia.unregister() or when tearing down the app. */
     teardown(): void;
 }
 
+// ─── Action types (public API) ────────────────────────────────────────────────
+
+export type DigiaAction =
+    | { type: 'deep_link'; url: string; fallback_url?: string }
+    | { type: 'open_url'; url: string; presentation: 'external' | 'in_app' }
+    | { type: 'dismiss'; scope?: 'self' | 'all' }
+    | { type: 'next' }
+    | { type: 'back' };
+
+export type ActionContext = {
+    campaign_id: string;
+    campaign_key: string;
+    campaign_type: 'nudge' | 'guide' | 'inline' | 'survey';
+    source: {
+        kind: 'button' | 'card_tap' | 'pip_small_view' | 'auto_dismiss';
+        element_id?: string;
+        button_label?: string;
+    };
+    step_index?: number;
+    step_total?: number;
+    source_node?: unknown;
+};
+
+export type ActionResult = boolean | Promise<boolean> | void;
+
+export type OnAction = (action: DigiaAction, context: ActionContext) => ActionResult;
+
+export type InAppBrowserAdapter = {
+    open: (url: string) => Promise<void>;
+};
+
+// ─── SDK init config ──────────────────────────────────────────────────────────
+
 /**
  * Configuration for initialising the Digia Engage SDK.
  */
 export interface DigiaConfig {
-    /** The API key provided by Digia. */
-    apiKey: string;
+    /** The Engage project ID — sent as x-digia-project-id on all SDK requests. */
+    projectId: string;
+    /**
+     * Base URL for the Digia API.
+     * Defaults to the production API root, or the Engage sandbox root when
+     * `environment` is "sandbox".
+     */
+    baseUrl?: string;
     /**
      * The target environment.
      * @default 'production'
@@ -87,5 +158,31 @@ export interface DigiaConfig {
      * @default 'error'
      */
     logLevel?: 'none' | 'error' | 'verbose';
+    /**
+     * Optional global font family applied to all Digia-rendered text.
+     * Must match a font available to the native app — an Android system/registered
+     * family name, or an iOS bundled font's PostScript name.
+     */
+    fontFamily?: string;
+    /**
+     * Optional override hook called for every action before the SDK runs its
+     * default behavior. Return true to suppress the default; false/void lets
+     * the SDK handle it.
+     */
+    onAction?: OnAction;
+    /**
+     * URL / linking configuration.
+     */
+    linking?: {
+        /**
+         * When true (default) the SDK calls Linking.openURL for URL-bearing actions.
+         * @default true
+         */
+        routeViaSystemLinking?: boolean;
+        /**
+         * Required if any campaign uses open_url with presentation: 'in_app'.
+         * Falls back to Linking.openURL + emits inapp_browser_unavailable if absent.
+         */
+        inAppBrowser?: InAppBrowserAdapter;
+    };
 }
-