insert-affiliate-js-sdk 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -6,16 +6,17 @@ interface AffiliateDetails {
     affiliateShortCode: string;
     deeplinkUrl: string;
 }
-type InsertAffiliateIdentifierChangeCallback = (identifier: string | null) => void;
+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>;
@@ -29,15 +30,40 @@ declare class InsertAffiliate {
     static setInsertAffiliateIdentifierChangeCallback(callback: InsertAffiliateIdentifierChangeCallback | null): void;
     static isAffiliateAttributionValid(): Promise<boolean>;
     static getAffiliateStoredDate(): Promise<string | null>;
+    /**
+     * 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
      * 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
      */
-    static getAffiliateDetails(affiliateCode: string): Promise<AffiliateDetails | null>;
+    static getAffiliateDetails(affiliateCode: string, options?: {
+        trackUsage?: boolean;
+    }): Promise<AffiliateDetails | null>;
     static returnCompanyId(): Promise<string | null>;
-    static getOfferCode(): Promise<string | null>;
+    /**
+     * Get the offer code for the current affiliate
+     * @param platformType Optional platform type: 'stripe' (default for web), 'ios', or 'android'
+     * @returns The offer code for the specified platform, or null if not found
+     */
+    static getOfferCode(platformType?: 'ios' | 'android' | 'stripe'): Promise<string | null>;
+    /**
+     * Get the Stripe coupon/promo code for the current affiliate
+     * Convenience method that calls getOfferCode with platformType='stripe'
+     * @returns The Stripe coupon/promo code, or null if not found
+     */
+    static getStripeCouponCode(): Promise<string | null>;
+    /**
+     * Fetch offer code for a specific platform
+     * @param shortCode The affiliate short code
+     * @param platformType The platform type: 'ios', 'android', or 'stripe'
+     * @returns The offer code for the specified platform, or null if not found
+     */
+    private static fetchOfferCodeForPlatform;
     private static fetchAndStoreOfferCode;
     static trackEvent(eventName: string): Promise<void>;
     static returnUserAccountTokenAndStoreExpectedTransaction(): Promise<string | null>;

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;
   }
@@ -193,7 +200,7 @@ var InsertAffiliate = class {
       this.verboseLog("Invalid short code format, aborting");
       return false;
     }
-    const affiliateDetails = await this.getAffiliateDetails(shortCode);
+    const affiliateDetails = await this.getAffiliateDetails(shortCode, { trackUsage: true });
     if (!affiliateDetails) {
       this.verboseLog(`Short code '${shortCode}' does not exist or validation failed`);
       console.error(`[Insert Affiliate] Error: Short code '${shortCode}' does not exist or validation failed.`);
@@ -238,13 +245,38 @@ var InsertAffiliate = class {
     this.verboseLog(`Stored date: ${storedDate || "none"}`);
     return storedDate;
   }
+  /**
+   * 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
    * 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
    */
-  static async getAffiliateDetails(affiliateCode) {
+  static async getAffiliateDetails(affiliateCode, options) {
     this.verboseLog(`Getting affiliate details for: ${affiliateCode}`);
     const companyCode = this.companyCode || await getValue("companyCode");
     if (!companyCode) {
@@ -259,6 +291,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, {
@@ -295,28 +330,97 @@ var InsertAffiliate = class {
     this.verboseLog(`Company ID: ${companyCode || "none"}`);
     return companyCode;
   }
-  static async getOfferCode() {
-    this.verboseLog("Getting offer code...");
-    if (this.offerCode) {
+  /**
+   * Get the offer code for the current affiliate
+   * @param platformType Optional platform type: 'stripe' (default for web), 'ios', or 'android'
+   * @returns The offer code for the specified platform, or null if not found
+   */
+  static async getOfferCode(platformType = "stripe") {
+    this.verboseLog(`Getting offer code for platform: ${platformType}...`);
+    const storageKey = platformType === "stripe" ? "offerCode" : `offerCode_${platformType}`;
+    if (platformType === "stripe" && this.offerCode) {
       this.verboseLog(`Returning cached offer code: ${this.offerCode}`);
       return this.offerCode;
     }
-    const storedOfferCode = await getValue("offerCode");
+    const storedOfferCode = await getValue(storageKey);
     if (storedOfferCode) {
       this.verboseLog(`Returning stored offer code: ${storedOfferCode}`);
-      this.offerCode = storedOfferCode;
+      if (platformType === "stripe") {
+        this.offerCode = storedOfferCode;
+      }
       return storedOfferCode;
     }
+    const shortCode = await getValue("referrerLink");
+    if (shortCode) {
+      this.verboseLog(`No stored offer code, fetching for short code: ${shortCode}`);
+      const fetchedCode = await this.fetchOfferCodeForPlatform(shortCode, platformType);
+      return fetchedCode;
+    }
     this.verboseLog("No offer code found");
     return null;
   }
+  /**
+   * Get the Stripe coupon/promo code for the current affiliate
+   * Convenience method that calls getOfferCode with platformType='stripe'
+   * @returns The Stripe coupon/promo code, or null if not found
+   */
+  static async getStripeCouponCode() {
+    return this.getOfferCode("stripe");
+  }
+  /**
+   * Fetch offer code for a specific platform
+   * @param shortCode The affiliate short code
+   * @param platformType The platform type: 'ios', 'android', or 'stripe'
+   * @returns The offer code for the specified platform, or null if not found
+   */
+  static async fetchOfferCodeForPlatform(shortCode, platformType) {
+    this.verboseLog(`Fetching offer code for platform: ${platformType}, short code: ${shortCode}`);
+    try {
+      const companyCode = this.companyCode || await getValue("companyCode");
+      if (!companyCode) {
+        this.verboseLog("Cannot fetch offer code: no company code available");
+        return null;
+      }
+      const encoded = encodeURIComponent(shortCode);
+      const url = `https://api.insertaffiliate.com/v1/affiliateReturnOfferCode/${companyCode}/${encoded}?platformType=${platformType}`;
+      this.verboseLog(`Making API call to: ${url}`);
+      const response = await fetch(url);
+      this.verboseLog(`API response status: ${response.status}`);
+      if (!response.ok) {
+        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)) {
+        this.verboseLog("Offer code not found or invalid");
+        return null;
+      }
+      const storageKey = platformType === "stripe" ? "offerCode" : `offerCode_${platformType}`;
+      await saveValue(storageKey, offerCode);
+      if (platformType === "stripe") {
+        this.offerCode = offerCode;
+      }
+      this.verboseLog(`Offer code stored successfully with key ${storageKey}: ${offerCode}`);
+      return offerCode;
+    } catch (error) {
+      this.verboseLog(`Error fetching offer code: ${error}`);
+      return null;
+    }
+  }
   static async fetchAndStoreOfferCode(shortCode) {
     this.verboseLog(`Fetching offer code for short code: ${shortCode}`);
     try {
       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}`;
@@ -325,7 +429,7 @@ 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}`);
@@ -337,13 +441,15 @@ var InsertAffiliate = class {
       ];
       if (errorCodes.includes(offerCode)) {
         this.verboseLog("Offer code not found or invalid");
-        return;
+        return null;
       }
       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) {
@@ -567,6 +673,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/docs/deep-linking-web.md

@@ -0,0 +1,199 @@
+# Deep Linking for Web Payments
+
+This guide covers how to configure deep links from Branch.io, AppsFlyer, or Insert Links to correctly pass affiliate parameters to your web checkout.
+
+## Overview
+
+When using web-based payments (Stripe), your deep linking provider needs to redirect users to your web checkout page with the `insertAffiliate` parameter. The Insert Affiliate SDK will automatically detect this parameter and attribute the payment to the correct affiliate.
+
+## Insert Links (Automatic)
+
+If you're using [Insert Links](https://docs.insertaffiliate.com/insert-links) (Insert Affiliate's built-in deep linking solution), no additional configuration is needed for web payments.
+
+Insert Links automatically:
+1. Adds the `insertAffiliate` parameter to URLs
+2. Detects and processes attribution in your web app
+3. Tracks the payment to the correct affiliate
+
+Just initialize the SDK and you're done:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+await InsertAffiliate.initialize('your_company_code');
+// Affiliate parameters are automatically detected from the URL
+```
+
+Learn more: [Insert Links Documentation](https://docs.insertaffiliate.com/insert-links)
+
+## Branch.io Web Redirect Setup
+
+Use these steps if you're using [Branch.io](https://docs.insertaffiliate.com/branch) Quick Links to send users to your web-hosted payment page.
+
+### Creating a Branch.io Quick Link for Web Checkout
+
+1. **Create a new Quick Link** in your Branch.io dashboard
+2. Go to the **Redirects** section
+3. **Select "Web URL"** as the redirect destination
+4. **Configure the URL** to point to your web app:
+   - Enter your web app's URL
+   - Append the parameter: `?insertAffiliate={affiliateShortCode}`
+   - Replace `{affiliateShortCode}` with the actual short code of the affiliate
+
+**Example URL:**
+```
+https://yourwebsite.com/checkout?insertAffiliate=ABC123
+```
+
+Once the user arrives on your site, the Insert Affiliate SDK automatically detects `insertAffiliate` and attributes the payment.
+
+### Branch.io with Capacitor (Hybrid Apps)
+
+For Capacitor apps using the Branch.io plugin:
+
+```javascript
+import { BranchDeepLinks, BranchInitEvent } from 'capacitor-branch-deep-links';
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Set up callback to capture affiliate identifier
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier captured:', identifier);
+  }
+});
+
+let branchInitialised = false;
+
+async function setUpBranchListener() {
+  if (branchInitialised) return;
+  branchInitialised = true;
+
+  try {
+    await BranchDeepLinks.addListener('init', async (event: BranchInitEvent) => {
+      const clicked = event?.referringParams?.['+clicked_branch_link'];
+      const referringLink = event?.referringParams?.['~referring_link'];
+
+      if (clicked && referringLink) {
+        // This will automatically trigger the callback
+        await InsertAffiliate.setInsertAffiliateIdentifier(referringLink);
+      }
+    });
+
+    BranchDeepLinks.addListener('initError', (error: any) => {
+      console.error('Branch init error:', error);
+    });
+  } catch (err) {
+    console.error('Error setting up Branch listener:', err);
+  }
+}
+```
+
+## AppsFlyer Web Redirect Setup
+
+Use these steps if you're using [AppsFlyer](https://docs.insertaffiliate.com/appsflyer) OneLinks to send users to your web checkout.
+
+### Creating an AppsFlyer OneLink for Web Checkout
+
+1. **Create a new OneLink** in your AppsFlyer dashboard
+2. Open the link configuration settings
+3. Under **"When link is clicked on desktop web page"**, set the redirect URL
+4. Enter your web app's checkout URL
+5. Append the parameter: `?insertAffiliate={affiliateShortCode}`
+   - Replace `{affiliateShortCode}` with the actual short code of the affiliate
+
+**Example URL:**
+```
+https://yourwebsite.com/checkout?insertAffiliate=ABC123
+```
+
+The Insert Affiliate SDK will automatically detect the parameter and attribute the resulting payment.
+
+## How the SDK Detects Parameters
+
+When your web app loads, the Insert Affiliate SDK automatically:
+
+1. Checks the URL for `insertAffiliate` parameter
+2. Validates the affiliate code with the Insert Affiliate API
+3. Stores the affiliate identifier for later use
+4. Triggers any registered callbacks
+
+**Automatic URL Detection:**
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Initialize the SDK - it automatically checks URL parameters
+await InsertAffiliate.initialize('your_company_code');
+
+// The affiliate identifier is now available
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+console.log('Detected affiliate:', affiliateId);
+```
+
+## Using the Change Callback
+
+For dynamic updates when an affiliate link is clicked:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Set up callback before initialization
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier changed:', identifier);
+
+    // Update UI
+    const banner = document.getElementById('affiliate-banner');
+    if (banner) {
+      banner.textContent = 'You used a special affiliate link!';
+      banner.style.display = 'block';
+    }
+
+    // Track in analytics
+    analytics.track('affiliate_link_clicked', { identifier });
+  }
+});
+
+await InsertAffiliate.initialize('your_company_code');
+```
+
+## URL Parameter Reference
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `insertAffiliate` | The affiliate's short code | `?insertAffiliate=ABC123` |
+
+## Testing
+
+Test your deep link setup by visiting your web app with the affiliate parameter:
+
+```
+https://yourwebsite.com/checkout?insertAffiliate=TEST123
+```
+
+Then check the console for:
+```
+[Insert Affiliate] Affiliate identifier set: TEST123
+```
+
+## Troubleshooting
+
+**Problem:** Affiliate parameter not detected
+- **Solution:** Ensure the SDK is initialized before the URL parameters are processed
+- Check that the parameter name is exactly `insertAffiliate` (case-sensitive)
+
+**Problem:** Deep link opens app instead of web checkout
+- **Solution:** Configure your deep linking provider to redirect to web URL for web-only flows
+- Check the "Desktop redirect" settings in Branch.io or AppsFlyer
+
+**Problem:** Parameter lost after page navigation
+- **Solution:** The SDK stores the affiliate identifier in local storage, so it persists across pages
+- Verify local storage is not being cleared
+
+## Next Steps
+
+- Configure your deep linking provider to pass `insertAffiliate` parameter
+- Test with a sample affiliate short code
+- Integrate with your payment flow (see [Stripe Integration Guide](./stripe-integration.md))
+
+[Back to Main README](../README.md)