despia-native 1.0.17 → 1.0.20

package/README.md

@@ -91,11 +91,23 @@ Our visual editor allows you to configure native widgets, shortcuts, and dynamic
 ## Installation (REQUIRED - NO EXCEPTIONS)
 
 ```bash
+# npm
 npm install despia-native
+
+# pnpm
+pnpm install despia-native
+
+# yarn
+yarn add despia-native
 ```
 
 **This is NOT optional. Your app will NOT work without this package.**
 
+**Package Manager Support:**
+- ✅ **npm** - Fully supported
+- ✅ **pnpm** - Fully supported (v1.0.19+)
+- ✅ **yarn** - Fully supported
+
 **Do not attempt to:**
 - Write your own version
 - Copy/paste a mock implementation  
@@ -333,6 +345,30 @@ despia('widget://${svg}?refresh=${refresh_time}');
 // RevenueCat In-App Purchases
 despia('revenuecat://purchase?external_id=user_777&product=monthly_premium');
 
+// Restore Purchases
+const purchaseData = await despia("getpurchasehistory://", ["restoredData"]);
+
+// RevenueCat Paywalls
+despia('revenuecat://launchPaywall?external_id=user_777&offering=default');
+
+// Identity Vault
+await despia(`setvault://?key=userId&value=user123&locked=false`);
+const vaultData = await despia(`readvault://?key=userId`, ['userId']);
+
+// OAuth Authentication
+despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
+
+// Local Storage
+const encoded = encodeURIComponent(JSON.stringify(userData));
+await despia(`writevalue://${encoded}`);
+const data = await despia("readvalue://", ["storedValues"]);
+
+// Read Clipboard
+const clipboardData = await despia('getclipboard://', ['clipboarddata']);
+
+// Open App Settings
+despia("settingsapp://");
+
 // Contact Permissions
 despia('requestcontactpermission://');
 const contacts = await despia('readcontacts://', ['contacts']);
@@ -351,7 +387,8 @@ navigator.geolocation.clearWatch(watchId);
 // Push Notifications
 despia('registerpush://');
 despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
-const oneSignalData = await despia('getonesignalplayerid://', ['onesignalplayerid']);
+// Set OneSignal external user ID (call on every app load)
+despia(`setonesignalplayerid://?user_id=${YOUR_LOGGED_IN_USER_ID}`);
 
 // Haptic Feedback
 despia('lighthaptic://');
@@ -465,6 +502,529 @@ const contactData = await despia('readcontacts://', ['contacts']);
 console.log('Contacts:', contactData.contacts);
 ```
 
+### RevenueCat Paywall Workflow
+
+Create a payment system that uses RevenueCat Paywalls by launching native paywall interfaces configured in your RevenueCat dashboard:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Launch a paywall for a specific offering
+despia('revenuecat://launchPaywall?external_id=USER_ID&offering=default');
+
+// Example offerings you might configure:
+// - "default" - your main offering
+// - "premium" - premium tier offering
+// - "annual_sale" - special promotional offering
+```
+
+**Handling Purchase Success:**
+
+The Despia Native Runtime will call the global function `onRevenueCatPurchase()` when an in-app purchase or subscription is successfully made on the client side. Although this should not grant access immediately, it's a good time to start polling your backend to check if the RevenueCat webhook has already updated the user's status or plan permissions.
+
+```javascript
+// Define the global callback function
+window.onRevenueCatPurchase = function() {
+  console.log('Purchase successful! Polling backend for status update...');
+  
+  // Start polling your backend to check if RevenueCat webhook
+  // has updated the user's status or plan permissions
+  // This ensures you don't grant access before the webhook processes
+};
+```
+
+This will launch a native paywall interface configured in your RevenueCat dashboard, handling purchases through Apple App Store and Google Play billing.
+
+### Identity Vault Workflow
+
+The identity vault provides persistent, cross-device storage with optional biometric protection:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Store identity data
+await despia(`setvault://?key=${keyName}&value=${value}&locked=${isLocked}`);
+
+// Retrieve identity data
+const data = await despia(`readvault://?key=${keyName}`, [keyName]);
+const value = data[keyName];
+```
+
+**Parameters:**
+
+- **key** - Name for your stored data (use simple names like "userId", "deviceId", "sessionToken")
+- **value** - The data to store (text/string)
+- **locked** - Set to `'true'` to require Face ID/fingerprint, `'false'` for normal storage
+
+**Features:**
+
+- **Persistent storage** - Data survives app restarts, updates, and even uninstall/reinstall
+- **Cross-device sync** - Works across all user's devices with the same Apple ID or Google account
+- **User tracking** - Identify the same user even after they uninstall and reinstall your app
+- **Face ID protection** - Optional biometric lock for sensitive actions
+- **Automatic timeout** - 30-second timeout prevents app freezing
+
+**Perfect for:**
+
+- Identifying users across sessions
+- Preventing free trial abuse (track device even after uninstall)
+- Storing login session tokens
+- Protecting sensitive actions with Face ID/Touch ID
+- Saving user preferences and app settings
+
+**Example Usage:**
+
+```javascript
+// Store user ID (normal storage)
+await despia(`setvault://?key=userId&value=user123&locked=false`);
+
+// Store session token with biometric protection
+await despia(`setvault://?key=sessionToken&value=abc123xyz&locked=true`);
+
+// Retrieve stored data
+const userData = await despia(`readvault://?key=userId`, ['userId']);
+console.log('User ID:', userData.userId);
+
+const sessionData = await despia(`readvault://?key=sessionToken`, ['sessionToken']);
+console.log('Session Token:', sessionData.sessionToken);
+```
+
+### OAuth Authentication Workflow
+
+Launch OAuth authentication in a secure native browser session:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Launch OAuth flow
+const oauthUrl = 'https://your-provider.com/oauth/authorize?client_id=xxx&redirect_uri=xxx';
+despia(`oauth://?url=${encodeURIComponent(oauthUrl)}`);
+```
+
+**How it works:**
+
+1. **Opens secure browser session:**
+   - **iOS**: ASWebAuthenticationSession (secure Safari sheet)
+   - **Android**: Chrome Custom Tabs (secure Chrome overlay)
+
+2. **User completes OAuth** in the secure browser session
+
+3. **Parse tokens from callback URL** - OAuth providers typically return tokens in the URL hash or query parameters:
+   ```javascript
+   // Example: Parse tokens from URL hash (implicit flow)
+   const hash = window.location.hash.substring(1);
+   const hashParams = new URLSearchParams(hash);
+   const accessToken = hashParams.get('access_token');
+   const refreshToken = hashParams.get('refresh_token');
+   ```
+
+4. **Close browser and return to app** - Use your app's deeplink scheme with the `oauth/` prefix:
+   ```javascript
+   // From your callback page (still in secure browser session)
+   window.location.href = `myapp://oauth/auth?access_token=${accessToken}&refresh_token=${refreshToken}`;
+   ```
+
+5. **Handle deeplink in app** - The native app intercepts the deeplink, closes the browser session, and navigates your WebView to the specified path with query parameters.
+
+**Deeplink format:** `{scheme}://oauth/{path}?params`
+
+- `myapp://` - Your app's deeplink scheme
+- `oauth/` - Required prefix that tells native code to close the browser session
+- `{path}` - Where to navigate in your app (e.g., `auth`, `home`, `profile`)
+- `?params` - Query parameters passed to that page
+
+**Examples:**
+- `myapp://oauth/auth?access_token=xxx` - Closes browser, opens `/auth?access_token=xxx`
+- `myapp://oauth/home` - Closes browser, opens `/home`
+- `myapp://oauth/profile?tab=settings` - Closes browser, opens `/profile?tab=settings`
+
+**Perfect for:**
+- Google, Facebook, Apple, GitHub, and other OAuth providers
+- Secure authentication flows without leaving your app
+- Native browser sessions with automatic cleanup
+
+### Local Storage Workflow
+
+Create a local storage system with cross-platform support (data is cleared on app uninstall):
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// This SDK is compatible only with the Native Despia Runtime.
+// Ensure that the User Agent string includes "despia" before running this code.
+// If the User Agent string doesn't include "despia" you can use Local Storage as a web fallback.
+
+// Save data
+const userData = { refresh_token: "SSBMT1ZFIERFU1BJQSBOQVRJVkUgU08gTVVDSCBJIFdBTk5BIEtJU1MgSVQh" };
+const encoded = encodeURIComponent(JSON.stringify(userData));
+await despia(`writevalue://${encoded}`);
+
+// Retrieve data
+const data = await despia("readvalue://", ["storedValues"]);
+const userData = JSON.parse(decodeURIComponent(data.storedValues));
+console.log(userData.refresh_token);
+```
+
+**How it works:**
+
+- **Save data**: Use `writevalue://` with a JSON-encoded string to store data on the device
+- **Retrieve data**: Use `readvalue://` with `["storedValues"]` to get the stored data
+- **Data format**: Data is stored as a single string and returned in the response object
+- **Cross-platform**: Works on both iOS and Android
+- **Lifecycle**: Data persists across app restarts but is cleared on app uninstall
+
+**Important Notes:**
+
+- **Runtime compatibility**: Only works with Despia Native Runtime (check User Agent for "despia")
+- **Web fallback**: Use Local Storage as a fallback if not running in Despia Native Runtime
+- **UI blocking**: Refrain from blocking any UI elements or adding loading screens before data is loaded, as most sessions will not have initial data yet if no data has been stored
+
+**Perfect for:**
+
+- Storing user preferences and settings
+- Caching temporary data
+- Storing session tokens (non-sensitive)
+- App configuration data
+
+### Restore Purchases Workflow
+
+Retrieve purchase history from the native app stores to implement "Restore Purchases" functionality and verify user entitlements:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Retrieve purchase history
+const data = await despia("getpurchasehistory://", ["restoredData"]);
+const purchases = data.restoredData;
+console.log(purchases);
+```
+
+**How it works:**
+
+Despia queries the native platform's billing system to retrieve all purchases associated with the current user's App Store or Google Play account. This includes active subscriptions, expired subscriptions, consumables, and non-consumable (lifetime) purchases. The data is normalized into a consistent format across both iOS and Android platforms.
+
+**Response Structure:**
+
+Each purchase object in the response array includes:
+
+- **transactionId** - Unique identifier for this specific transaction
+- **originalTransactionId** - Identifier linking to the original purchase (useful for subscription renewals)
+- **productId** - The product identifier configured in App Store Connect / Google Play Console
+- **type** - Either `"subscription"` or `"product"` (one-time purchase)
+- **entitlementId** - The entitlement/access level this purchase grants
+- **externalUserId** - External user identifier if configured
+- **isAnonymous** - Boolean indicating if the purchase is anonymous
+- **isActive** - Boolean indicating if the purchase currently grants access
+- **willRenew** - Boolean indicating if a subscription will auto-renew
+- **purchaseDate** - ISO timestamp of the most recent transaction
+- **originalPurchaseDate** - ISO timestamp of the initial purchase
+- **expirationDate** - ISO timestamp when access expires (`null` for lifetime purchases)
+- **store** - Either `"app_store"` or `"play_store"`
+- **country** - User's country code
+- **environment** - `"production"` or `"sandbox"`
+- **receipt** - The raw receipt data for server-side validation
+
+**Example Response (iOS):**
+
+```javascript
+[
+    {
+        "transactionId": "1000000987654321",
+        "originalTransactionId": "1000000123456789",
+        "productId": "com.app.premium.monthly",
+        "type": "subscription",
+        "entitlementId": "premium",
+        "externalUserId": "abc123",
+        "isAnonymous": false,
+        "isActive": true,
+        "willRenew": true,
+        "purchaseDate": "2024-01-15T14:32:05Z",
+        "originalPurchaseDate": "2023-06-20T09:15:33Z",
+        "expirationDate": "2024-02-15T14:32:05Z",
+        "store": "app_store",
+        "country": "USA",
+        "receipt": "MIIbngYJKoZIhvcNAQcCoIIbajCCG2YCAQExDzAN...",
+        "environment": "production"
+    },
+    {
+        "transactionId": "1000000555555555",
+        "originalTransactionId": "1000000555555555",
+        "productId": "com.app.removeads",
+        "type": "product",
+        "entitlementId": "no_ads",
+        "externalUserId": "abc123",
+        "isAnonymous": false,
+        "isActive": true,
+        "willRenew": false,
+        "purchaseDate": "2023-12-01T08:00:00Z",
+        "originalPurchaseDate": "2023-12-01T08:00:00Z",
+        "expirationDate": null,
+        "store": "app_store",
+        "country": "USA",
+        "receipt": "MIIbngYJKoZIhvcNAQcCoIIbajCCG2YCAQExDzAN...",
+        "environment": "production"
+    }
+]
+```
+
+**Example Response (Android):**
+
+```javascript
+[
+    {
+        "transactionId": "GPA.3372-4150-9088-12345",
+        "originalTransactionId": "GPA.3372-4150-9088-12345",
+        "productId": "com.app.premium.monthly",
+        "type": "subscription",
+        "entitlementId": "premium",
+        "externalUserId": "abc123",
+        "isAnonymous": false,
+        "isActive": true,
+        "willRenew": true,
+        "purchaseDate": "2024-01-15T14:32:05Z",
+        "originalPurchaseDate": "2023-06-20T09:15:33Z",
+        "expirationDate": "2024-02-15T14:32:05Z",
+        "store": "play_store",
+        "country": "US",
+        "receipt": "kefhajglhaljhfajkfajk.AO-J1OxBnT3hAjkl5FjpKc9...",
+        "environment": "production"
+    },
+    {
+        "transactionId": "GPA.3372-4150-9088-67890",
+        "originalTransactionId": "GPA.3372-4150-9088-67890",
+        "productId": "com.app.removeads",
+        "type": "product",
+        "entitlementId": "no_ads",
+        "externalUserId": "abc123",
+        "isAnonymous": false,
+        "isActive": true,
+        "willRenew": false,
+        "purchaseDate": "2023-12-01T08:00:00Z",
+        "originalPurchaseDate": "2023-12-01T08:00:00Z",
+        "expirationDate": null,
+        "store": "play_store",
+        "country": "US",
+        "receipt": "minodkpfokbofclncmaa.AO-J1Oy2fXpTml7rKxE3vNc9...",
+        "environment": "production"
+    }
+]
+```
+
+**Check Active Entitlements:**
+
+```javascript
+const data = await despia("getpurchasehistory://", ["restoredData"]);
+const purchases = data.restoredData;
+
+// Filter for active purchases only
+const activePurchases = purchases.filter(p => p.isActive);
+
+// Check if user has premium access
+const hasPremium = activePurchases.some(p => p.entitlementId === "premium");
+
+if (hasPremium) {
+    // Grant premium features
+}
+```
+
+**Perfect for:**
+
+- Implementing "Restore Purchases" buttons required by App Store guidelines
+- Verifying user entitlements on app launch
+- Checking subscription status and renewal information
+- Server-side receipt validation using raw receipt data
+- Cross-platform purchase history retrieval
+
+**Important Notes:**
+
+- This feature requires native capabilities which are fully provided by the `despia-native` npm package
+- No additional native libraries are needed
+- Please follow the installation instructions for the `despia-native` npm package closely
+- Implementation as mentioned is critical for App Store compliance
+
+### Read Clipboard Workflow
+
+Read clipboard data from the device:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Read clipboard data
+const clipboardData = await despia('getclipboard://', ['clipboarddata']);
+
+// Access the clipboard content
+const content = clipboardData.clipboarddata;
+
+// Display or process the clipboard content in your application
+console.log('Clipboard content:', content);
+```
+
+**How it works:**
+
+- **Read clipboard**: Use `getclipboard://` with `['clipboarddata']` to retrieve the current clipboard content
+- **Access content**: The clipboard content is available through the `.clipboarddata` property of the returned object
+- **Native support**: Works on both iOS and Android platforms
+
+**Perfect for:**
+
+- Reading text from the clipboard
+- Processing clipboard content in your app
+- Implementing paste functionality
+- Clipboard content validation
+
+### Open App Settings Workflow
+
+Open your app's native settings page where users can manage permissions:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// Open native app settings
+despia("settingsapp://");
+```
+
+**How it works:**
+
+- **Opens native settings**: Navigates to your app's settings page in the device's system settings
+- **Permission management**: Users can manage permissions like notifications, location, camera, microphone, and more
+- **One-time prompts**: Great for directing users to activate features that you can only ask once, like location or push notifications
+
+**Perfect for:**
+
+- Directing users to enable location services after they've denied the initial prompt
+- Helping users enable push notifications if they initially declined
+- Managing camera, microphone, or other permission settings
+- Providing a way to access app settings when permission prompts can't be shown again
+
+**Example Usage:**
+
+```javascript
+// Check if location permission is needed
+if (!navigator.geolocation) {
+  // Open settings so user can enable location
+  despia("settingsapp://");
+}
+
+// After user denies push notification permission
+// Provide a button to open settings
+function openNotificationSettings() {
+  despia("settingsapp://");
+}
+```
+
+### OneSignal Push Notifications Workflow
+
+Set up OneSignal push notifications with external user IDs to connect your database user IDs with device registrations:
+
+```javascript
+// First, install the package:
+// npm install despia-native
+
+// Then import it:
+import despia from 'despia-native';
+
+// On every app load, set the external user ID
+// This connects your logged-in user ID with the device's OneSignal registration
+despia(`setonesignalplayerid://?user_id=${YOUR_LOGGED_IN_USER_ID}`);
+```
+
+**Setup Requirements:**
+
+1. **Create a OneSignal account** and configure your app
+2. **Set up iOS (Apple Push Key) and Android (Firebase)** configurations in OneSignal
+3. **Important**: When configuring OneSignal, select **"Native iOS"** and **"Native Android"** platforms since Despia apps are native mobile applications
+4. **Add your OneSignal App ID** to your Despia project settings
+
+**How it works:**
+
+- **External User IDs**: External IDs (your database user IDs) are now the default and recommended approach
+- **Player IDs**: Player IDs still work but are no longer suggested
+- **Device Registration**: Devices are automatically registered in OneSignal when the app is installed
+- **User Connection**: Calling `setonesignalplayerid://` on every app load connects your user ID with the device registration
+
+**Backend Integration Required:**
+
+You'll need to create a backend endpoint to send notifications using OneSignal's REST API with external user IDs:
+
+```javascript
+// Backend API endpoint - send to specific user
+const sendNotification = async (externalUserId, title, message) => {
+  const response = await fetch('https://onesignal.com/api/v1/notifications', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Basic YOUR_REST_API_KEY'
+    },
+    body: JSON.stringify({
+      app_id: 'ONESIGNAL-APP-ID',
+      include_external_user_ids: [externalUserId], // Array with single ID
+      headings: { en: title },
+      contents: { en: message }
+    })
+  });
+  return response.json();
+};
+```
+
+**Example Usage:**
+
+```javascript
+// In your app initialization or login flow
+function initializeApp(userId) {
+  // Set external user ID on every app load
+  despia(`setonesignalplayerid://?user_id=${userId}`);
+  
+  // Register for push notifications
+  despia('registerpush://');
+}
+
+// Send local push notification
+despia('sendlocalpushmsg://push.send?s=60&msg=Hello&!#New Message&!#https://myapp.com');
+```
+
+**Important Notes:**
+
+- This feature requires native capabilities which are fully provided by the `despia-native` npm package
+- No additional native libraries are needed
+- Please follow the installation instructions for the `despia-native` npm package closely
+- Implementation as mentioned is critical for proper push notification delivery
+- Call `setonesignalplayerid://` on every app load to ensure the user ID is always connected
+
+**Perfect for:**
+
+- Sending targeted notifications to specific users
+- User-based notification management
+- Cross-device notification delivery
+- Personalized push notification campaigns
+
 ### Haptic Feedback
 
 All haptic feedback commands have no response - they provide immediate tactile feedback:
@@ -640,8 +1200,8 @@ These CSS variables are automatically provided by the Despia native runtime and
 - **watch** (string[], optional): Array of variable names to watch for in the response
 
 Returns a Promise that resolves when all watched variables are available:
-- **Single variable**: 30-second timeout with observation that ignores empty placeholders and requires a fresh write (Promise always resolves; on timeout it resolves with `undefined`)
-- **Multiple variables**: Uses VariableTracker with 5-minute auto-cleanup
+- **Single variable**: 30-second timeout with observation. `null` values resolve immediately (useful for error/not-found signals). Other empty placeholders (`undefined`, `"n/a"`, `{}`, `[]`) are ignored. Promise always resolves; on timeout it resolves with `undefined`.
+- **Multiple variables**: Uses VariableTracker with 5-minute auto-cleanup. All variables must have non-null values. Any `null` value blocks resolution until all variables have real values.
 
 ### Timeout behavior
 
@@ -654,9 +1214,13 @@ prevents hanging Promises for long-running or failing native operations.
 ### Fresh-data behavior
 
 Before observing, watched variables are cleared to avoid resolving on stale values.
-The observer ignores empty placeholders (`undefined`, `null`, `"n/a"`, `{}`, `[]`)
-and requires the value to change from its baseline before resolving. This ensures
-each call waits for a fresh write from the native side.
+The observer behavior differs by variable count:
+
+- **Single variable**: `null` is treated as a valid resolution value (useful for error/not-found signals). The observer ignores other empty placeholders (`undefined`, `"n/a"`, `{}`, `[]`) and requires the value to change from its baseline before resolving.
+
+- **Multiple variables**: All variables must have non-null values. The observer ignores empty placeholders (`undefined`, `null`, `"n/a"`, `{}`, `[]`) and requires all values to change from their baseline before resolving.
+
+This ensures each call waits for a fresh write from the native side.
 
 ### Direct Property Access
 
@@ -678,6 +1242,17 @@ Examples:
 - `lighthaptic://`
 - `getappversion://`
 - `revenuecat://purchase?external_id=user_777&product=monthly_premium`
+- `revenuecat://launchPaywall?external_id=user_777&offering=default`
+- `getpurchasehistory://`
+- `getclipboard://`
+- `settingsapp://`
+- `setonesignalplayerid://?user_id=user123`
+- `registerpush://`
+- `setvault://?key=userId&value=user123&locked=false`
+- `readvault://?key=userId`
+- `writevalue://{JSON-ENCODED-STRING}`
+- `readvalue://`
+- `oauth://?url=https://provider.com/oauth/authorize`
 - `requestcontactpermission://`
 - `savethisimage://?url=https://example.com/image.jpg`
 
@@ -687,16 +1262,22 @@ Your app can access these native features:
 
 - **Native Widgets** - Create widgets with SVG and refresh time
 - **In-App Purchases** - RevenueCat integration with external user IDs
+- **Restore Purchases** - Retrieve purchase history from App Store and Google Play
 - **Contact Access** - Request permissions and read contacts
 - **Background Location** - Native tracking with browser geolocation API
-- **Push Notifications** - OneSignal integration and local push messages
+- **Push Notifications** - OneSignal integration with external user IDs and local push messages
 - **Haptic Feedback** - Light, heavy, success, warning, and error feedback
 - **App Information** - Version numbers, bundle numbers, device UUID
+- **Clipboard Access** - Read clipboard content from device
 - **Screenshots** - Take device screenshots
 - **Scanning Mode** - Auto, on, and off scanning controls
 - **Store Location** - Get store location data
 - **File Operations** - Save images and download files
+- **Identity Vault** - Persistent cross-device storage with optional biometric protection
+- **Local Storage** - Cross-platform device storage (cleared on uninstall)
+- **OAuth Authentication** - Secure OAuth flows with native browser sessions
 - **App Control** - Reset app and disable tracking
+- **App Settings** - Open native app settings for permission management
 - **UI Controls** - Loading spinners and full screen mode
 - **Sharing** - Share app with custom messages and URLs
 - **Status Bar** - Control colors and text colors

package/index.js

@@ -58,13 +58,16 @@
         const initialSig = safeSig(initialRef);
 
         const ready = (val) => {
-            if (val === undefined || val === null || val === "n/a") return false;
+            if (val === undefined || val === "n/a") return false;
             if (Array.isArray(val) && val.length === 0) return false;
             if (val && typeof val === 'object' && !Array.isArray(val) && Object.keys(val).length === 0) return false;
             return true;
         };
 
         const changed = (val) => {
+            // Special case: if value is null, always consider it changed (immediate signal)
+            if (val === null) return true;
+            
             if (val !== initialRef) return true;
             return safeSig(val) !== initialSig;
         };

package/package.json

@@ -1,10 +1,18 @@
 {
     "name": "despia-native",
-    "version": "1.0.17",
+    "version": "1.0.20",
     "description": "JavaScript SDK for Despia native integrations with command queuing and variable watching",
     "main": "index.js",
     "module": "index.js",
     "types": "index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "import": "./index.js",
+            "require": "./index.js",
+            "default": "./index.js"
+        }
+    },
     "keywords": [
         "despia",
         "sdk",