@connect-xyz/withdraw-js 0.34.0 → 0.36.0

package/README.md

@@ -68,6 +68,9 @@ const withdraw = new Withdraw({
   onEvent: ({ type, data }) => {
     console.log('Event received:', type, data);
   },
+  onLoaded: () => {
+    console.log('Withdraw widget loaded and ready');
+  },
 });
 
 // Render the widget to a container element
@@ -101,6 +104,7 @@ withdraw.destroy();
 | `onClose`      | `() => void`                      | No       | -              | Callback when the widget is closed                 |
 | `onWithdrawal` | `({ data }) => void`              | No       | -              | Callback for withdrawal completed                  |
 | `onEvent`      | `({ type, data }) => void`        | No       | -              | Callback for general events                        |
+| `onLoaded`     | `() => void`                      | No       | -              | Callback when the widget is loaded and ready       |
 
 ### Constructor
 
@@ -119,6 +123,7 @@ Creates a new Withdraw instance with the provided configuration.
   - `onClose` (function, optional): Close callback
   - `onWithdrawal` (function, optional): Withdrawal callback
   - `onEvent` (function, optional): General event callback
+  - `onLoaded` (function, optional): Callback when widget is loaded and ready
 
 ### Methods
 
@@ -214,6 +219,16 @@ onEvent: ({ type, data }) => {
 };
 ```
 
+### onLoaded
+
+Called when the Withdraw widget has fully loaded and is ready for user interaction. This callback is useful for showing loading states or performing actions once the widget is initialized.
+
+```javascript
+onLoaded: () => {
+  // Widget is fully loaded and ready
+};
+```
+
 ## Browser Support
 
 - Chrome/Edge 90+

package/dist/index.d.ts

@@ -32,11 +32,13 @@ declare interface BaseConfig<TEvent = AppEvent> extends CommonCallbacks<TEvent>
      * JWT token used for authentication
      */
     jwt: string;
+
     /**
      * Target environment
      * @default 'production'
      */
     env?: Environment;
+
     /**
      * Theme mode
      * @default 'auto'
@@ -49,54 +51,259 @@ declare interface BaseConfig<TEvent = AppEvent> extends CommonCallbacks<TEvent>
     theme?: Theme;
 }
 
-declare type BaseErrorMessageKeys = 'ALREADY_RENDERED' | 'NOT_RENDERED' | 'INVALID_CONTAINER' | 'SCRIPT_LOAD_FAILED' | 'WEB_COMPONENT_NOT_DEFINED';
+declare type BaseErrorMessageKeys =
+| 'ALREADY_RENDERED'
+| 'NOT_RENDERED'
+| 'INVALID_CONTAINER'
+| 'SCRIPT_LOAD_FAILED'
+| 'WEB_COMPONENT_NOT_DEFINED';
 
 declare abstract class BaseJsSdk<Config extends BaseConfig<never> = BaseConfig> {
-    private config;
-    private state;
-    private scriptLoadingPromise?;
+    private config: Config;
+    private state: SdkState;
+    private scriptLoadingPromise?: Promise<void>;
+
     protected abstract errorMessages: Record<BaseErrorMessageKeys, string>;
     protected abstract scriptUrls: Record<string, string>;
     protected abstract webComponentTag: string;
-    constructor(config: Config);
+
+    constructor(config: Config) {
+        if (!config.jwt || typeof config.jwt !== 'string') {
+            throw new Error(INVALID_JWT_ERROR_MESSAGE);
+        }
+
+        this.config = {
+            ...config,
+            env: config.env || DEFAULT_ENVIRONMENT,
+            theme: config.theme,
+        };
+
+        this.state = {
+            initialized: false,
+            scriptLoaded: false,
+            container: null,
+            element: null,
+        };
+    }
+
     /**
      * Render the widget to a container element
      * @param container - The container element to render the widget into
      * @returns Promise that resolves when the widget is rendered
      */
-    render(container: HTMLElement): Promise<void>;
+    async render(container: HTMLElement): Promise<void> {
+        // Validate container
+        if (!container || !(container instanceof HTMLElement)) {
+            throw new Error(this.errorMessages.INVALID_CONTAINER);
+        }
+
+        // Check if already rendered
+        if (this.state.initialized) {
+            throw new Error(this.errorMessages.ALREADY_RENDERED);
+        }
+
+        try {
+            // Ensure script is loaded
+            await this.ensureScriptLoaded();
+
+            // Create and append the web component
+            const element = this.createWebComponent();
+
+            // Clear the container and append the element
+            container.innerHTML = '';
+            container.appendChild(element);
+
+            // Update state
+            this.state.container = container;
+            this.state.element = element;
+            this.state.initialized = true;
+        } catch (error) {
+            console.error('Failed to render widget:', error);
+            throw error;
+        }
+    }
+
     /**
      * Update the configuration of the widget
      * @param config - Partial configuration to update
      * @returns void
      */
-    updateConfig(config: Partial<Config>): void;
+    updateConfig(config: Partial<Config>): void {
+        if (!this.state.initialized || !this.state.element) {
+            throw new Error(this.errorMessages.NOT_RENDERED);
+        }
+
+        const element = this.state.element as SdkElement<Config>;
+
+        Object.entries(config).forEach(([key, value]) => {
+            if (value) {
+                this.config[key as keyof Config] = value;
+                element[key as keyof Config] = value;
+            }
+        });
+    }
+
     /**
      * Destroy the widget and clean up resources
      */
-    destroy(): void;
+    destroy(): void {
+        if (!this.state.initialized) {
+            return; // Nothing to destroy
+        }
+
+        // Remove the element from the container
+        if (this.state.element && this.state.element.parentNode) {
+            this.state.element.parentNode.removeChild(this.state.element);
+        }
+
+        // Clear the container
+        if (this.state.container) {
+            this.state.container.innerHTML = '';
+        }
+
+        // Reset state
+        this.state.container = null;
+        this.state.element = null;
+        this.state.initialized = false;
+    }
+
     /**
      * Check if the widget is currently rendered
      * @returns True if the widget is rendered, false otherwise
      */
-    isRendered(): boolean;
+    isRendered(): boolean {
+        return this.state.initialized;
+    }
+
     /**
      * Get the current configuration
      * @returns The current configuration object
      */
-    getConfig(): Readonly<Config>;
-    private getEnvironment;
-    private getScriptId;
-    private isScriptLoaded;
-    private getWebComponent;
-    private getScriptUrl;
-    private loadScript;
-    private waitForWebComponent;
+    getConfig(): Readonly<Config> {
+        return { ...this.config };
+    }
+
+    private getEnvironment(): Environment {
+        return this.config.env || DEFAULT_ENVIRONMENT;
+    }
+
+    private getScriptId() {
+        return `${this.webComponentTag}-script-${this.getEnvironment()}`;
+    }
+
+    private isScriptLoaded() {
+        return !!document.getElementById(this.getScriptId());
+    }
+
+    private getWebComponent() {
+        return customElements.get(this.webComponentTag);
+    }
+
+    private getScriptUrl() {
+        // Support local development with Vite
+        if (typeof import.meta !== 'undefined' && import.meta.env?.['VITE_INTERNAL_BUILD'] === 'true') {
+            return import.meta.env['VITE_SCRIPT_URL'] || this.scriptUrls[this.getEnvironment()];
+        }
+
+        return this.scriptUrls[this.getEnvironment()];
+    }
+
+    private async loadScript() {
+        if (this.isScriptLoaded()) {
+            return;
+        }
+
+        if (this.scriptLoadingPromise) {
+            return this.scriptLoadingPromise;
+        }
+
+        this.scriptLoadingPromise = new Promise<void>((resolve, reject) => {
+            const script = document.createElement('script');
+            script.id = this.getScriptId();
+            script.src = this.getScriptUrl();
+            script.type = 'module';
+            script.async = true;
+
+            script.onload = () => {
+                setTimeout(() => {
+                    if (this.getWebComponent()) {
+                        resolve();
+                    } else {
+                        reject(new Error(this.errorMessages.WEB_COMPONENT_NOT_DEFINED));
+                    }
+                }, 0);
+            };
+
+            script.onerror = () => {
+                this.scriptLoadingPromise = undefined;
+                reject(new Error(`${this.errorMessages.SCRIPT_LOAD_FAILED} (${this.getEnvironment()})`));
+            };
+
+            document.head.appendChild(script);
+        });
+
+        try {
+            await this.scriptLoadingPromise;
+        } catch (error) {
+            this.scriptLoadingPromise = undefined;
+            throw error;
+        }
+
+        return this.scriptLoadingPromise;
+    }
+
+    private async waitForWebComponent(timeout = 5000) {
+        if (this.getWebComponent()) {
+            return;
+        }
+
+        return new Promise<void>((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Timeout waiting for ${this.webComponentTag} to be defined`));
+            }, timeout);
+
+            customElements
+            .whenDefined(this.webComponentTag)
+            .then(() => {
+                clearTimeout(timeoutId);
+                resolve();
+            })
+            .catch((error) => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+
     /**
      * Load the web component script if not already loaded
      */
-    protected ensureScriptLoaded(): Promise<void>;
-    private createWebComponent;
+    protected async ensureScriptLoaded(): Promise<void> {
+        if (this.state.scriptLoaded) {
+            return;
+        }
+
+        try {
+            await this.loadScript();
+            await this.waitForWebComponent();
+            this.state.scriptLoaded = true;
+        } catch (error) {
+            console.error('Failed to load Connect script:', error);
+            throw error;
+        }
+    }
+
+    private createWebComponent() {
+        const element = document.createElement(this.webComponentTag) as SdkElement<Config>;
+
+        Object.entries(this.config).forEach(([key, value]) => {
+            if (value) {
+                element[key as keyof Config] = value;
+            }
+        });
+
+        return element;
+    }
 }
 
 /**
@@ -110,6 +317,8 @@ declare type CommonCallbacks<TEvent = AppEvent> = {
     onClose?: () => void;
     /** Called when a general event occurs */
     onEvent?: (event: TEvent) => void;
+    /** Called when the widget has loaded and is ready */
+    onLoaded?: () => void;
 };
 
 export declare type ConnectWithdrawElement = SdkElement<WithdrawConfig>;
@@ -154,6 +363,20 @@ declare type ErrorPayload = {
  */
 declare type SdkElement<Config extends BaseConfig<never>> = HTMLElement & Config;
 
+/**
+ * Internal state of the SDK
+ */
+declare interface SdkState {
+    /** Whether the SDK is initialized */
+    initialized: boolean;
+    /** Whether the web component script is loaded */
+    scriptLoaded: boolean;
+    /** The container element where the widget is rendered */
+    container: HTMLElement | null;
+    /** The web component element */
+    element: HTMLElement | null;
+}
+
 /**
  * Theme configuration for the SDK
  *
@@ -175,7 +398,8 @@ declare type Theme = 'auto' | 'light' | 'dark';
  *   onError: ({ error, reason }) => console.error(error, reason),
  *   onClose: () => console.log('Withdraw closed'),
  *   onWithdrawal: ({ data }) => console.log('Withdrawal', data),
- *   onEvent: ({ type, data }) => console.log('Event', type, data)
+ *   onEvent: ({ type, data }) => console.log('Event', type, data),
+ *   onLoaded: () => console.log('Withdraw widget loaded and ready')
  * });
  *
  * // Render to a container

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connect-xyz/withdraw-js",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",