despia-native 1.0.0 → 1.0.1

package/README.md

@@ -27,11 +27,11 @@ npm install despia
 ```javascript
 import despia from 'despia';
 
-// Execute a Despia protocol command (no response)
-await despia('lighthaptic://');
+// Execute a Despia protocol command (no response needed)
+despia('lighthaptic://');
 
-// Execute command and watch for response variables
-const result = await despia('getappversion://', ['versionNumber', 'bundleNumber'], 5000);
+// Execute command and watch for response variables (await needed)
+const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
 console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
 ```
 
@@ -39,74 +39,74 @@ console.log(result); // { versionNumber: '1.0.0', bundleNumber: '123' }
 
 ```javascript
 // Native Widgets
-await despia('widget://${svg}?refresh=${refresh_time}');
+despia('widget://${svg}?refresh=${refresh_time}');
 
 // RevenueCat In-App Purchases
-await despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');
+despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');
 
 // Contact Permissions
-await despia('requestcontactpermission://');
+despia('requestcontactpermission://');
 const contacts = await despia('readcontacts://', ['contacts']);
 
 // Background Location
-await despia('backgroundlocationon://');
+despia('backgroundlocationon://');
 // Use native browser geolocation API (not despia wrapper)
 const watchId = navigator.geolocation.watchPosition(
   (position) => console.log('Location:', position),
   (error) => console.error('Location error:', error)
 );
 // To stop
-await despia('backgroundlocationoff://');
+despia('backgroundlocationoff://');
 navigator.geolocation.clearWatch(watchId);
 
 // Push Notifications
-await despia('registerpush://');
-await despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
+despia('registerpush://');
+despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
 const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);
 
 // Haptic Feedback
-await despia('lighthaptic://');
-await despia('heavyhaptic://');
-await despia('successhaptic://');
-await despia('warninghaptic://');
-await despia('errorhaptic://');
+despia('lighthaptic://');
+despia('heavyhaptic://');
+despia('successhaptic://');
+despia('warninghaptic://');
+despia('errorhaptic://');
 
 // App Information
 const appInfo = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
 const deviceInfo = await despia('get-uuid://', ['uuid']);
 
 // Screenshots and Scanning
-await despia('takescreenshot://');
-await despia('scanningmode://auto');
-await despia('scanningmode://on');
-await despia('scanningmode://off');
+despia('takescreenshot://');
+despia('scanningmode://auto');
+despia('scanningmode://on');
+despia('scanningmode://off');
 
 // Store and Location
 const storeData = await despia('getstorelocation://', ['storeLocation']);
 
 // Image and File Operations
-await despia('savethisimage://?url=${image_url}');
-await despia('file://${file_url}');
+despia('savethisimage://?url=${image_url}');
+despia('file://${file_url}');
 
 // App Control
-await despia('reset://');
+despia('reset://');
 const trackingData = await despia('user-disable-tracking://', ['trackingDisabled']);
 
 // UI Controls
-await despia('spinneron://');
-await despia('spinneroff://');
-await despia('hidebars://on');
-await despia('hidebars://off');
+despia('spinneron://');
+despia('spinneroff://');
+despia('hidebars://on');
+despia('hidebars://off');
 
 // Sharing
-await despia('shareapp://message?=${message}&url=${url}');
+despia('shareapp://message?=${message}&url=${url}');
 
 // Status Bar Styling
-await despia('statusbarcolor://{255, 255, 255}');
-await despia('statusbartextcolor://{black}');
+despia('statusbarcolor://{255, 255, 255}');
+despia('statusbartextcolor://{black}');
 
 // Biometric Authentication
-await despia('bioauth://');
+despia('bioauth://');
 ```
 
 ### Direct Window Variable Access
@@ -121,13 +121,13 @@ const appVersion = despia.appVersion;
 ### Advanced Usage with Variable Watching
 
 ```javascript
-// Watch multiple response variables with custom timeout
-const appData = await despia('getappversion://', ['versionNumber', 'bundleNumber'], 15000);
+// Watch multiple response variables
+const appData = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
 
 // Chain multiple Despia commands
-await despia('lighthaptic://');
-await despia('getappversion://', ['versionNumber', 'bundleNumber']);
-await despia('successhaptic://');
+despia('lighthaptic://');
+const appData2 = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
+despia('successhaptic://');
 ```
 
 ### Background Location Workflow
@@ -136,7 +136,7 @@ Background location tracking requires a two-step process:
 
 ```javascript
 // Step 1: Enable native background location tracking via Despia
-await despia('backgroundlocationon://');
+despia('backgroundlocationon://');
 
 // Step 2: Use native browser geolocation API for actual tracking (not despia wrapper)
 const watchId = navigator.geolocation.watchPosition(
@@ -160,7 +160,7 @@ const watchId = navigator.geolocation.watchPosition(
 
 // To stop tracking:
 // Step 1: Disable native background tracking via Despia
-await despia('backgroundlocationoff://');
+despia('backgroundlocationoff://');
 // Step 2: Clear browser geolocation watch (native API)
 navigator.geolocation.clearWatch(watchId);
 ```
@@ -169,7 +169,7 @@ navigator.geolocation.clearWatch(watchId);
 
 ```javascript
 // Step 1: Request contact permission
-await despia('requestcontactpermission://');
+despia('requestcontactpermission://');
 
 // Step 2: Read contacts after permission granted
 const contactData = await despia('readcontacts://', ['contacts']);
@@ -182,13 +182,13 @@ All haptic feedback commands have no response - they provide immediate tactile f
 
 ```javascript
 // Basic haptic feedback
-await despia('lighthaptic://');    // Light haptic feedback - subtle vibration
-await despia('heavyhaptic://');    // Heavy haptic feedback - strong vibration
+despia('lighthaptic://');    // Light haptic feedback - subtle vibration
+despia('heavyhaptic://');    // Heavy haptic feedback - strong vibration
 
 // Contextual haptic feedback
-await despia('successhaptic://');  // Success haptic feedback - positive confirmation
-await despia('warninghaptic://');  // Warning haptic feedback - attention alert
-await despia('errorhaptic://');    // Error haptic feedback - negative feedback
+despia('successhaptic://');  // Success haptic feedback - positive confirmation
+despia('warninghaptic://');  // Warning haptic feedback - attention alert
+despia('errorhaptic://');    // Error haptic feedback - negative feedback
 
 // Use cases:
 // - Button press feedback (light/heavy)
@@ -248,7 +248,7 @@ window.bioauthUnavailable = function() {
 }
 
 // Step 3: Trigger biometric authentication
-await despia('bioauth://');
+despia('bioauth://');
 ```
 
 ### App Information & Device Data
@@ -329,8 +329,6 @@ Access native safe area insets via CSS custom properties:
 .my-element {
   padding-top: var(--safe-area-top);
   padding-bottom: var(--safe-area-bottom);
-  padding-left: var(--safe-area-left);
-  padding-right: var(--safe-area-right);
 }
 
 /* Full height with safe area consideration */
@@ -339,19 +337,22 @@ Access native safe area insets via CSS custom properties:
 }
 ```
 
+**Note:** Despia only supports top and bottom safe area insets. Left and right safe area variables are not available.
+
 These CSS variables are automatically provided by the Despia native runtime and represent the device's safe area insets (notches, home indicators, etc.).
 
 
 
 ## API Reference
 
-### `despia(command, watch?, timeout?)`
+### `despia(command, watch?)`
 
-- **command** (string): The Despia protocol command (e.g., `'applinks://open?url=...'`)
+- **command** (string): The Despia protocol command (e.g., `'lighthaptic://'`)
 - **watch** (string[], optional): Array of variable names to watch for in the response
-- **timeout** (number, optional): Timeout in milliseconds (default: 10000)
 
-Returns a Promise that resolves when all watched variables are available or timeout is reached.
+Returns a Promise that resolves when all watched variables are available:
+- **Single variable**: 5-second timeout with simple observation
+- **Multiple variables**: Uses VariableTracker with 5-minute auto-cleanup
 
 ### Direct Property Access
 

package/index.d.ts

@@ -4,7 +4,6 @@
  * Despia protocol command types
  */
 type DespiaCommand = 
-  | `applinks://${string}`
   | `widget://${string}`
   | `revenuecat://${string}`
   | `requestcontactpermission://`
@@ -70,16 +69,15 @@ interface DespiaFunction {
    * Execute a Despia protocol command and watch for specific response variables
    * @param command - The Despia protocol command
    * @param watch - Array of variable names to watch for in the response
-   * @param timeout - Timeout in milliseconds (default: 10000)
-   * @returns Promise that resolves with the watched variables or times out
+   * @returns Promise that resolves with the watched variables
    * 
    * @example
    * ```typescript
-   * const result = await despia('biometric://authenticate', ['authResult', 'userID']);
-   * const purchase = await despia('purchase://product?sku=premium', ['purchaseResult', 'transactionID']);
+   * const result = await despia('getappversion://', ['versionNumber', 'bundleNumber']);
+   * const purchase = await despia('revenuecat://purchase?external_id=user_777&product=monthly_premium', ['purchaseResult', 'transactionID']);
    * ```
    */
-  <T = Record<string, any>>(command: DespiaCommand, watch: string[], timeout?: number): Promise<T>;
+  <T = Record<string, any>>(command: DespiaCommand, watch: string[]): Promise<T>;
   
   /**
    * Access any window variable directly (useful for Despia response data)

package/index.js

@@ -0,0 +1,184 @@
+// index.js
+(function (root, factory) {
+    if (typeof define === 'function' && define.amd) {
+      define([], factory);
+    } else if (typeof module === 'object' && module.exports) {
+      module.exports = factory();
+    } else {
+      root.despia = factory();
+    }
+  }(typeof self !== 'undefined' ? self : this, function () {
+    'use strict';
+  
+    // Command queue for sequential execution
+    const commandQueue = [];
+    let processing = false;
+  
+    // Process command queue with 1ms delay between commands
+    function processQueue() {
+      if (processing || commandQueue.length === 0) return;
+      
+      processing = true;
+      const { command, native } = commandQueue.shift();
+      
+      try {
+        native({ command });
+      } catch (e) {}
+      
+      setTimeout(() => {
+        processing = false;
+        processQueue();
+      }, 1);
+    }
+  
+    // Add command to queue
+    function queueCommand(command) {
+      const native = typeof window !== 'undefined' 
+        ? window.despia 
+        : (typeof global !== 'undefined' ? global.despia : null);
+      
+      if (native) {
+        commandQueue.push({ command, native });
+        processQueue();
+      }
+    }
+  
+    // Simple variable observer with 5-second timeout
+    function observeDespiaVariable(variableName, callback, timeout = 5000) {
+        const startTime = Date.now();
+        
+        function checkVariable() {
+            if (window[variableName] !== undefined) {
+                callback(window[variableName]);
+            } else if (Date.now() - startTime < timeout) {
+                setTimeout(checkVariable, 100);
+            } else {
+                console.error(`Despia timeout: ${variableName} was not set within ${timeout} ms`);
+            }
+        }
+        
+        checkVariable();
+    }
+
+    // VariableTracker class for complex multi-variable observation
+    class VariableTracker {
+        constructor(variables, onReady) {
+            this.variables = variables;
+            this.onReady = onReady;
+            this.triggered = false;
+            this.processing = false;
+            
+            // Create tracker element
+            this.tracker = document.createElement('div');
+            this.tracker.style.display = 'none';
+            document.body.appendChild(this.tracker);
+            
+            // Setup observer with debounce
+            let timeout;
+            this.observer = new MutationObserver(() => {
+                clearTimeout(timeout);
+                timeout = setTimeout(() => this.check(), 100);
+            });
+            
+            // Start observing and checking
+            this.observer.observe(this.tracker, { attributes: true });
+            this.check();
+            this.interval = setInterval(() => this.check(), 1000);
+        }
+
+        check() {
+            if (this.processing || this.triggered) return;
+            this.processing = true;
+
+            try {
+                const values = {};
+                const allSet = this.variables.every(name => {
+                    const val = window[name];
+                    // Check for undefined, "n/a" string, or null values
+                    if (val === undefined || val === "n/a" || val === null) return false;
+                    values[name] = val;
+                    return true;
+                });
+
+                if (allSet && !this.triggered) {
+                    this.triggered = true;
+                    this.cleanup();
+                    this.onReady(values);
+                }
+            } catch (err) {
+                console.error("Error during check:", err);
+            }
+            
+            this.processing = false;
+        }
+
+        cleanup() {
+            this.observer.disconnect();
+            clearInterval(this.interval);
+            this.tracker.remove();
+        }
+    }
+
+    // Observe variables - simple for single variable, tracker for multiple
+    function observeVariables(variables, timeout) {
+        if (!variables || variables.length === 0) {
+            return Promise.resolve({});
+        }
+
+        if (variables.length === 1) {
+            // Simple single variable observation with 5-second timeout
+            return new Promise((resolve) => {
+                observeDespiaVariable(variables[0], (value) => {
+                    resolve({ [variables[0]]: value });
+                }, 5000);
+            });
+        } else {
+            // Multiple variables - use VariableTracker (no timeout, expires after 5 minutes)
+            return new Promise((resolve) => {
+                const tracker = new VariableTracker(variables, resolve);
+                // Auto-cleanup after 5 minutes if not triggered
+                setTimeout(() => {
+                    if (!tracker.triggered) {
+                        tracker.cleanup();
+                        resolve({});
+                    }
+                }, 300000); // 5 minutes
+            });
+        }
+    }
+  
+    // Main despia function
+    function despiaFunction(command, watch = []) {
+      // Queue command execution
+      queueCommand(command);
+      
+      // No variables to watch
+      if (!watch || watch.length === 0) {
+        return Promise.resolve();
+      }
+      
+      // Watch for variables (timeout handled internally)
+      return observeVariables(watch);
+    }
+  
+    // Create proxy for window access
+    const despia = new Proxy(despiaFunction, {
+      get(target, prop) {
+        if (prop in target || prop === 'then' || typeof prop === 'symbol') {
+          return target[prop];
+        }
+        
+        if (typeof window !== 'undefined' && prop in window) {
+          return window[prop];
+        }
+        
+        return undefined;
+      },
+      
+      apply(target, thisArg, args) {
+        return target(...args);
+      }
+    });
+  
+    return despia;
+  }));

package/package.json

@@ -1,17 +1,37 @@
 {
     "name": "despia-native",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "JavaScript SDK for Despia native integrations with command queuing and variable watching",
     "main": "index.js",
     "module": "index.js",
     "types": "index.d.ts",
-    "keywords": ["despia", "sdk", "mobile", "native", "bridge", "applinks", "biometric", "purchase", "push", "camera", "location", "download", "haptic", "widget", "revenuecat", "contacts"],
+    "keywords": [
+        "despia",
+        "sdk",
+        "mobile",
+        "native",
+        "bridge",
+        "applinks",
+        "biometric",
+        "purchase",
+        "push",
+        "camera",
+        "location",
+        "download",
+        "haptic",
+        "widget",
+        "revenuecat",
+        "contacts"
+    ],
     "author": "Despia Native <developers@despia.com>",
     "license": "MIT",
-
     "scripts": {
         "test": "echo \"No tests specified\"",
         "prepublishOnly": "npm test"
     },
-    "files": ["index.js", "index.d.ts", "README.md"]
-   }
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "README.md"
+    ]
+}