@superleapai/flow-ui 1.0.2 → 2.2.1

package/index.d.ts

@@ -6,7 +6,7 @@ declare module "@superleapai/flow-ui" {
   // ============================================================================
   // SUPERLEAP SDK
   // ============================================================================
-  
+
   export interface SuperLeapConfig {
     apiKey?: string;
     baseUrl?: string;
@@ -25,11 +25,135 @@ declare module "@superleapai/flow-ui" {
     };
   }
 
+  // ============================================================================
+  // CRM BRIDGE TYPES
+  // ============================================================================
+
+  /** Configuration passed to SuperLeap.connect() */
+  export interface ConnectOptions {
+    /** Unique identifier for this flow/form (must match CRM-side registration) */
+    flowId: string;
+    /** Expected CRM origin for validation (e.g., "https://app.superleap.com"). Optional for RN. */
+    crmOrigin?: string;
+    /** Whether to auto-call SuperLeap.init() with the SDK config from the CRM. Default: true */
+    autoInit?: boolean;
+    /** Handshake timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+  }
+
+  /** Context data provided by the CRM during handshake */
+  export interface CRMContext {
+    /** Organization ID */
+    orgId: string;
+    /** Current user ID */
+    userId: string;
+    /** Record ID (if iframe is in a record context) */
+    recordId?: string;
+    /** Object slug (e.g., "accounts", "contacts") */
+    objectSlug?: string;
+    /** Form ID (if iframe is inside a form) */
+    formId?: string;
+    /** Component ID within the form */
+    componentId?: string;
+    /** Any additional context data */
+    [key: string]: any;
+  }
+
+  /** Configuration received from the CRM */
+  export interface CRMConfig {
+    /** SDK configuration for SuperLeap.init() */
+    sdkConfig?: SuperLeapConfig;
+    /** Any additional configuration */
+    [key: string]: any;
+  }
+
+  /** Result of a successful SuperLeap.connect() call */
+  export interface ConnectResult {
+    /** Context data from the CRM */
+    context: CRMContext;
+    /** Configuration from the CRM */
+    config: CRMConfig;
+  }
+
+  /** Unsubscribe function returned by SuperLeap.on() */
+  export type EventUnsubscribe = () => void;
+
   export interface SuperLeap {
+    // SDK Methods (from superleapClient.js)
     init(config?: SuperLeapConfig): void;
     getSdk(): any;
     isAvailable(): boolean;
     getDefaultConfig(): SuperLeapConfig;
+
+    // Bridge Methods (from crm.js)
+
+    /**
+     * Connect to the CRM via postMessage bridge.
+     * Performs handshake, receives config, optionally auto-initializes the SDK.
+     * @returns Promise that resolves with context and config from the CRM
+     */
+    connect(options: ConnectOptions): Promise<ConnectResult>;
+
+    /** Check if the bridge is connected to the CRM */
+    isConnected(): boolean;
+
+    /** Disconnect from the CRM and clean up listeners */
+    disconnect(): void;
+
+    /**
+     * Tell the CRM to show or hide a loading overlay
+     * @param loading - Whether to show loading state
+     */
+    setLoading(loading: boolean): void;
+
+    /** Tell the CRM to close the current form/modal */
+    closeForm(): void;
+
+    /**
+     * Tell the CRM to show a toast notification
+     * @param message - Toast message
+     * @param type - Toast type
+     * @param duration - Duration in milliseconds
+     */
+    toast(
+      message: string,
+      type?: "success" | "error" | "warning" | "info",
+      duration?: number
+    ): void;
+
+    /**
+     * Tell the CRM to navigate to a path
+     * @param path - Navigation path
+     */
+    navigate(path: string): void;
+
+    /**
+     * Get the context data received from the CRM during handshake
+     * @returns Context object or null if not connected
+     */
+    getContext(): CRMContext | null;
+
+    /**
+     * Send a custom event to the CRM
+     * @param event - Event name
+     * @param payload - Event data
+     */
+    send(event: string, payload?: any): void;
+
+    /**
+     * Listen for a custom event from the CRM
+     * @param event - Event name
+     * @param callback - Handler function
+     * @returns Unsubscribe function
+     */
+    on(event: string, callback: (payload: any) => void): EventUnsubscribe;
+
+    /**
+     * Remove a specific event listener
+     * @param event - Event name
+     * @param callback - The same callback that was passed to on()
+     */
+    off(event: string, callback: (payload: any) => void): void;
   }
 
   export const SuperLeap: SuperLeap;
@@ -37,7 +161,7 @@ declare module "@superleapai/flow-ui" {
   // ============================================================================
   // STATE MANAGEMENT
   // ============================================================================
-  
+
   export interface FlowUIState {
     [key: string]: any;
   }
@@ -45,7 +169,19 @@ declare module "@superleapai/flow-ui" {
   export interface ButtonConfig {
     text?: string;
     label?: string;
-    variant?: "primary" | "outline" | "ghost" | "link" | "primaryDestructive" | "outlineDestructive" | "ghostDestructive" | "dashed" | "toggleOff" | "toggleOn" | "ghostInline" | "linkInline";
+    variant?:
+      | "primary"
+      | "outline"
+      | "ghost"
+      | "link"
+      | "primaryDestructive"
+      | "outlineDestructive"
+      | "ghostDestructive"
+      | "dashed"
+      | "toggleOff"
+      | "toggleOn"
+      | "ghostInline"
+      | "linkInline";
     size?: "small" | "medium" | "default" | "large";
     type?: "button" | "submit" | "reset";
     disabled?: boolean;
@@ -62,7 +198,13 @@ declare module "@superleapai/flow-ui" {
     required?: boolean;
     type?: "text" | "email" | "number" | "password" | "tel" | "url";
     helpText?: string;
-    variant?: "default" | "error" | "warning" | "success" | "borderless" | "inline";
+    variant?:
+      | "default"
+      | "error"
+      | "warning"
+      | "success"
+      | "borderless"
+      | "inline";
     inputSize?: "default" | "large" | "small";
     disabled?: boolean;
     showReadOnlyIcon?: boolean;
@@ -223,7 +365,13 @@ declare module "@superleapai/flow-ui" {
     required?: boolean;
     onChange?: (value: number | null) => void;
     disabled?: boolean;
-    variant?: "default" | "error" | "warning" | "success" | "borderless" | "inline";
+    variant?:
+      | "default"
+      | "error"
+      | "warning"
+      | "success"
+      | "borderless"
+      | "inline";
     size?: "small" | "default" | "large";
     helpText?: string;
   }
@@ -239,7 +387,13 @@ declare module "@superleapai/flow-ui" {
     onChange?: (count: number) => void;
     disabled?: boolean;
     readOnly?: boolean;
-    variant?: "default" | "error" | "warning" | "success" | "borderless" | "inline";
+    variant?:
+      | "default"
+      | "error"
+      | "warning"
+      | "success"
+      | "borderless"
+      | "inline";
     size?: "default" | "large" | "small";
     helpText?: string;
   }
@@ -387,7 +541,10 @@ declare module "@superleapai/flow-ui" {
 
   export interface FlowUI {
     // State management
-    initState(initialState: FlowUIState, onChangeCallback?: (state: FlowUIState) => void): void;
+    initState(
+      initialState: FlowUIState,
+      onChangeCallback?: (state: FlowUIState) => void
+    ): void;
     getState(): FlowUIState;
     setState(partial: Partial<FlowUIState>): void;
     get(key: string): any;
@@ -399,7 +556,11 @@ declare module "@superleapai/flow-ui" {
     // Screen utilities
     createScreen(title: string, description: string): HTMLElement;
     createGrid(): HTMLElement;
-    createFieldWrapper(label: string, required?: boolean, helpText?: string | null): HTMLElement;
+    createFieldWrapper(
+      label: string,
+      required?: boolean,
+      helpText?: string | null
+    ): HTMLElement;
 
     // Form components
     createInput(config: InputConfig): HTMLElement;
@@ -422,11 +583,29 @@ declare module "@superleapai/flow-ui" {
     createButton(config: ButtonConfig): HTMLElement;
 
     // Stepper
-    renderStepper(container: HTMLElement, steps: StepConfig[], currentStepId: string): void;
+    renderStepper(
+      container: HTMLElement,
+      steps: StepConfig[],
+      currentStepId: string
+    ): void;
 
     // Alerts & Toasts
-    showToast(message: string, type?: "success" | "error" | "warning" | "info" | "loading", duration?: number): ToastAPI;
-    renderAlerts(container: HTMLElement, messages?: (string | { title?: string; description?: string })[], type?: "error" | "info" | "success" | "warning" | "destructive" | "default"): void;
+    showToast(
+      message: string,
+      type?: "success" | "error" | "warning" | "info" | "loading",
+      duration?: number
+    ): ToastAPI;
+    renderAlerts(
+      container: HTMLElement,
+      messages?: (string | { title?: string; description?: string })[],
+      type?:
+        | "error"
+        | "info"
+        | "success"
+        | "warning"
+        | "destructive"
+        | "default"
+    ): void;
 
     // Table
     createDataTable(config: DataTableConfig): HTMLElement;