insert-affiliate-js-sdk 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to the Insert Affiliate JavaScript SDK will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-03-29
+
+### Fixed
+- **Offer code sanitization** - Fixed offer codes with dashes/underscores being stripped (e.g. `pro-v3-ext` was incorrectly becoming `prov3ext`)
+  - Now checks for API error responses before cleaning the offer code
+  - Sanitization regex updated to preserve dashes and underscores
+
 ## [1.1.0] - 2025-11-23
 
 ### Added

package/README.md

@@ -89,10 +89,23 @@ await InsertAffiliate.initialize('YOUR_COMPANY_CODE');
 <summary><strong>Advanced Initialization Options</strong> (click to expand)</summary>
 
 ```javascript
-// Enable verbose logging for debugging
-await InsertAffiliate.initialize('YOUR_COMPANY_CODE', true);
+// Full initialization with all options
+await InsertAffiliate.initialize(
+  'YOUR_COMPANY_CODE',   // Company code (required)
+  true,                  // Enable verbose logging (optional, default: false)
+  86400000,              // Attribution timeout in milliseconds (optional, e.g., 24 hours)
+  true                   // Prevent affiliate transfer (optional, default: false)
+);
 ```
 
+**Parameters:**
+- `companyCode` (required): Your Insert Affiliate company code
+- `verboseLogging` (optional): Enable detailed console logs for debugging
+- `affiliateAttributionActiveTime` (optional): Time in milliseconds before attribution expires (e.g., `86400000` for 24 hours)
+- `preventAffiliateTransfer` (optional): When `true`, prevents a new affiliate link from overwriting an existing affiliate attribution (defaults to `false`)
+  - Use this to ensure the first affiliate who acquired the user always gets credit
+  - New affiliate links will be silently ignored if the user already has an affiliate
+
 **Verbose logging shows:**
 - Initialization process and company code validation
 - Deep link processing and short code detection
@@ -125,17 +138,57 @@ import { InsertAffiliate } from 'insert-affiliate-js-sdk';
 import { Purchases } from '@revenuecat/purchases-capacitor';
 
 window.addEventListener('DOMContentLoaded', async () => {
-  await InsertAffiliate.initialize('YOUR_COMPANY_CODE');
+  await InsertAffiliate.initialize(
+    'YOUR_COMPANY_CODE',
+    false,    // verbose logging
+    86400000, // 24 hour attribution timeout (optional)
+    true      // prevent affiliate transfer (optional)
+  );
   await Purchases.configure({ apiKey: 'YOUR_REVENUECAT_API_KEY' });
 
-  const affiliateIdentifier = await InsertAffiliate.returnInsertAffiliateIdentifier();
+  // Set up callback for when affiliate identifier changes
+  // Note: Use preventAffiliateTransfer in initialize() to block affiliate changes in the SDK
+  InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(async (identifier, offerCode) => {
+    if (!identifier) return;
 
-  if (affiliateIdentifier) {
-    await Purchases.setAttributes({ insert_affiliate: affiliateIdentifier });
-  }
+    // Ensure RevenueCat subscriber exists before setting attributes
+    const customerInfo = await Purchases.getCustomerInfo();
+
+    // OPTIONAL: Prevent attribution for existing subscribers
+    // Uncomment to ensure affiliates only earn from users they actually brought:
+    // const hasActiveEntitlement = Object.keys(customerInfo.entitlements.active).length > 0;
+    // if (hasActiveEntitlement) return; // User already subscribed, don't attribute
+
+    // Get expiry timestamp for RevenueCat targeting
+    const expiryTimestamp = await InsertAffiliate.getAffiliateExpiryTimestamp();
+
+    // Set attributes for RevenueCat
+    const attributes = {
+      insert_affiliate: identifier,
+      insert_timedout: expiryTimestamp?.toString() || '',
+    };
+
+    // Add offer code for RevenueCat Targeting (if available)
+    if (offerCode) {
+      attributes.affiliateOfferCode = offerCode;
+    }
+
+    await Purchases.setAttributes(attributes);
+    await Purchases.syncAttributesAndOfferingsIfNeeded();
+  });
 });
 ```
 
+**Using RevenueCat Targeting (Recommended)**
+
+RevenueCat Targeting automatically shows different offerings based on the `affiliateOfferCode` attribute. Simply display `offerings.current`:
+
+```javascript
+const offerings = await Purchases.getOfferings();
+const currentOffering = offerings.current;
+// RevenueCat targeting automatically shows the correct offering based on affiliateOfferCode
+```
+
 **Step 2: Webhook Setup**
 
 1. In RevenueCat, [create a new webhook](https://www.revenuecat.com/docs/integrations/webhooks)
@@ -386,15 +439,16 @@ Learn more: [Short Codes Documentation](https://docs.insertaffiliate.com/short-c
 Get notified when the affiliate identifier changes:
 
 ```javascript
-InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier, offerCode) => {
   if (identifier) {
     console.log('Affiliate changed:', identifier);
+    console.log('Offer code:', offerCode || 'none');
 
     // Update UI
     document.getElementById('affiliate-banner').style.display = 'block';
 
     // Track in analytics
-    analytics.track('affiliate_link_clicked', { identifier });
+    analytics.track('affiliate_link_clicked', { identifier, offerCode });
   }
 });
 
@@ -402,8 +456,33 @@ InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
 InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(null);
 ```
 
+**Callback Parameters:**
+- `identifier` (string | null): The full affiliate identifier (shortCode-userId)
+- `offerCode` (string | null): The offer code associated with this affiliate (if any)
+
 </details>
 
+### Prevent Affiliate Transfer
+
+By default, clicking a new affiliate link will overwrite any existing attribution. Enable `preventAffiliateTransfer` to lock the first affiliate:
+
+```javascript
+await InsertAffiliate.initialize(
+  "YOUR_COMPANY_CODE",
+  false,   // verboseLogging
+  604800,  // 7-day attribution timeout
+  true     // preventAffiliateTransfer - locks first affiliate
+);
+```
+
+**How it works:**
+- When enabled, once a user is attributed to an affiliate, that attribution is locked
+- New affiliate links will not overwrite the existing attribution
+- The callback still fires with the existing affiliate data (not the new one)
+- Useful for preventing "affiliate stealing" where users click competitor links
+
+Learn more: [Prevent Affiliate Transfer Documentation](https://docs.insertaffiliate.com/prevent-affiliate-transfer)
+
 ---
 
 ## 📖 API Reference
@@ -412,7 +491,7 @@ InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(null);
 
 | Method | Description | Returns |
 |--------|-------------|---------|
-| `initialize(companyCode, verbose?)` | Initialize the SDK | `Promise<void>` |
+| `initialize(companyCode, verbose?, timeout?, preventTransfer?)` | Initialize the SDK | `Promise<void>` |
 | `returnInsertAffiliateIdentifier(ignoreTimeout?)` | Get current affiliate identifier | `Promise<string \| null>` |
 | `returnCompanyId()` | Get company ID | `Promise<string \| null>` |
 | `setInsertAffiliateIdentifier(link)` | Set affiliate from deep link | `Promise<string \| null>` |
@@ -420,6 +499,9 @@ InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(null);
 | `getAffiliateDetails(code)` | Get affiliate info without storing | `Promise<AffiliateDetails \| null>` |
 | `trackEvent(eventName)` | Track custom event | `Promise<void>` |
 | `getOfferCode()` | Get offer code modifier | `Promise<string \| null>` |
+| `getAffiliateExpiryTimestamp()` | Get Unix timestamp (ms) when attribution expires | `Promise<number \| null>` |
+| `getAffiliateStoredDate()` | Get ISO date string when affiliate was stored | `Promise<string \| null>` |
+| `isAffiliateAttributionValid()` | Check if attribution is still valid | `Promise<boolean>` |
 | `setInsertAffiliateIdentifierChangeCallback(fn)` | Set change callback | `void` |
 
 <details>

package/dist/index.d.ts

@@ -6,16 +6,22 @@ interface AffiliateDetails {
     affiliateShortCode: string;
     deeplinkUrl: string;
 }
-type InsertAffiliateIdentifierChangeCallback = (identifier: string | null) => void;
+type AffiliateLookupStatus = 'found' | 'not_found' | 'lookup_failed' | 'not_configured';
+interface AffiliateLookupResult {
+    status: AffiliateLookupStatus;
+    details: AffiliateDetails | null;
+}
+type InsertAffiliateIdentifierChangeCallback = (identifier: string | null, offerCode: string | null) => void;
 declare class InsertAffiliate {
     private static isInitialized;
     private static companyCode;
     private static verboseLogging;
     private static insertAffiliateIdentifierChangeCallback;
     private static affiliateAttributionActiveTime;
+    private static preventAffiliateTransfer;
     private static offerCode;
     private static verboseLog;
-    static initialize(code: string | null, verboseLogging?: boolean, affiliateAttributionActiveTime?: number): Promise<void>;
+    static initialize(code: string | null, verboseLogging?: boolean, affiliateAttributionActiveTime?: number, preventAffiliateTransfer?: boolean): Promise<void>;
     private static checkForInsertAffiliateParam;
     static returnInsertAffiliateIdentifier(ignoreTimeout?: boolean): Promise<string | null>;
     static setInsertAffiliateIdentifier(referringLink: string): Promise<string | null>;
@@ -23,19 +29,43 @@ declare class InsertAffiliate {
      * Validates and sets a short code for affiliate tracking
      * Validates the short code against the API before storing
      * @param shortCode The short code to validate and set
+     * @param options.onLookupFailed called when the lookup itself couldn't be completed
+     *   (not just an invalid code) — use it to offer a retry instead of proceeding unattributed.
      * @returns true if the code exists and was successfully validated and stored, false otherwise
      */
-    static setShortCode(shortCode: string): Promise<boolean>;
+    static setShortCode(shortCode: string, options?: {
+        onLookupFailed?: () => void;
+    }): Promise<boolean>;
     static setInsertAffiliateIdentifierChangeCallback(callback: InsertAffiliateIdentifierChangeCallback | null): void;
     static isAffiliateAttributionValid(): Promise<boolean>;
     static getAffiliateStoredDate(): Promise<string | null>;
     /**
-     * Retrieve detailed information about an affiliate by their short code or deep link
-     * This method queries the API and does not store or set the affiliate identifier
+     * Get the Unix timestamp (in milliseconds) when the affiliate attribution will expire
+     * @returns The expiry timestamp in milliseconds, or null if no attribution or no timeout configured
+     */
+    static getAffiliateExpiryTimestamp(): Promise<number | null>;
+    /**
+     * Retrieve detailed information about an affiliate by their short code or deep link,
+     * distinguishing "no affiliate matches this code" from "couldn't check" (backend
+     * outage, timeout, rate limit). This method queries the API and does not store or set
+     * the affiliate identifier.
+     * @param affiliateCode The short code or deep link to look up
+     * @returns an AffiliateLookupResult with a status of 'found', 'not_found', 'lookup_failed', or 'not_configured'
+     */
+    static getAffiliateLookupResult(affiliateCode: string, options?: {
+        trackUsage?: boolean;
+    }): Promise<AffiliateLookupResult>;
+    /**
+     * Retrieve detailed information about an affiliate by their short code or deep link.
+     * Kept for backward compatibility: collapses 'not_found' and 'lookup_failed' into the
+     * same null result, exactly as before. Use getAffiliateLookupResult if you need to tell
+     * an invalid code apart from a backend outage.
      * @param affiliateCode The short code or deep link to look up
      * @returns AffiliateDetails if found, null otherwise
      */
-    static getAffiliateDetails(affiliateCode: string): Promise<AffiliateDetails | null>;
+    static getAffiliateDetails(affiliateCode: string, options?: {
+        trackUsage?: boolean;
+    }): Promise<AffiliateDetails | null>;
     static returnCompanyId(): Promise<string | null>;
     /**
      * Get the offer code for the current affiliate
@@ -68,4 +98,4 @@ declare class InsertAffiliate {
     private static fetchShortLink;
 }
 
-export { type AffiliateDetails, InsertAffiliate, type InsertAffiliateIdentifierChangeCallback };
+export { type AffiliateDetails, type AffiliateLookupResult, type AffiliateLookupStatus, InsertAffiliate, type InsertAffiliateIdentifierChangeCallback };

package/dist/index.js

@@ -80,12 +80,14 @@ var InsertAffiliate = class {
       console.log(`[Insert Affiliate] [VERBOSE] ${message}`);
     }
   }
-  static async initialize(code, verboseLogging = false, affiliateAttributionActiveTime) {
+  static async initialize(code, verboseLogging = false, affiliateAttributionActiveTime, preventAffiliateTransfer = false) {
     this.verboseLogging = verboseLogging;
+    this.preventAffiliateTransfer = preventAffiliateTransfer;
     if (verboseLogging) {
       this.verboseLog("Starting SDK initialization...");
       this.verboseLog(`Company code provided: ${code ? "Yes" : "No"}`);
       this.verboseLog("Verbose logging enabled");
+      this.verboseLog(`Prevent affiliate transfer: ${preventAffiliateTransfer}`);
     }
     if (this.isInitialized) {
       this.verboseLog("SDK already initialized, skipping");
@@ -165,6 +167,11 @@ var InsertAffiliate = class {
       this.verboseLog(`Returning existing identifier: ${identifier2}`);
       return identifier2;
     }
+    if (this.preventAffiliateTransfer && existingShortCode && existingShortCode !== shortCode) {
+      this.verboseLog(`Transfer blocked: existing affiliate "${existingShortCode}" protected from being replaced by "${shortCode}"`);
+      const identifier2 = `${existingShortCode}-${userId}`;
+      return identifier2;
+    }
     this.verboseLog(`Saving short code to storage: ${shortCode}`);
     await saveValue("referrerLink", shortCode);
     const storedDate = (/* @__PURE__ */ new Date()).toISOString();
@@ -172,10 +179,10 @@ var InsertAffiliate = class {
     this.verboseLog(`Short code saved successfully with stored date: ${storedDate}`);
     const identifier = `${shortCode}-${userId}`;
     this.verboseLog(`Returning identifier: ${identifier}`);
-    await this.fetchAndStoreOfferCode(shortCode);
+    const offerCode = await this.fetchAndStoreOfferCode(shortCode);
     if (this.insertAffiliateIdentifierChangeCallback) {
-      this.verboseLog(`Triggering callback with identifier: ${identifier}`);
-      this.insertAffiliateIdentifierChangeCallback(identifier);
+      this.verboseLog(`Triggering callback with identifier: ${identifier}, offerCode: ${offerCode || "none"}`);
+      this.insertAffiliateIdentifierChangeCallback(identifier, offerCode);
     }
     return identifier;
   }
@@ -183,9 +190,12 @@ var InsertAffiliate = class {
    * Validates and sets a short code for affiliate tracking
    * Validates the short code against the API before storing
    * @param shortCode The short code to validate and set
+   * @param options.onLookupFailed called when the lookup itself couldn't be completed
+   *   (not just an invalid code) — use it to offer a retry instead of proceeding unattributed.
    * @returns true if the code exists and was successfully validated and stored, false otherwise
    */
-  static async setShortCode(shortCode) {
+  static async setShortCode(shortCode, options) {
+    var _a;
     this.verboseLog(`Setting short code. Input: ${shortCode}`);
     const valid = /^[a-zA-Z0-9]{3,25}$/.test(shortCode);
     this.verboseLog(`Short code validation: ${valid ? "Valid" : "Invalid"}`);
@@ -193,12 +203,16 @@ var InsertAffiliate = class {
       this.verboseLog("Invalid short code format, aborting");
       return false;
     }
-    const affiliateDetails = await this.getAffiliateDetails(shortCode);
-    if (!affiliateDetails) {
-      this.verboseLog(`Short code '${shortCode}' does not exist or validation failed`);
+    const lookup = await this.getAffiliateLookupResult(shortCode, { trackUsage: true });
+    if (lookup.status !== "found" || !lookup.details) {
+      this.verboseLog(`Short code '${shortCode}' does not exist or validation failed (status: ${lookup.status})`);
       console.error(`[Insert Affiliate] Error: Short code '${shortCode}' does not exist or validation failed.`);
+      if (lookup.status === "lookup_failed") {
+        (_a = options == null ? void 0 : options.onLookupFailed) == null ? void 0 : _a.call(options);
+      }
       return false;
     }
+    const affiliateDetails = lookup.details;
     this.verboseLog(`Short code validated successfully for affiliate: ${affiliateDetails.affiliateName}`);
     console.log(`[Insert Affiliate] Short code validated successfully for affiliate: ${affiliateDetails.affiliateName}`);
     this.verboseLog("Calling setInsertAffiliateIdentifier with short code");
@@ -239,17 +253,44 @@ var InsertAffiliate = class {
     return storedDate;
   }
   /**
-   * Retrieve detailed information about an affiliate by their short code or deep link
-   * This method queries the API and does not store or set the affiliate identifier
+   * Get the Unix timestamp (in milliseconds) when the affiliate attribution will expire
+   * @returns The expiry timestamp in milliseconds, or null if no attribution or no timeout configured
+   */
+  static async getAffiliateExpiryTimestamp() {
+    this.verboseLog("Getting affiliate expiry timestamp...");
+    const storedDateStr = await getValue("affiliateStoredDate");
+    if (!storedDateStr) {
+      this.verboseLog("No stored date found, returning null");
+      return null;
+    }
+    let timeoutMs = this.affiliateAttributionActiveTime;
+    if (timeoutMs === null) {
+      const storedTimeout = await getValue("affiliateAttributionActiveTime");
+      timeoutMs = storedTimeout ? parseInt(storedTimeout, 10) : null;
+    }
+    if (timeoutMs === null) {
+      this.verboseLog("No attribution timeout configured, returning null");
+      return null;
+    }
+    const storedDate = new Date(storedDateStr);
+    const expiryTimestamp = storedDate.getTime() + timeoutMs;
+    this.verboseLog(`Expiry timestamp: ${expiryTimestamp} (stored: ${storedDateStr}, timeout: ${timeoutMs}ms)`);
+    return expiryTimestamp;
+  }
+  /**
+   * Retrieve detailed information about an affiliate by their short code or deep link,
+   * distinguishing "no affiliate matches this code" from "couldn't check" (backend
+   * outage, timeout, rate limit). This method queries the API and does not store or set
+   * the affiliate identifier.
    * @param affiliateCode The short code or deep link to look up
-   * @returns AffiliateDetails if found, null otherwise
+   * @returns an AffiliateLookupResult with a status of 'found', 'not_found', 'lookup_failed', or 'not_configured'
    */
-  static async getAffiliateDetails(affiliateCode) {
+  static async getAffiliateLookupResult(affiliateCode, options) {
     this.verboseLog(`Getting affiliate details for: ${affiliateCode}`);
     const companyCode = this.companyCode || await getValue("companyCode");
     if (!companyCode) {
       this.verboseLog("Cannot get affiliate details: no company code available");
-      return null;
+      return { status: "not_configured", details: null };
     }
     const cleanCode = affiliateCode.includes("-") ? affiliateCode.split("-")[0] : affiliateCode;
     this.verboseLog(`Clean code: ${cleanCode}`);
@@ -259,6 +300,9 @@ var InsertAffiliate = class {
         companyId: companyCode,
         affiliateCode: cleanCode
       };
+      if (options == null ? void 0 : options.trackUsage) {
+        payload.trackUsage = true;
+      }
       this.verboseLog(`Making API call to: ${url}`);
       this.verboseLog(`Payload: ${JSON.stringify(payload)}`);
       const response = await fetch(url, {
@@ -269,26 +313,42 @@ var InsertAffiliate = class {
       this.verboseLog(`API response status: ${response.status}`);
       if (!response.ok) {
         this.verboseLog(`Failed to get affiliate details, status: ${response.status}`);
-        return null;
+        return { status: "lookup_failed", details: null };
       }
       const data = await response.json();
       this.verboseLog(`API response data: ${JSON.stringify(data)}`);
-      if (data.exists && data.affiliate) {
+      if (data.exists) {
+        if (!data.affiliate) {
+          this.verboseLog("Affiliate exists but response is missing affiliate details");
+          return { status: "lookup_failed", details: null };
+        }
         const details = {
           affiliateName: data.affiliate.affiliateName,
           affiliateShortCode: data.affiliate.affiliateShortCode,
           deeplinkUrl: data.affiliate.deeplinkurl
         };
         this.verboseLog(`Successfully retrieved affiliate details for: ${details.affiliateName}`);
-        return details;
+        return { status: "found", details };
       }
       this.verboseLog("Affiliate does not exist");
-      return null;
+      return { status: "not_found", details: null };
     } catch (error) {
       this.verboseLog(`Error fetching affiliate details: ${error}`);
-      return null;
+      return { status: "lookup_failed", details: null };
     }
   }
+  /**
+   * Retrieve detailed information about an affiliate by their short code or deep link.
+   * Kept for backward compatibility: collapses 'not_found' and 'lookup_failed' into the
+   * same null result, exactly as before. Use getAffiliateLookupResult if you need to tell
+   * an invalid code apart from a backend outage.
+   * @param affiliateCode The short code or deep link to look up
+   * @returns AffiliateDetails if found, null otherwise
+   */
+  static async getAffiliateDetails(affiliateCode, options) {
+    const result = await this.getAffiliateLookupResult(affiliateCode, options);
+    return result.details;
+  }
   static async returnCompanyId() {
     this.verboseLog("Getting company ID...");
     const companyCode = this.companyCode || await getValue("companyCode");
@@ -355,18 +415,13 @@ var InsertAffiliate = class {
         this.verboseLog(`Failed to fetch offer code, status: ${response.status}`);
         return null;
       }
-      const offerCode = (await response.text()).replace(/[^a-zA-Z0-9]/g, "");
-      this.verboseLog(`Received offer code: ${offerCode}`);
-      const errorCodes = [
-        "errorofferCodeNotFound",
-        "errorAffiliateoffercodenotfoundinanycompany",
-        "errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas",
-        "Routenotfound"
-      ];
-      if (errorCodes.includes(offerCode)) {
+      const rawOfferCode = await response.text();
+      if (rawOfferCode.includes("errorofferCodeNotFound") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompany") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas") || rawOfferCode.includes("Routenotfound")) {
         this.verboseLog("Offer code not found or invalid");
         return null;
       }
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, "");
+      this.verboseLog(`Received offer code: ${offerCode}`);
       const storageKey = platformType === "stripe" ? "offerCode" : `offerCode_${platformType}`;
       await saveValue(storageKey, offerCode);
       if (platformType === "stripe") {
@@ -385,7 +440,7 @@ var InsertAffiliate = class {
       const companyCode = this.companyCode || await getValue("companyCode");
       if (!companyCode) {
         this.verboseLog("Cannot fetch offer code: no company code available");
-        return;
+        return null;
       }
       const encoded = encodeURIComponent(shortCode);
       const url = `https://api.insertaffiliate.com/v1/affiliateReturnOfferCode/${companyCode}/${encoded}`;
@@ -394,25 +449,22 @@ var InsertAffiliate = class {
       this.verboseLog(`API response status: ${response.status}`);
       if (!response.ok) {
         this.verboseLog(`Failed to fetch offer code, status: ${response.status}`);
-        return;
+        return null;
       }
-      const offerCode = (await response.text()).replace(/[^a-zA-Z0-9]/g, "");
-      this.verboseLog(`Received offer code: ${offerCode}`);
-      const errorCodes = [
-        "errorofferCodeNotFound",
-        "errorAffiliateoffercodenotfoundinanycompany",
-        "errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas",
-        "Routenotfound"
-      ];
-      if (errorCodes.includes(offerCode)) {
+      const rawOfferCode = await response.text();
+      if (rawOfferCode.includes("errorofferCodeNotFound") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompany") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas") || rawOfferCode.includes("Routenotfound")) {
         this.verboseLog("Offer code not found or invalid");
-        return;
+        return null;
       }
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, "");
+      this.verboseLog(`Received offer code: ${offerCode}`);
       this.offerCode = offerCode;
       await saveValue("offerCode", offerCode);
       this.verboseLog(`Offer code stored successfully: ${offerCode}`);
+      return offerCode;
     } catch (error) {
       this.verboseLog(`Error fetching offer code: ${error}`);
+      return null;
     }
   }
   static async trackEvent(eventName) {
@@ -574,18 +626,13 @@ var InsertAffiliate = class {
       this.verboseLog(`API URL: ${url}`);
       const res = await fetch(url);
       this.verboseLog(`API response status: ${res.status}`);
-      const offerCode = (await res.text()).replace(/[^a-zA-Z0-9]/g, "");
-      this.verboseLog(`Received offer code: ${offerCode}`);
-      const errorCodes = [
-        "errorofferCodeNotFound",
-        "errorAffiliateoffercodenotfoundinanycompany",
-        "errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas",
-        "Routenotfound"
-      ];
-      if (errorCodes.includes(offerCode)) {
+      const rawOfferCode = await res.text();
+      if (rawOfferCode.includes("errorofferCodeNotFound") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompany") || rawOfferCode.includes("errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas") || rawOfferCode.includes("Routenotfound")) {
         this.verboseLog("Offer code not found or invalid");
         return;
       }
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, "");
+      this.verboseLog(`Received offer code: ${offerCode}`);
       const redeemUrl = `https://apps.apple.com/redeem?ctx=offercodes&id=${offerCodeUrlId}&code=${offerCode}`;
       this.verboseLog(`Opening redeem URL: ${redeemUrl}`);
       window.open(redeemUrl, "_blank");
@@ -636,6 +683,7 @@ InsertAffiliate.verboseLogging = false;
 InsertAffiliate.insertAffiliateIdentifierChangeCallback = null;
 InsertAffiliate.affiliateAttributionActiveTime = null;
 // in milliseconds
+InsertAffiliate.preventAffiliateTransfer = false;
 InsertAffiliate.offerCode = null;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insert-affiliate-js-sdk",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/sdk/InsertAffiliate.ts

@@ -1,6 +1,6 @@
 // src/sdk/InsertAffiliate.ts
 import { getValue, saveValue } from '../utils/asyncStorage';
-import { generateUUID, generateShortDeviceID } from '../utils/helpers';
+import { generateShortDeviceID, generateUUID } from '../utils/helpers';
 
 interface IapticAndroidReceipt {
   orderId: string;
@@ -25,7 +25,16 @@ export interface AffiliateDetails {
   deeplinkUrl: string;
 }
 
-export type InsertAffiliateIdentifierChangeCallback = (identifier: string | null) => void;
+// 'lookup_failed' (outage, timeout) may be worth retrying. 'not_configured' (no company
+// code set) never will be — it's always a bug in the calling app, not the code or backend.
+export type AffiliateLookupStatus = 'found' | 'not_found' | 'lookup_failed' | 'not_configured';
+
+export interface AffiliateLookupResult {
+  status: AffiliateLookupStatus;
+  details: AffiliateDetails | null;
+}
+
+export type InsertAffiliateIdentifierChangeCallback = (identifier: string | null, offerCode: string | null) => void;
 
 export class InsertAffiliate {
   private static isInitialized: boolean = false;
@@ -33,6 +42,7 @@ export class InsertAffiliate {
   private static verboseLogging: boolean = false;
   private static insertAffiliateIdentifierChangeCallback: InsertAffiliateIdentifierChangeCallback | null = null;
   private static affiliateAttributionActiveTime: number | null = null; // in milliseconds
+  private static preventAffiliateTransfer: boolean = false;
   private static offerCode: string | null = null;
 
   private static verboseLog(message: string): void {
@@ -41,13 +51,20 @@ export class InsertAffiliate {
     }
   }
 
-  static async initialize(code: string | null, verboseLogging: boolean = false, affiliateAttributionActiveTime?: number): Promise<void> {
+  static async initialize(
+    code: string | null,
+    verboseLogging: boolean = false,
+    affiliateAttributionActiveTime?: number,
+    preventAffiliateTransfer: boolean = false
+  ): Promise<void> {
     this.verboseLogging = verboseLogging;
+    this.preventAffiliateTransfer = preventAffiliateTransfer;
 
     if (verboseLogging) {
       this.verboseLog('Starting SDK initialization...');
       this.verboseLog(`Company code provided: ${code ? 'Yes' : 'No'}`);
       this.verboseLog('Verbose logging enabled');
+      this.verboseLog(`Prevent affiliate transfer: ${preventAffiliateTransfer}`);
     }
 
     if (this.isInitialized) {
@@ -154,6 +171,13 @@ export class InsertAffiliate {
       return identifier;
     }
 
+    // Check if transfer is blocked
+    if (this.preventAffiliateTransfer && existingShortCode && existingShortCode !== shortCode) {
+      this.verboseLog(`Transfer blocked: existing affiliate "${existingShortCode}" protected from being replaced by "${shortCode}"`);
+      const identifier = `${existingShortCode}-${userId}`;
+      return identifier;
+    }
+
     this.verboseLog(`Saving short code to storage: ${shortCode}`);
     await saveValue('referrerLink', shortCode);
 
@@ -166,12 +190,12 @@ export class InsertAffiliate {
     this.verboseLog(`Returning identifier: ${identifier}`);
 
     // Auto-fetch and store offer code (use just the short code, not the full identifier)
-    await this.fetchAndStoreOfferCode(shortCode);
+    const offerCode = await this.fetchAndStoreOfferCode(shortCode);
 
     // Trigger callback if one is registered
     if (this.insertAffiliateIdentifierChangeCallback) {
-      this.verboseLog(`Triggering callback with identifier: ${identifier}`);
-      this.insertAffiliateIdentifierChangeCallback(identifier);
+      this.verboseLog(`Triggering callback with identifier: ${identifier}, offerCode: ${offerCode || 'none'}`);
+      this.insertAffiliateIdentifierChangeCallback(identifier, offerCode);
     }
 
     return identifier;
@@ -181,9 +205,11 @@ export class InsertAffiliate {
    * Validates and sets a short code for affiliate tracking
    * Validates the short code against the API before storing
    * @param shortCode The short code to validate and set
+   * @param options.onLookupFailed called when the lookup itself couldn't be completed
+   *   (not just an invalid code) — use it to offer a retry instead of proceeding unattributed.
    * @returns true if the code exists and was successfully validated and stored, false otherwise
    */
-  static async setShortCode(shortCode: string): Promise<boolean> {
+  static async setShortCode(shortCode: string, options?: { onLookupFailed?: () => void }): Promise<boolean> {
     this.verboseLog(`Setting short code. Input: ${shortCode}`);
 
     const valid = /^[a-zA-Z0-9]{3,25}$/.test(shortCode);
@@ -195,12 +221,16 @@ export class InsertAffiliate {
     }
 
     // Validate that the short code exists in the system
-    const affiliateDetails = await this.getAffiliateDetails(shortCode);
-    if (!affiliateDetails) {
-      this.verboseLog(`Short code '${shortCode}' does not exist or validation failed`);
+    const lookup = await this.getAffiliateLookupResult(shortCode, { trackUsage: true });
+    if (lookup.status !== 'found' || !lookup.details) {
+      this.verboseLog(`Short code '${shortCode}' does not exist or validation failed (status: ${lookup.status})`);
       console.error(`[Insert Affiliate] Error: Short code '${shortCode}' does not exist or validation failed.`);
+      if (lookup.status === 'lookup_failed') {
+        options?.onLookupFailed?.();
+      }
       return false;
     }
+    const affiliateDetails = lookup.details;
 
     this.verboseLog(`Short code validated successfully for affiliate: ${affiliateDetails.affiliateName}`);
     console.log(`[Insert Affiliate] Short code validated successfully for affiliate: ${affiliateDetails.affiliateName}`);
@@ -256,18 +286,53 @@ export class InsertAffiliate {
   }
 
   /**
-   * Retrieve detailed information about an affiliate by their short code or deep link
-   * This method queries the API and does not store or set the affiliate identifier
+   * Get the Unix timestamp (in milliseconds) when the affiliate attribution will expire
+   * @returns The expiry timestamp in milliseconds, or null if no attribution or no timeout configured
+   */
+  static async getAffiliateExpiryTimestamp(): Promise<number | null> {
+    this.verboseLog('Getting affiliate expiry timestamp...');
+
+    const storedDateStr = await getValue('affiliateStoredDate');
+    if (!storedDateStr) {
+      this.verboseLog('No stored date found, returning null');
+      return null;
+    }
+
+    // Get timeout value from storage or class property
+    let timeoutMs = this.affiliateAttributionActiveTime;
+    if (timeoutMs === null) {
+      const storedTimeout = await getValue('affiliateAttributionActiveTime');
+      timeoutMs = storedTimeout ? parseInt(storedTimeout, 10) : null;
+    }
+
+    // If no timeout is set, return null (attribution never expires)
+    if (timeoutMs === null) {
+      this.verboseLog('No attribution timeout configured, returning null');
+      return null;
+    }
+
+    const storedDate = new Date(storedDateStr);
+    const expiryTimestamp = storedDate.getTime() + timeoutMs;
+    this.verboseLog(`Expiry timestamp: ${expiryTimestamp} (stored: ${storedDateStr}, timeout: ${timeoutMs}ms)`);
+
+    return expiryTimestamp;
+  }
+
+  /**
+   * Retrieve detailed information about an affiliate by their short code or deep link,
+   * distinguishing "no affiliate matches this code" from "couldn't check" (backend
+   * outage, timeout, rate limit). This method queries the API and does not store or set
+   * the affiliate identifier.
    * @param affiliateCode The short code or deep link to look up
-   * @returns AffiliateDetails if found, null otherwise
+   * @returns an AffiliateLookupResult with a status of 'found', 'not_found', 'lookup_failed', or 'not_configured'
    */
-  static async getAffiliateDetails(affiliateCode: string): Promise<AffiliateDetails | null> {
+  static async getAffiliateLookupResult(affiliateCode: string, options?: { trackUsage?: boolean }): Promise<AffiliateLookupResult> {
     this.verboseLog(`Getting affiliate details for: ${affiliateCode}`);
 
     const companyCode = this.companyCode || await getValue('companyCode');
     if (!companyCode) {
       this.verboseLog('Cannot get affiliate details: no company code available');
-      return null;
+      return { status: 'not_configured', details: null };
     }
 
     // Strip UUID from code if present (e.g., "ABC123-uuid" becomes "ABC123")
@@ -276,11 +341,15 @@ export class InsertAffiliate {
 
     try {
       const url = 'https://api.insertaffiliate.com/V1/checkAffiliateExists';
-      const payload = {
+      const payload: Record<string, any> = {
         companyId: companyCode,
         affiliateCode: cleanCode,
       };
 
+      if (options?.trackUsage) {
+        payload.trackUsage = true;
+      }
+
       this.verboseLog(`Making API call to: ${url}`);
       this.verboseLog(`Payload: ${JSON.stringify(payload)}`);
 
@@ -294,13 +363,19 @@ export class InsertAffiliate {
 
       if (!response.ok) {
         this.verboseLog(`Failed to get affiliate details, status: ${response.status}`);
-        return null;
+        return { status: 'lookup_failed', details: null };
       }
 
       const data = await response.json();
       this.verboseLog(`API response data: ${JSON.stringify(data)}`);
 
-      if (data.exists && data.affiliate) {
+      if (data.exists) {
+        if (!data.affiliate) {
+          // Malformed response, not a real not-found.
+          this.verboseLog('Affiliate exists but response is missing affiliate details');
+          return { status: 'lookup_failed', details: null };
+        }
+
         const details: AffiliateDetails = {
           affiliateName: data.affiliate.affiliateName,
           affiliateShortCode: data.affiliate.affiliateShortCode,
@@ -308,17 +383,30 @@ export class InsertAffiliate {
         };
 
         this.verboseLog(`Successfully retrieved affiliate details for: ${details.affiliateName}`);
-        return details;
+        return { status: 'found', details };
       }
 
       this.verboseLog('Affiliate does not exist');
-      return null;
+      return { status: 'not_found', details: null };
     } catch (error) {
       this.verboseLog(`Error fetching affiliate details: ${error}`);
-      return null;
+      return { status: 'lookup_failed', details: null };
     }
   }
 
+  /**
+   * Retrieve detailed information about an affiliate by their short code or deep link.
+   * Kept for backward compatibility: collapses 'not_found' and 'lookup_failed' into the
+   * same null result, exactly as before. Use getAffiliateLookupResult if you need to tell
+   * an invalid code apart from a backend outage.
+   * @param affiliateCode The short code or deep link to look up
+   * @returns AffiliateDetails if found, null otherwise
+   */
+  static async getAffiliateDetails(affiliateCode: string, options?: { trackUsage?: boolean }): Promise<AffiliateDetails | null> {
+    const result = await this.getAffiliateLookupResult(affiliateCode, options);
+    return result.details;
+  }
+
   static async returnCompanyId(): Promise<string | null> {
     this.verboseLog('Getting company ID...');
     const companyCode = this.companyCode || await getValue('companyCode');
@@ -401,21 +489,23 @@ export class InsertAffiliate {
         return null;
       }
 
-      const offerCode = (await response.text()).replace(/[^a-zA-Z0-9]/g, '');
-      this.verboseLog(`Received offer code: ${offerCode}`);
-
-      const errorCodes = [
-        'errorofferCodeNotFound',
-        'errorAffiliateoffercodenotfoundinanycompany',
-        'errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas',
-        'Routenotfound'
-      ];
+      const rawOfferCode = await response.text();
 
-      if (errorCodes.includes(offerCode)) {
+      // Check for specific error strings from API before cleaning
+      if (
+        rawOfferCode.includes('errorofferCodeNotFound') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompany') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas') ||
+        rawOfferCode.includes('Routenotfound')
+      ) {
         this.verboseLog('Offer code not found or invalid');
         return null;
       }
 
+      // Remove special characters, keep only alphanumeric, underscores, and dashes
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, '');
+      this.verboseLog(`Received offer code: ${offerCode}`);
+
       // Store offer code with platform-specific key
       const storageKey = platformType === 'stripe' ? 'offerCode' : `offerCode_${platformType}`;
       await saveValue(storageKey, offerCode);
@@ -431,7 +521,7 @@ export class InsertAffiliate {
     }
   }
 
-  private static async fetchAndStoreOfferCode(shortCode: string): Promise<void> {
+  private static async fetchAndStoreOfferCode(shortCode: string): Promise<string | null> {
     this.verboseLog(`Fetching offer code for short code: ${shortCode}`);
 
     try {
@@ -439,7 +529,7 @@ export class InsertAffiliate {
       const companyCode = this.companyCode || await getValue('companyCode');
       if (!companyCode) {
         this.verboseLog('Cannot fetch offer code: no company code available');
-        return;
+        return null;
       }
 
       // Use the more efficient endpoint with company code and just the short code
@@ -452,31 +542,34 @@ export class InsertAffiliate {
 
       if (!response.ok) {
         this.verboseLog(`Failed to fetch offer code, status: ${response.status}`);
-        return;
+        return null;
       }
 
-      const offerCode = (await response.text()).replace(/[^a-zA-Z0-9]/g, '');
-      this.verboseLog(`Received offer code: ${offerCode}`);
-
-      // Check for error codes
-      const errorCodes = [
-        'errorofferCodeNotFound',
-        'errorAffiliateoffercodenotfoundinanycompany',
-        'errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas',
-        'Routenotfound'
-      ];
+      const rawOfferCode = await response.text();
 
-      if (errorCodes.includes(offerCode)) {
+      // Check for specific error strings from API before cleaning
+      if (
+        rawOfferCode.includes('errorofferCodeNotFound') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompany') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas') ||
+        rawOfferCode.includes('Routenotfound')
+      ) {
         this.verboseLog('Offer code not found or invalid');
-        return;
+        return null;
       }
 
+      // Remove special characters, keep only alphanumeric, underscores, and dashes
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, '');
+      this.verboseLog(`Received offer code: ${offerCode}`);
+
       // Store offer code
       this.offerCode = offerCode;
       await saveValue('offerCode', offerCode);
       this.verboseLog(`Offer code stored successfully: ${offerCode}`);
+      return offerCode;
     } catch (error) {
       this.verboseLog(`Error fetching offer code: ${error}`);
+      return null;
     }
   }
 
@@ -685,21 +778,23 @@ export class InsertAffiliate {
       const res = await fetch(url);
       this.verboseLog(`API response status: ${res.status}`);
 
-      const offerCode = (await res.text()).replace(/[^a-zA-Z0-9]/g, '');
-      this.verboseLog(`Received offer code: ${offerCode}`);
-
-      const errorCodes = [
-        'errorofferCodeNotFound',
-        'errorAffiliateoffercodenotfoundinanycompany',
-        'errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas',
-        'Routenotfound'
-      ];
+      const rawOfferCode = await res.text();
 
-      if (errorCodes.includes(offerCode)) {
+      // Check for specific error strings from API before cleaning
+      if (
+        rawOfferCode.includes('errorofferCodeNotFound') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompany') ||
+        rawOfferCode.includes('errorAffiliateoffercodenotfoundinanycompanyAffiliatelinkwas') ||
+        rawOfferCode.includes('Routenotfound')
+      ) {
         this.verboseLog('Offer code not found or invalid');
         return;
       }
 
+      // Remove special characters, keep only alphanumeric, underscores, and dashes
+      const offerCode = rawOfferCode.replace(/[^a-zA-Z0-9_-]/g, '');
+      this.verboseLog(`Received offer code: ${offerCode}`);
+
       const redeemUrl = `https://apps.apple.com/redeem?ctx=offercodes&id=${offerCodeUrlId}&code=${offerCode}`;
       this.verboseLog(`Opening redeem URL: ${redeemUrl}`);
       window.open(redeemUrl, '_blank');

package/.claude/settings.local.json

@@ -1,10 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:www.revenuecat.com)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}