@mobana/react-native-sdk 0.2.10 → 0.2.11

package/src/Mobana.ts

@@ -2,6 +2,7 @@ import type {
   MobanaConfig,
   GetAttributionOptions,
   Attribution,
+  AttributionResult,
   ConversionEvent,
   FlowResult,
   FlowOptions,
@@ -67,10 +68,14 @@ class MobanaSDK {
   private config: MobanaConfig | null = null;
   private isConfigured = false;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private attributionPromise: Promise<Attribution<any> | null> | null = null;
+  private attributionPromise: Promise<AttributionResult<any>> | null = null;
   // In-memory cache for attribution (faster than AsyncStorage)
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private cachedAttribution: Attribution<any> | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private cachedAttributionResult: AttributionResult<any> | null = null;
+  // Only true after a definitive server response (matched or no_match) — never on error.
+  // This allows retry on subsequent calls when the first attempt failed.
   private attributionChecked = false;
 
   /**
@@ -131,6 +136,13 @@ class MobanaSDK {
 
     // Flush any queued conversions when SDK is initialized
     await this.flushConversionQueue();
+
+    // Fire attribution in the background unless explicitly disabled.
+    // Non-blocking — init() resolves immediately after this.
+    // The result is cached so any subsequent getAttribution() call returns instantly.
+    if (this.config.autoAttribute !== false) {
+      this.getAttribution().catch(() => {});
+    }
   }
 
   /**
@@ -193,48 +205,61 @@ class MobanaSDK {
    */
   async getAttribution<T = Record<string, unknown>>(
     options: GetAttributionOptions = {}
-  ): Promise<Attribution<T> | null> {
+  ): Promise<AttributionResult<T>> {
     if (!this.isConfigured || !this.config) {
       console.warn('[Mobana] SDK not configured. Call init() first.');
-      return null;
+      return { status: 'error', attribution: null, error: { type: 'sdk_not_configured' } };
     }
 
     if (!this.config.enabled) {
       if (this.config.debug) {
-        console.log('[Mobana] SDK disabled, returning null');
+        console.log('[Mobana] SDK disabled, skipping attribution');
       }
-      return null;
+      return { status: 'error', attribution: null, error: { type: 'sdk_disabled' } };
     }
 
     // Return in-memory cache if available (fastest)
     if (this.attributionChecked) {
-      return this.cachedAttribution as Attribution<T> | null;
+      return this.cachedAttributionResult as AttributionResult<T>;
     }
 
     // Check AsyncStorage cache
     const cached = await getCachedResult<T>();
+
+    // Re-check enabled after the async read — it may have changed (e.g. GDPR opt-out)
+    if (!this.config?.enabled) {
+      return { status: 'error', attribution: null, error: { type: 'sdk_disabled' } };
+    }
+
     if (cached) {
       if (this.config.debug) {
         console.log('[Mobana] Returning cached result, matched:', cached.matched);
       }
-      // Update in-memory cache
+      const result: AttributionResult<T> = cached.matched && cached.attribution
+        ? { status: 'matched', attribution: cached.attribution as Attribution<T> }
+        : { status: 'no_match', attribution: null };
       this.attributionChecked = true;
-      this.cachedAttribution = cached.matched ? (cached.attribution ?? null) : null;
-      return this.cachedAttribution as Attribution<T> | null;
+      this.cachedAttribution = result.attribution;
+      this.cachedAttributionResult = result;
+      return result;
     }
 
-    // Prevent duplicate concurrent requests
+    // Prevent duplicate concurrent requests — both callers get the same promise
     if (this.attributionPromise) {
-      return this.attributionPromise as Promise<Attribution<T> | null>;
+      return this.attributionPromise as Promise<AttributionResult<T>>;
     }
 
     this.attributionPromise = this.fetchAttribution<T>(options);
     const result = await this.attributionPromise;
     this.attributionPromise = null;
 
-    // Update in-memory cache
-    this.attributionChecked = true;
-    this.cachedAttribution = result;
+    // Only cache definitive results. Errors (network, timeout, server) leave
+    // attributionChecked = false so the next call retries automatically.
+    if (result.status !== 'error') {
+      this.attributionChecked = true;
+      this.cachedAttribution = result.attribution;
+      this.cachedAttributionResult = result;
+    }
 
     return result;
   }
@@ -307,6 +332,25 @@ class MobanaSDK {
     }
   }
 
+  /**
+   * Get the install ID for this device
+   * 
+   * A random UUID generated on first launch and persisted locally.
+   * Useful for GDPR data access/deletion requests — this is the identifier
+   * Mobana uses server-side to associate attribution and conversion records.
+   * 
+   * @returns The install ID string
+   * 
+   * @example
+   * ```typescript
+   * const installId = await Mobana.getInstallId();
+   * // Share with support for data access/deletion: support@mobana.ai
+   * ```
+   */
+  async getInstallId(): Promise<string> {
+    return getInstallId();
+  }
+
   /**
    * Reset all stored attribution data
    * Useful for testing or when user logs out
@@ -317,6 +361,7 @@ class MobanaSDK {
   async reset(): Promise<void> {
     // Clear in-memory cache
     this.cachedAttribution = null;
+    this.cachedAttributionResult = null;
     this.attributionChecked = false;
     this.attributionPromise = null;
 
@@ -612,7 +657,7 @@ class MobanaSDK {
 
   private async fetchAttribution<T = Record<string, unknown>>(
     options: GetAttributionOptions
-  ): Promise<Attribution<T> | null> {
+  ): Promise<AttributionResult<T>> {
     const { timeout = DEFAULT_TIMEOUT } = options;
 
     try {
@@ -635,8 +680,14 @@ class MobanaSDK {
         }
       }
 
+      // Re-check enabled before making the network call — the SDK may have been
+      // disabled (via setEnabled(false)) while waiting for install ID or referrer
+      if (!this.config?.enabled) {
+        return { status: 'no_match', attribution: null };
+      }
+
       // Make API request
-      const response = await findAttribution<T>(
+      const { data: response, errorType, status } = await findAttribution<T>(
         endpoint,
         this.config!.appKey,
         installId,
@@ -646,54 +697,57 @@ class MobanaSDK {
         this.config?.debug ?? false
       );
 
-      // If no response (network error, timeout), don't cache - allow retry
+      // No response — network error, timeout, or server error
       if (!response) {
         if (this.config?.debug) {
-          console.log('[Mobana] No response from server');
+          console.log('[Mobana] Attribution request failed:', errorType);
         }
-        return null;
+        return {
+          status: 'error',
+          attribution: null,
+          error: {
+            type: errorType ?? 'unknown',
+            ...(status !== undefined && { status }),
+          },
+        };
       }
 
-      // Cache the response if server returned a valid response with matched key
-      // This prevents retrying on every startup
+      // Cache the response for definitive results (matched or unmatched)
       if (typeof response.matched === 'boolean') {
         if (response.matched && response.attribution) {
-          // Build attribution object
           const attribution: Attribution<T> = {
             ...response.attribution,
             confidence: response.confidence ?? 0,
           };
 
-          // Cache matched result
           await setCachedResult(true, attribution);
 
           if (this.config?.debug) {
             console.log('[Mobana] Attribution matched:', attribution);
           }
 
-          return attribution;
+          return { status: 'matched', attribution };
         } else {
-          // Cache unmatched result - prevents retry on next startup
           await setCachedResult<T>(false);
 
           if (this.config?.debug) {
             console.log('[Mobana] No match found (cached)');
           }
 
-          return null;
+          return { status: 'no_match', attribution: null };
         }
       }
 
-      // Unexpected response format
+      // Unexpected response format — treat as transient error (don't cache, allow retry)
       if (this.config?.debug) {
         console.log('[Mobana] Unexpected response format');
       }
-      return null;
+      return { status: 'error', attribution: null, error: { type: 'unknown' } };
     } catch (error) {
       if (this.config?.debug) {
         console.log('[Mobana] Error fetching attribution:', error);
       }
-      return null;
+      return { status: 'error', attribution: null, error: { type: 'unknown' } };
     }
   }
 

package/src/api.ts

@@ -70,6 +70,79 @@ async function request<T>(
   }
 }
 
+/**
+ * Internal result type for requests that need to surface error details.
+ * Used by findAttribution so getAttribution() can distinguish network vs.
+ * server vs. timeout errors.
+ */
+interface RequestResult<U> {
+  data: U | null;
+  errorType?: 'network' | 'timeout' | 'server';
+  /** HTTP status code — only present for 'server' errorType */
+  status?: number;
+}
+
+/**
+ * Like request(), but returns a structured result with error type information
+ * instead of collapsing all failures to null.
+ */
+async function requestWithError<U>(
+  endpoint: string,
+  path: string,
+  body: Record<string, unknown>,
+  appKey: string,
+  timeout: number = DEFAULT_TIMEOUT,
+  debug: boolean = false
+): Promise<RequestResult<U>> {
+  const url = `${endpoint}${path}`;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    if (debug) {
+      console.log(`[Mobana] POST ${url}`, body);
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: buildHeaders(appKey),
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      if (debug) {
+        console.log(`[Mobana] Request failed: ${response.status}`);
+      }
+      return { data: null, errorType: 'server', status: response.status };
+    }
+
+    const data = await response.json();
+
+    if (debug) {
+      console.log(`[Mobana] Response:`, data);
+    }
+
+    return { data: data as U };
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    const isTimeout = error instanceof Error && error.name === 'AbortError';
+
+    if (debug) {
+      if (isTimeout) {
+        console.log(`[Mobana] Request timed out after ${timeout}ms`);
+      } else {
+        console.log(`[Mobana] Request error:`, error);
+      }
+    }
+
+    return { data: null, errorType: isTimeout ? 'timeout' : 'network' };
+  }
+}
+
 /**
  * Call /find endpoint to get attribution
  */
@@ -81,8 +154,8 @@ export async function findAttribution<T = Record<string, unknown>>(
   dacid: string | null,
   timeout: number,
   debug: boolean
-): Promise<FindResponse<T> | null> {
-  return request<FindResponse<T>>(
+): Promise<RequestResult<FindResponse<T>>> {
+  return requestWithError<FindResponse<T>>(
     endpoint,
     '/find',
     {

package/src/types.ts

@@ -32,6 +32,17 @@ export interface MobanaConfig {
    * When true, logs SDK operations to console
    */
   debug?: boolean;
+
+  /**
+   * Automatically fetch attribution when init() is called (default: true)
+   *
+   * When true, attribution is fetched in the background on init — non-blocking.
+   * The result is cached so any subsequent getAttribution() call returns instantly.
+   *
+   * Set to false to delay attribution until you explicitly call getAttribution()
+   * (e.g., to wait for GDPR consent before making any network calls).
+   */
+  autoAttribute?: boolean;
 }
 
 // ============================================
@@ -300,6 +311,41 @@ export interface Attribution<T = Record<string, unknown>> {
   confidence: number;
 }
 
+/**
+ * Error details returned when an attribution request fails
+ */
+export interface AttributionError {
+  /**
+   * Type of error:
+   * - 'network' — no internet connection or request was blocked
+   * - 'timeout' — request exceeded the timeout limit
+   * - 'server' — server returned an HTTP error
+   * - 'sdk_not_configured' — SDK.init() was not called before getAttribution()
+   * - 'sdk_disabled' — SDK is disabled (enabled: false in config)
+   * - 'unknown' — unexpected error
+   */
+  type: 'network' | 'timeout' | 'server' | 'sdk_not_configured' | 'sdk_disabled' | 'unknown';
+  /** HTTP status code (only present for 'server' type) */
+  status?: number;
+}
+
+/**
+ * Result returned by getAttribution()
+ */
+export interface AttributionResult<T = Record<string, unknown>> {
+  /**
+   * Attribution status:
+   * - 'matched' — attribution data found; check the attribution field
+   * - 'no_match' — no match found (organic install)
+   * - 'error' — request failed or SDK is misconfigured; check the error field for details
+   */
+  status: 'matched' | 'no_match' | 'error';
+  /** Attribution data. Present only when status is 'matched'. */
+  attribution: Attribution<T> | null;
+  /** Error details. Present only when status is 'error'. */
+  error?: AttributionError;
+}
+
 /**
  * Internal: API response from /find endpoint
  */