@li-nk.me/react-native-sdk 0.1.1 → 0.2.1

package/README.md

@@ -1,103 +1,37 @@
 # LinkMe React Native SDK
 
-Pure TypeScript React Native SDK for LinkMe — deep linking and attribution. No native modules required.
+React Native SDK for LinkMe — deep linking and attribution.
 
-- Quick Start: See `QUICK_START.md`
-- Repo docs: ../../docs/help/docs/setup/react-native.md
-- Hosted docs: https://li-nk.me/resources/developer/setup/react-native
-- Example app: See `example-expo/` directory
-- Android troubleshooting: See [Android Troubleshooting](https://li-nk.me/resources/developer/setup/android#troubleshooting) section in Android setup docs
+- **Main Site**: [li-nk.me](https://li-nk.me)
+- **Documentation**: [React Native Setup](https://li-nk.me/docs/developer/setup/react-native)
+- **Package**: [npm](https://www.npmjs.com/package/@linkme/react-native-sdk)
 
 ## Installation
 
 ```bash
-npm install @li-nk.me/react-native-sdk
+npm install @linkme/react-native-sdk
 ```
 
-### Optional: iOS Pasteboard Support
+## Basic Usage
 
-For more reliable deferred deep linking on iOS, install `expo-clipboard`:
+```ts
+import { configure } from '@linkme/react-native-sdk';
 
-```bash
-npx expo install expo-clipboard
-```
-
-When installed, the SDK will automatically check the iOS pasteboard for a li-nk.me URL before falling back to fingerprint matching. Pasteboard must also be enabled in the Portal (App Settings → iOS).
-
-### Expo Configuration
-
-Add the config plugin to your `app.json` or `app.config.js`:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "@li-nk.me/react-native-sdk/plugin/app.plugin.js",
-        {
-          "hosts": ["link.example.com"],
-          "associatedDomains": ["applinks:link.example.com"],
-          "schemes": ["com.example.app"]
-        }
-      ]
-    ]
-  }
-}
-```
-
-## Usage
-
-Initialize the SDK in your root layout (e.g., `app/_layout.tsx`):
-
-```typescript
-import { configure, onLink, getInitialLink, claimDeferredIfAvailable, track } from '@li-nk.me/react-native-sdk';
-
-// ... inside your component
-useEffect(() => {
-  configure({
-    appId: 'your-app-id',
-    appKey: 'your-app-key',
-    // ... other options
-  }).then(() => {
-    // 1. Listen for deep links (foreground)
-    onLink((payload) => handlePayload(payload));
-
-    // 2. Check for initial link (cold start)
-    getInitialLink().then((payload) => {
-      if (payload) handlePayload(payload);
-      else {
-        // 3. Check for deferred link (first install)
-        claimDeferredIfAvailable().then((payload) => {
-          if (payload) handlePayload(payload);
-        });
-      }
-    });
-
-    // 4. Track open
-    track('open');
-  });
-}, []);
+await configure({
+  appId: 'your_app_id',
+  appKey: 'your_app_key',
+  debug: __DEV__, // Optional: surface verbose logs for deferred/pasteboard flows
+});
 ```
 
-## UTM & Analytics
+For full documentation, guides, and API reference, please visit our [Help Center](https://li-nk.me/docs/help).
 
-LinkMe automatically normalizes UTM parameters from deep links and deferred links. You can map these to your analytics provider (e.g., Firebase):
+## Debugging Deferred Links
 
-```typescript
-function handlePayload(payload: LinkMePayload) {
-  if (payload.utm) {
-    // Example: Map to Firebase Analytics
-    // analytics().logEvent('campaign_details', {
-    //   source: payload.utm.source,
-    //   medium: payload.utm.medium,
-    //   campaign: payload.utm.campaign,
-    //   term: payload.utm.term,
-    //   content: payload.utm.content,
-    // });
-  }
-}
-```
+- Pass `debug: true` (or `__DEV__`) to `configure` to emit `[LinkMe SDK]` logs for pasteboard and fingerprint claims.
+- Check that Expo Clipboard is installed if you expect pasteboard-based iOS claims.
+- Review server logs for `/api/deferred/claim` to verify fingerprint matches.
 
-The SDK uses React Native's built-in `Linking` API and requires an Expo config plugin for deep link configuration.
+## License
 
-License: MIT
+Apache-2.0

package/lib/index.d.ts

@@ -10,6 +10,7 @@ export type LinkMeConfig = {
     baseUrl?: string;
     appId?: string;
     appKey?: string;
+    debug?: boolean;
     /**
      * @deprecated Pasteboard is now controlled from the Portal (App Settings → iOS).
      * The SDK automatically checks pasteboard on iOS if expo-clipboard is installed.

package/lib/index.js

@@ -13,6 +13,7 @@ class LinkMeController {
         var _a, _b;
         this.ready = false;
         this.advertisingConsent = false;
+        this.debug = false;
         this.lastPayload = null;
         this.listeners = new Set();
         this.pendingUrls = [];
@@ -26,9 +27,13 @@ class LinkMeController {
         this.linking = (_b = deps === null || deps === void 0 ? void 0 : deps.linking) !== null && _b !== void 0 ? _b : Linking;
     }
     async configure(config) {
+        var _a;
         const normalized = normalizeConfig(config);
         this.config = normalized;
         this.advertisingConsent = !!config.includeAdvertisingId;
+        const fallbackDev = Boolean(globalThis === null || globalThis === void 0 ? void 0 : globalThis.__DEV__);
+        this.debug = (_a = normalized.debug) !== null && _a !== void 0 ? _a : fallbackDev;
+        this.logDebug('configure', { baseUrl: normalized.baseUrl, debug: this.debug });
         this.subscribeToLinking();
         this.ready = true;
         await this.drainPending();
@@ -67,14 +72,19 @@ class LinkMeController {
     async claimDeferredIfAvailable() {
         const cfg = this.config;
         if (!cfg) {
+            this.logDebug('deferred.skip_no_config');
             return null;
         }
+        this.logDebug('deferred.claim.start', { platform: Platform.OS });
         // 1. On iOS, try to read CID from pasteboard first (if expo-clipboard is available)
         if (Platform.OS === 'ios' && (Clipboard === null || Clipboard === void 0 ? void 0 : Clipboard.getStringAsync)) {
+            this.logDebug('deferred.pasteboard.check');
             const pasteboardPayload = await this.tryClaimFromPasteboard(cfg);
             if (pasteboardPayload) {
+                this.logDebug('deferred.pasteboard.payload');
                 return pasteboardPayload;
             }
+            this.logDebug('deferred.pasteboard.no_match');
         }
         // 2. Fallback to probabilistic fingerprint matching
         try {
@@ -85,48 +95,65 @@ class LinkMeController {
             if (device) {
                 body.device = device;
             }
+            this.logDebug('deferred.fingerprint.request');
             const res = await this.fetchImpl(`${cfg.apiBaseUrl}/deferred/claim`, {
                 method: 'POST',
                 headers: this.buildHeaders(true),
                 body: JSON.stringify(body),
             });
             if (!res.ok) {
+                this.logDebug('deferred.fingerprint.http_error', { status: res.status });
                 return null;
             }
             const payload = await this.parsePayload(res);
             if (payload) {
+                this.logDebug('deferred.fingerprint.payload', { linkId: payload.linkId, duplicate: payload === null || payload === void 0 ? void 0 : payload.duplicate });
                 this.emit(payload);
             }
+            else {
+                this.logDebug('deferred.fingerprint.no_match');
+            }
             return payload;
         }
-        catch {
+        catch (err) {
+            this.logDebug('deferred.fingerprint.error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
     async tryClaimFromPasteboard(cfg) {
         try {
             if (!(Clipboard === null || Clipboard === void 0 ? void 0 : Clipboard.getStringAsync)) {
+                this.logDebug('pasteboard.skip_module');
                 return null;
             }
+            this.logDebug('pasteboard.read');
             const pasteStr = await Clipboard.getStringAsync();
             if (!pasteStr) {
+                this.logDebug('pasteboard.empty');
                 return null;
             }
             // Check if the clipboard contains a li-nk.me URL with a cid parameter
             const cid = this.extractCidFromUrl(pasteStr, cfg.baseUrl);
             if (!cid) {
+                this.logDebug('pasteboard.no_cid', { hasClipboard: true });
                 return null;
             }
+            this.logDebug('pasteboard.cid_found');
             // Resolve the CID to get the payload
             const payload = await this.resolveCidWithConfig(cfg, cid);
             if (payload) {
                 this.emit(payload);
                 // Track pasteboard claim
-                this.track('claim', { claim_type: 'pasteboard' });
+                this.logDebug('pasteboard.payload', { linkId: payload.linkId });
+                void this.track('claim', { claim_type: 'pasteboard' });
+            }
+            else {
+                this.logDebug('pasteboard.resolve_empty');
             }
             return payload;
         }
-        catch {
+        catch (err) {
+            this.logDebug('pasteboard.error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -136,13 +163,21 @@ class LinkMeController {
             // Check if the URL is from our domain
             const baseHost = new URL(baseUrl).host;
             if (!url.host.endsWith(baseHost) && url.host !== baseHost.replace(/^www\./, '')) {
+                this.logDebug('pasteboard.url_mismatch', { host: url.host });
                 return null;
             }
             // Extract the cid parameter
             const cid = url.searchParams.get('cid');
+            if (cid) {
+                this.logDebug('pasteboard.url_cid_present');
+            }
+            else {
+                this.logDebug('pasteboard.url_no_cid');
+            }
             return cid || null;
         }
-        catch {
+        catch (err) {
+            this.logDebug('pasteboard.url_parse_error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -194,11 +229,14 @@ class LinkMeController {
                 body: JSON.stringify(body),
             });
             if (!res.ok) {
-                await res.text().catch(() => undefined);
+                const text = await res.text().catch(() => undefined);
+                this.logDebug('app_events.http_error', { status: res.status, body: text });
+                console.warn('[LinkMe SDK] app_events.http_error', { status: res.status, body: text });
             }
         }
         catch {
-            /* noop */
+            this.logDebug('app_events.network_error');
+            console.warn('[LinkMe SDK] app_events.network_error');
         }
     }
     onLink(listener) {
@@ -385,7 +423,8 @@ class LinkMeController {
             const json = (await res.json());
             return json !== null && json !== void 0 ? json : null;
         }
-        catch {
+        catch (err) {
+            this.logDebug('payload.parse_error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -400,6 +439,22 @@ class LinkMeController {
             }
         }
     }
+    logDebug(event, details) {
+        if (!this.debug) {
+            return;
+        }
+        try {
+            if (details) {
+                console.log(`[LinkMe SDK] ${event}`, details);
+            }
+            else {
+                console.log(`[LinkMe SDK] ${event}`);
+            }
+        }
+        catch {
+            /* noop */
+        }
+    }
 }
 function normalizeConfig(config) {
     const baseUrl = (config === null || config === void 0 ? void 0 : config.baseUrl) || 'https://li-nk.me';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@li-nk.me/react-native-sdk",
-    "version": "0.1.1",
+    "version": "0.2.1",
     "description": "Pure TypeScript React Native SDK for LinkMe deep and deferred links.",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",
@@ -24,6 +24,10 @@
         "sdk"
     ],
     "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/r-dev-limited/li-nk.me-react-native-sdk"
+    },
     "peerDependencies": {
         "react": ">=18",
         "react-native": ">=0.72.0",

package/src/index.ts

@@ -21,6 +21,7 @@ export type LinkMeConfig = {
     baseUrl?: string;
     appId?: string;
     appKey?: string;
+    debug?: boolean;
     /**
      * @deprecated Pasteboard is now controlled from the Portal (App Settings → iOS).
      * The SDK automatically checks pasteboard on iOS if expo-clipboard is installed.
@@ -52,6 +53,7 @@ class LinkMeController {
     private config: NormalizedConfig | undefined;
     private ready = false;
     private advertisingConsent = false;
+    private debug = false;
     private userId: string | undefined;
     private lastPayload: LinkMePayload | null = null;
     private readonly listeners = new Set<Listener>();
@@ -74,6 +76,9 @@ class LinkMeController {
         const normalized = normalizeConfig(config);
         this.config = normalized;
         this.advertisingConsent = !!config.includeAdvertisingId;
+        const fallbackDev = Boolean((globalThis as any)?.__DEV__);
+        this.debug = normalized.debug ?? fallbackDev;
+        this.logDebug('configure', { baseUrl: normalized.baseUrl, debug: this.debug });
         this.subscribeToLinking();
         this.ready = true;
         await this.drainPending();
@@ -113,15 +118,20 @@ class LinkMeController {
     async claimDeferredIfAvailable(): Promise<LinkMePayload | null> {
         const cfg = this.config;
         if (!cfg) {
+            this.logDebug('deferred.skip_no_config');
             return null;
         }
+        this.logDebug('deferred.claim.start', { platform: Platform.OS });
 
         // 1. On iOS, try to read CID from pasteboard first (if expo-clipboard is available)
         if (Platform.OS === 'ios' && Clipboard?.getStringAsync) {
+            this.logDebug('deferred.pasteboard.check');
             const pasteboardPayload = await this.tryClaimFromPasteboard(cfg);
             if (pasteboardPayload) {
+                this.logDebug('deferred.pasteboard.payload');
                 return pasteboardPayload;
             }
+            this.logDebug('deferred.pasteboard.no_match');
         }
 
         // 2. Fallback to probabilistic fingerprint matching
@@ -133,20 +143,26 @@ class LinkMeController {
             if (device) {
                 body.device = device;
             }
+            this.logDebug('deferred.fingerprint.request');
             const res = await this.fetchImpl(`${cfg.apiBaseUrl}/deferred/claim`, {
                 method: 'POST',
                 headers: this.buildHeaders(true),
                 body: JSON.stringify(body),
             });
             if (!res.ok) {
+                this.logDebug('deferred.fingerprint.http_error', { status: res.status });
                 return null;
             }
             const payload = await this.parsePayload(res);
             if (payload) {
+                this.logDebug('deferred.fingerprint.payload', { linkId: payload.linkId, duplicate: (payload as any)?.duplicate });
                 this.emit(payload);
+            } else {
+                this.logDebug('deferred.fingerprint.no_match');
             }
             return payload;
-        } catch {
+        } catch (err) {
+            this.logDebug('deferred.fingerprint.error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -154,26 +170,35 @@ class LinkMeController {
     private async tryClaimFromPasteboard(cfg: NormalizedConfig): Promise<LinkMePayload | null> {
         try {
             if (!Clipboard?.getStringAsync) {
+                this.logDebug('pasteboard.skip_module');
                 return null;
             }
+            this.logDebug('pasteboard.read');
             const pasteStr = await Clipboard.getStringAsync();
             if (!pasteStr) {
+                this.logDebug('pasteboard.empty');
                 return null;
             }
             // Check if the clipboard contains a li-nk.me URL with a cid parameter
             const cid = this.extractCidFromUrl(pasteStr, cfg.baseUrl);
             if (!cid) {
+                this.logDebug('pasteboard.no_cid', { hasClipboard: true });
                 return null;
             }
+            this.logDebug('pasteboard.cid_found');
             // Resolve the CID to get the payload
             const payload = await this.resolveCidWithConfig(cfg, cid);
             if (payload) {
                 this.emit(payload);
                 // Track pasteboard claim
-                this.track('claim', { claim_type: 'pasteboard' });
+                this.logDebug('pasteboard.payload', { linkId: payload.linkId });
+                void this.track('claim', { claim_type: 'pasteboard' });
+            } else {
+                this.logDebug('pasteboard.resolve_empty');
             }
             return payload;
-        } catch {
+        } catch (err) {
+            this.logDebug('pasteboard.error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -184,12 +209,19 @@ class LinkMeController {
             // Check if the URL is from our domain
             const baseHost = new URL(baseUrl).host;
             if (!url.host.endsWith(baseHost) && url.host !== baseHost.replace(/^www\./, '')) {
+                this.logDebug('pasteboard.url_mismatch', { host: url.host });
                 return null;
             }
             // Extract the cid parameter
             const cid = url.searchParams.get('cid');
+            if (cid) {
+                this.logDebug('pasteboard.url_cid_present');
+            } else {
+                this.logDebug('pasteboard.url_no_cid');
+            }
             return cid || null;
-        } catch {
+        } catch (err) {
+            this.logDebug('pasteboard.url_parse_error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -245,10 +277,13 @@ class LinkMeController {
                 body: JSON.stringify(body),
             });
             if (!res.ok) {
-                await res.text().catch(() => undefined);
+                const text = await res.text().catch(() => undefined);
+                this.logDebug('app_events.http_error', { status: res.status, body: text });
+                console.warn('[LinkMe SDK] app_events.http_error', { status: res.status, body: text });
             }
         } catch {
-            /* noop */
+            this.logDebug('app_events.network_error');
+            console.warn('[LinkMe SDK] app_events.network_error');
         }
     }
 
@@ -436,7 +471,8 @@ class LinkMeController {
         try {
             const json = (await res.json()) as LinkMePayload;
             return json ?? null;
-        } catch {
+        } catch (err) {
+            this.logDebug('payload.parse_error', { message: err instanceof Error ? err.message : String(err) });
             return null;
         }
     }
@@ -451,6 +487,21 @@ class LinkMeController {
             }
         }
     }
+
+    private logDebug(event: string, details?: Record<string, any>): void {
+        if (!this.debug) {
+            return;
+        }
+        try {
+            if (details) {
+                console.log(`[LinkMe SDK] ${event}`, details);
+            } else {
+                console.log(`[LinkMe SDK] ${event}`);
+            }
+        } catch {
+            /* noop */
+        }
+    }
 }
 
 function normalizeConfig(config: LinkMeConfig): NormalizedConfig {