@salla.sa/embedded-sdk 0.1.0-beta.6 → 0.1.0-beta.9

package/dist/types/index.d.ts

@@ -1,42 +1,122 @@
+/**
+ * Callback for action button clicks.
+ */
+declare type ActionClickCallback = (url?: string, value?: string) => void;
+
 /**
  * Auth module interface.
  */
 export declare interface AuthModule {
     /**
-     * Get the current access token.
-     * @returns The access token or undefined if not authenticated
-     */
-    getAccessToken(): string | undefined;
-    /**
-     * Check if the SDK is authenticated.
+     * Get the token from the URL query parameter.
+     * The token is passed to the iframe via ?token=XXX
+     * @returns The token string or null if not present
      */
-    isAuthenticated(): boolean;
+    getToken(): string | null;
     /**
-     * Get the current store ID.
+     * Get the app ID from the URL query parameter.
+     * The app ID is passed to the iframe via ?app_id=XXX
+     * @returns The app ID string or null if not present
      */
-    getStoreId(): number | undefined;
+    getAppId(): string | null;
     /**
-     * Get the current user ID.
+     * Request a token refresh from the host.
+     * This will re-render the iframe with a new token URL.
      */
-    getUserId(): number | undefined;
+    refresh(): void;
     /**
-     * Get the merchant plan.
+     * Introspect (verify) a short-lived token with Salla's API.
+     * This method verifies the token and returns token information.
+     *
+     * @param options - Optional parameters (appId, token, and autoRetry). If not provided, will be extracted from URL params.
+     * @returns Promise that resolves with the introspect response. On API errors, resolves with isVerified: false, isError: true, and empty data.
+     * @throws {Error} If appId or token is missing (validation errors only)
+     *
+     * @example
+     * ```typescript
+     * // With explicit parameters
+     * const result = await embedded.auth.introspect({
+     *   appId: 'my-app-id',
+     *   token: 'short-lived-token'
+     * });
+     *
+     * // Using URL params (fallback, autoRetry enabled by default)
+     * const result = await embedded.auth.introspect();
+     *
+     * // Disable auto-retry on error
+     * const result = await embedded.auth.introspect({ autoRetry: false });
+     * ```
      */
-    getMerchantPlan(): string | undefined;
+    introspect(options?: IntrospectOptions): Promise<IntrospectResponse>;
+}
+
+/**
+ * Checkout module interface.
+ */
+export declare interface CheckoutModule {
     /**
-     * Request a token refresh from the host.
+     * Create/initiate a checkout flow.
+     *
+     * @param payload - Checkout data
+     *
+     * @example
+     * ```typescript
+     * embedded.checkout.create({
+     *   items: [{ productId: 123, quantity: 1 }],
+     *   amount: 99.99,
+     *   currency: 'SAR'
+     * });
+     * ```
      */
-    refreshToken(): void;
+    create(payload: CheckoutPayload): void;
+}
+
+/**
+ * @fileoverview Type definitions for the checkout module.
+ */
+/**
+ * Checkout payload structure.
+ */
+export declare interface CheckoutPayload {
+    /** Cart items or product IDs */
+    items?: unknown[];
+    /** Total amount */
+    amount?: number;
+    /** Currency code */
+    currency?: string;
+    /** Additional checkout data */
+    [key: string]: unknown;
 }
 
 /**
- * Breadcrumb item.
+ * Confirm dialog options.
  */
-export declare interface BreadcrumbItem {
-    label: string;
-    path?: string;
+export declare interface ConfirmOptions {
+    /** Dialog title */
+    title: string;
+    /** Dialog message/body */
+    message: string;
+    /** Text for the confirm button (default: "Confirm") */
+    confirmText?: string;
+    /** Text for the cancel button (default: "Cancel") */
+    cancelText?: string;
+    /** Visual variant for the dialog (default: "info") */
+    variant?: ConfirmVariant;
 }
 
+/**
+ * Confirm dialog result.
+ */
+export declare interface ConfirmResult {
+    /** Whether the user confirmed (true) or cancelled (false) */
+    confirmed: boolean;
+}
+
+/**
+ * Confirm dialog variant.
+ */
+export declare type ConfirmVariant = "danger" | "warning" | "info";
+
 export declare const embedded: EmbeddedApp;
 
 /**
@@ -46,15 +126,22 @@ export declare const embedded: EmbeddedApp;
 export declare class EmbeddedApp {
     private config;
     private state;
+    private themeCallbacks;
+    private initCallbacks;
+    private appReady;
     /** Auth module for token management */
     auth: AuthModule;
-    /** Page module for loading, overlay, navigation */
+    /** Page module for navigation and resize */
     page: PageModule;
     /** Nav module for primary actions */
     nav: NavModule;
+    /** UI module for loading, overlay, toast, modal */
+    ui: UIModule;
+    /** Checkout module for checkout flow */
+    checkout: CheckoutModule;
     constructor();
     /**
-     * Get current SDK state.
+     * Get current SDK state (layout info only, no token).
      */
     getState(): Readonly<EmbeddedState>;
     /**
@@ -62,40 +149,106 @@ export declare class EmbeddedApp {
      */
     getConfig(): Readonly<EmbeddedConfig>;
     /**
-     * Check if SDK is ready.
+     * Check if SDK is initialized.
      */
     isReady(): boolean;
     /**
-     * Log debug messages if debug mode is enabled.
+     * Unified internal logging function that supports all console log types.
+     *
+     * @param type - Log type (log, warn, error, info, debug)
+     * @param args - Arguments to log
+     */
+    private internalLog;
+    /**
+     * Set up listener for theme changes from host.
      */
-    private log;
+    private setupThemeListener;
     /**
-     * Log warnings.
+     * Set up listeners for async response events from host.
      */
-    private warn;
+    private setupResponseListeners;
     /**
-     * Initialize the SDK and establish connection with the host.
+     * Subscribe to theme changes.
      *
-     * @param options - Initialization options
-     * @returns Promise that resolves when SDK is ready
+     * @param callback - Function called when theme changes
+     * @returns Unsubscribe function
      *
      * @example
      * ```typescript
-     * await salla.embedded.init({
-     *   app_id: 'my-app-123',
-     *   env: 'prod',
-     *   debug: true
+     * const unsubscribe = embedded.onThemeChange((theme) => {
+     *   document.body.classList.toggle('dark-mode', theme === 'dark');
      * });
      * ```
      */
-    init(options: InitOptions): Promise<EmbeddedState>;
+    onThemeChange(callback: ThemeChangeCallback): () => void;
+    /**
+     * Subscribe to init completion. If called after init, fires immediately.
+     *
+     * @param callback - Function called when init completes
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * embedded.onInit((state) => {
+     *   console.log('SDK initialized with layout:', state.layout);
+     * });
+     * ```
+     */
+    onInit(callback: InitCallback): () => void;
+    /**
+     * Send log message to host for debugging/monitoring.
+     *
+     * @param level - Log level (info, warn, error)
+     * @param message - Log message
+     * @param context - Additional context
+     *
+     * @example
+     * ```typescript
+     * embedded.log('error', 'Failed to load data', { endpoint: '/api/data' });
+     * ```
+     */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Signal that the app is fully loaded and ready.
+     * This removes the host's loading overlay.
+     *
+     * @example
+     * ```typescript
+     * // After verifying token and loading initial data
+     * embedded.ready();
+     * ```
+     */
+    ready(): void;
+    /**
+     * Initialize the SDK and establish connection with the host.
+     *
+     * @param options - Initialization options (optional)
+     * @returns Promise that resolves with layout info
+     *
+     * @example
+     * ```typescript
+     * const { layout } = await embedded.init({ debug: true });
+     * console.log('Theme:', layout.theme);
+     * console.log('Locale:', layout.locale);
+     * ```
+     */
+    init(options?: InitOptions): Promise<{
+        layout: LayoutInfo;
+    }>;
     /**
-     * Wait for the SDK to be ready.
+     * Wait for initialization to complete.
      * Useful when multiple calls to init() might happen.
      */
-    private waitForReady;
+    private waitForInit;
     /**
      * Destroy the SDK instance and clean up resources.
+     * Sends a destroy event to the host to navigate away from the embedded view.
+     *
+     * @example
+     * ```typescript
+     * // On auth failure or when app needs to exit
+     * embedded.destroy();
+     * ```
      */
     destroy(): void;
 }
@@ -104,8 +257,6 @@ export declare class EmbeddedApp {
  * Internal configuration after initialization.
  */
 declare interface EmbeddedConfig {
-    appId: string;
-    env: Environment;
     debug: boolean;
     initialized: boolean;
 }
@@ -114,42 +265,24 @@ declare interface EmbeddedConfig {
  * Current state of the embedded SDK.
  */
 export declare interface EmbeddedState {
-    /** Whether the SDK is ready and authenticated */
+    /** Whether the SDK is ready */
     ready: boolean;
     /** Whether initialization is in progress */
     initializing: boolean;
-    /** Authentication token from the host */
-    token?: string;
-    /** Store ID from merchant context */
-    storeId?: number;
-    /** User ID from merchant context */
-    userId?: number;
-    /** Merchant plan */
-    merchantPlan?: string;
-    /** Current dark mode state */
-    isDarkMode?: boolean;
-    /** Parent window width */
-    parentWidth?: number;
-    /** Base URL of the host */
-    baseUrl?: string;
-    /** Base API URL */
-    baseApiUrl?: string;
+    /** Layout information from the host */
+    layout: LayoutInfo;
 }
 
-/**
- * @fileoverview Core type definitions for the Embedded SDK.
- */
-/**
- * Environment mode for the SDK.
- */
-export declare type Environment = "prod" | "dev";
-
 /**
  * Extended action for navigation.
  */
 export declare interface ExtendedAction {
     title: string;
+    subTitle?: string;
     url?: string;
+    value?: string;
+    icon?: string;
+    disabled?: boolean;
 }
 
 /**
@@ -157,107 +290,277 @@ export declare interface ExtendedAction {
  */
 export declare function getEmbeddedApp(): EmbeddedApp;
 
+/**
+ * Init callback type for onInit subscribers.
+ */
+declare type InitCallback = (state: EmbeddedState) => void;
+
 /**
  * Options for initializing the embedded SDK.
  */
 export declare interface InitOptions {
-    /** The unique identifier for the app */
-    app_id: string;
-    /** Environment mode (defaults to 'prod') */
-    env?: Environment;
     /** Enable debug logging */
     debug?: boolean;
 }
 
 /**
- * Loading mode for the page.
+ * Options for the introspect method.
+ */
+declare interface IntrospectOptions {
+    /** Application ID (audience). If not provided, will be extracted from URL params. */
+    appId?: string;
+    /** Short-lived token. If not provided, will be extracted from URL params. */
+    token?: string;
+    /** Automatically refresh token on error (default: true) */
+    autoRetry?: boolean;
+}
+
+/**
+ * Response from the introspect API.
+ */
+declare interface IntrospectResponse {
+    /** Whether the token was verified successfully */
+    isVerified: boolean;
+    /** Whether an error occurred */
+    isError: boolean;
+    /** Error content if an error occurred */
+    error?: unknown;
+    /** Response data */
+    data: IntrospectResponseData;
+}
+
+/**
+ * Response data from the introspect API.
+ */
+declare interface IntrospectResponseData {
+    /** Token ID */
+    id: number;
+    /** User ID */
+    user_id: number;
+    /** Expiration time in ISO 8601 format */
+    exp: string;
+}
+
+/**
+ * Layout information from the host.
+ */
+declare interface LayoutInfo {
+    /** Current theme */
+    theme: Theme;
+    /** Parent window width */
+    width: number;
+    /** Current locale */
+    locale: string;
+    /** Current currency */
+    currency: string;
+}
+
+/**
+ * Loading mode.
  */
 export declare type LoadingMode = "full" | "component";
 
+/**
+ * Loading sub-module interface.
+ */
+declare interface LoadingSubModule {
+    /**
+     * Show loading indicator.
+     * @param mode - Loading display mode
+     *
+     * @example
+     * ```typescript
+     * embedded.ui.loading.show();
+     * await fetchData();
+     * embedded.ui.loading.hide();
+     * ```
+     */
+    show(mode?: LoadingMode): void;
+    /**
+     * Hide loading indicator.
+     */
+    hide(): void;
+}
+
+/**
+ * Log level type.
+ */
+declare type LogLevel = "info" | "warn" | "error";
+
+/**
+ * Modal action types.
+ */
+export declare type ModalAction = "open" | "close";
+
+/**
+ * Modal action type.
+ */
+declare type ModalAction_2 = "open" | "close";
+
+/**
+ * Modal control options.
+ */
+export declare interface ModalOptions {
+    /** Modal action */
+    action: ModalAction_2;
+    /** Modal identifier */
+    id?: string;
+    /** Modal content/data */
+    content?: unknown;
+}
+
+/**
+ * Modal sub-module interface.
+ */
+declare interface ModalSubModule {
+    /**
+     * Open a modal.
+     * @param id - Modal identifier
+     * @param content - Modal content/data
+     *
+     * @example
+     * ```typescript
+     * embedded.ui.modal.open('confirm-delete', { itemId: 123 });
+     * ```
+     */
+    open(id?: string, content?: unknown): void;
+    /**
+     * Close a modal.
+     * @param id - Modal identifier
+     */
+    close(id?: string): void;
+}
+
 /**
  * Nav module interface.
  */
 export declare interface NavModule {
     /**
-     * Set the primary action button in the navigation.
+     * Set the primary action button in the navbar.
      *
-     * @param config - Primary action configuration
+     * @param config - Action button configuration
      *
      * @example
      * ```typescript
-     * salla.embedded.nav.primaryAction({
+     * embedded.nav.setAction({
      *   title: 'Create Product',
-     *   url: '/products/create',
+     *   onClick: () => {
+     *     // Handle click
+     *   }
+     * });
+     *
+     * // With optional props
+     * embedded.nav.setAction({
+     *   title: 'Save',
+     *   subTitle: 'Save changes',
+     *   icon: 'sicon-save',
+     *   disabled: false,
+     *   onClick: () => {
+     *     handleSave();
+     *   }
+     * });
+     *
+     * // With extended actions dropdown
+     * embedded.nav.setAction({
+     *   title: 'Actions',
+     *   value: 'main-action',
      *   extendedActions: [
-     *     { title: 'Import Products', url: '/products/import' },
-     *     { title: 'Bulk Edit', url: '/products/bulk-edit' }
+     *     { title: 'Import', url: '/import' },
+     *     { title: 'Export', value: 'export' }
      *   ]
      * });
      * ```
      */
-    primaryAction(config: PrimaryActionConfig): void;
+    setAction(config: PrimaryActionConfig): void;
     /**
      * Clear the primary action button.
+     *
+     * @example
+     * ```typescript
+     * embedded.nav.clearAction();
+     * ```
+     */
+    clearAction(): void;
+    /**
+     * Subscribe to action button click events.
+     *
+     * @param callback - Function called when action is clicked
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = embedded.nav.onActionClick((url, value) => {
+     *   if (value === 'export') {
+     *     handleExport();
+     *   }
+     * });
+     * ```
+     */
+    onActionClick(callback: ActionClickCallback): Unsubscribe;
+    /**
+     * @deprecated Use setAction instead
+     */
+    primaryAction(config: PrimaryActionConfig): void;
+    /**
+     * @deprecated Use clearAction instead
      */
     clearPrimaryAction(): void;
 }
 
 /**
- * Navigation options.
+ * @fileoverview Type definitions for the page module.
  */
-export declare interface NavToOptions {
-    /** Navigation mode */
-    mode?: "iframe" | "redirect";
-}
-
 /**
- * Overlay action.
+ * Options for navigation.
  */
-export declare type OverlayAction = "open" | "close";
+export declare interface NavToOptions {
+    /** State to pass to the route */
+    state?: Record<string, unknown>;
+    /** Replace history entry instead of push */
+    replace?: boolean;
+}
 
 /**
  * Page module interface.
  */
 export declare interface PageModule {
     /**
-     * Set the loading state of the page.
+     * Navigate to a path using React Router (SPA navigation).
+     * Use this for internal dashboard paths.
      *
-     * @param status - true to show loading complete, false for loading
-     * @param mode - Loading mode ('full' or 'component')
+     * @param path - The path to navigate to
+     * @param options - Navigation options
      *
      * @example
      * ```typescript
-     * // Show loading
-     * salla.embedded.page.loading(false);
-     *
-     * // Hide loading (content ready)
-     * salla.embedded.page.loading(true);
+     * embedded.page.navigate('/products');
+     * embedded.page.navigate('/orders', { replace: true });
      * ```
      */
-    loading(status: boolean, mode?: LoadingMode): void;
+    navigate(path: string, options?: NavToOptions): void;
     /**
-     * Control the overlay state.
+     * Redirect to a URL (full page reload).
+     * Use this for external URLs or when a full reload is needed.
      *
-     * @param action - 'open' or 'close'
+     * @param url - The URL to redirect to
      *
      * @example
      * ```typescript
-     * salla.embedded.page.overlay('open');
-     * // ... show modal content
-     * salla.embedded.page.overlay('close');
+     * embedded.page.redirect('https://external-site.com');
      * ```
      */
-    overlay(action: OverlayAction): void;
+    redirect(url: string): void;
     /**
-     * Navigate to a path.
+     * Navigate to a path - auto-detects internal vs external.
+     * Internal paths use React Router, external URLs use redirect.
      *
-     * @param path - The path to navigate to
-     * @param options - Navigation options
+     * @param path - The path or URL to navigate to
+     * @param options - Navigation options (only for internal paths)
      *
      * @example
      * ```typescript
-     * salla.embedded.page.navTo('/products');
-     * salla.embedded.page.navTo('https://external.com', { mode: 'redirect' });
+     * embedded.page.navTo('/products'); // SPA navigation
+     * embedded.page.navTo('https://external.com'); // Full redirect
      * ```
      */
     navTo(path: string, options?: NavToOptions): void;
@@ -265,36 +568,54 @@ export declare interface PageModule {
      * Update the iframe height.
      *
      * @param height - Height in pixels
+     *
+     * @example
+     * ```typescript
+     * embedded.page.resize(800);
+     * ```
      */
     resize(height: number): void;
     /**
-     * Set breadcrumb items.
+     * Auto-resize iframe to content height.
+     * Measures document.documentElement.scrollHeight and sends resize.
      *
-     * @param items - Array of breadcrumb items
+     * @example
+     * ```typescript
+     * // After content changes
+     * embedded.page.autoResize();
+     * ```
+     */
+    autoResize(): void;
+    /**
+     * Set the page title in the host document.
+     *
+     * @param title - The title to set
      *
      * @example
      * ```typescript
-     * salla.embedded.page.setBreadcrumbs([
-     *   { label: 'Home', path: '/' },
-     *   { label: 'Products', path: '/products' },
-     *   { label: 'Current Product' }
-     * ]);
+     * embedded.page.setTitle('Product Details');
      * ```
      */
-    setBreadcrumbs(items: BreadcrumbItem[]): void;
+    setTitle(title: string): void;
 }
 
 /**
- * Primary action configuration.
+ * Configuration for the primary action button.
  */
 export declare interface PrimaryActionConfig {
     /** Button title */
     title: string;
-    /** URL to navigate to when clicked (optional) */
-    url?: string;
-    /** Custom value to send back on click */
+    /** Callback function to execute when clicked (replaces url) */
+    onClick?: () => void;
+    /** Custom value for identifying the action (passed to onClick callback) */
     value?: string;
-    /** Extended actions for dropdown menu */
+    /** Optional subtitle */
+    subTitle?: string;
+    /** Optional icon class name */
+    icon?: string;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Extended dropdown actions */
     extendedActions?: ExtendedAction[];
 }
 
@@ -303,6 +624,141 @@ export declare interface PrimaryActionConfig {
  */
 export declare function resetEmbeddedApp(): void;
 
-export declare const version = "0.1.0";
+/**
+ * @fileoverview Core type definitions for the Embedded SDK.
+ */
+/**
+ * Theme type for the SDK.
+ */
+declare type Theme = "light" | "dark";
+
+/**
+ * Theme change callback type.
+ */
+declare type ThemeChangeCallback = (theme: "light" | "dark") => void;
+
+/**
+ * Toast notification options.
+ */
+export declare interface ToastOptions {
+    /** Toast type */
+    type: ToastType_2;
+    /** Message to display */
+    message: string;
+    /** Duration in milliseconds (optional) */
+    duration?: number;
+}
+
+/**
+ * Toast sub-module interface.
+ */
+declare interface ToastSubModule {
+    /**
+     * Show a toast notification.
+     * @param options - Toast configuration
+     *
+     * @example
+     * ```typescript
+     * embedded.ui.toast.show({
+     *   type: 'success',
+     *   message: 'Product saved!',
+     *   duration: 3000
+     * });
+     * ```
+     */
+    show(options: ToastOptions): void;
+    /**
+     * Show success toast.
+     * @param message - Message to display
+     * @param duration - Duration in ms
+     */
+    success(message: string, duration?: number): void;
+    /**
+     * Show error toast.
+     * @param message - Message to display
+     * @param duration - Duration in ms
+     */
+    error(message: string, duration?: number): void;
+    /**
+     * Show warning toast.
+     * @param message - Message to display
+     * @param duration - Duration in ms
+     */
+    warning(message: string, duration?: number): void;
+    /**
+     * Show info toast.
+     * @param message - Message to display
+     * @param duration - Duration in ms
+     */
+    info(message: string, duration?: number): void;
+}
+
+/**
+ * Toast notification types.
+ */
+export declare type ToastType = "success" | "error" | "warning" | "info";
+
+/**
+ * Toast type.
+ */
+declare type ToastType_2 = "success" | "error" | "warning" | "info";
+
+/**
+ * UI module interface with nested sub-modules.
+ */
+export declare interface UIModule {
+    /**
+     * Loading state control.
+     */
+    loading: LoadingSubModule;
+    /**
+     * Toast notifications.
+     */
+    toast: ToastSubModule;
+    /**
+     * Modal control.
+     */
+    modal: ModalSubModule;
+    /**
+     * Show a confirmation dialog and wait for user response.
+     *
+     * @param options - Confirm dialog options
+     * @returns Promise that resolves with the user's choice
+     *
+     * @example
+     * ```typescript
+     * const result = await embedded.ui.confirm({
+     *   title: 'Delete Product?',
+     *   message: 'This action cannot be undone.',
+     *   confirmText: 'Delete',
+     *   variant: 'danger',
+     * });
+     * if (result.confirmed) {
+     *   // User confirmed
+     * }
+     * ```
+     */
+    confirm(options: ConfirmOptions): Promise<ConfirmResult>;
+}
+
+/**
+ * Unsubscribe function returned by message listeners.
+ */
+declare type Unsubscribe = () => void;
+
+/**
+ * @fileoverview Validation types for SDK payload validation.
+ */
+/**
+ * Result of a validation check.
+ */
+export declare interface ValidationResult {
+    /** Whether the validation passed */
+    valid: boolean;
+    /** Array of error messages if validation failed */
+    errors: string[];
+}
+
+export declare const version: string;
 
 export { }