insert-affiliate-js-sdk 1.1.0 → 1.3.0

package/docs/stripe-integration.md

@@ -0,0 +1,237 @@
+# Stripe Integration Guide
+
+This guide covers all Stripe-based payment integrations for affiliate tracking with Insert Affiliate.
+
+## Prerequisites
+
+- Insert Affiliate SDK initialized in your web application
+- Stripe account connected to Insert Affiliate (see [Connect Stripe Account](#1-connect-your-stripe-account) below)
+
+## 1. Connect Your Stripe Account
+
+Before integrating the SDK code, you must connect your Stripe account to Insert Affiliate:
+
+1. Go to your [Insert Affiliate dashboard settings](https://app.insertaffiliate.com/settings)
+2. Navigate to the payment verification settings
+3. Select **Stripe** as your verification method
+4. Click **Connect with Stripe** to authorize the connection via Stripe Connect
+5. Once connected, Insert Affiliate will automatically receive your Stripe events
+
+## 2. Direct Stripe Checkout Integration
+
+For web-based subscriptions and payments using Stripe Checkout directly.
+
+### Frontend Code
+
+Retrieve the affiliate identifier and company ID before creating a checkout session:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+const companyId = await InsertAffiliate.returnCompanyId();
+
+const response = await fetch('https://your-backend.com/create-checkout-session', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    priceId: 'price_xxxxx',
+    insertAffiliate: affiliateId,
+    insertAffiliateCompanyId: companyId,
+    successUrl: window.location.origin + '/success',
+    cancelUrl: window.location.origin + '/canceled',
+  }),
+});
+
+const { sessionId } = await response.json();
+// Redirect to Stripe Checkout
+```
+
+### Backend Code (Node.js)
+
+Store both the affiliate identifier and company ID in Stripe metadata:
+
+```javascript
+const stripe = require('stripe')('sk_test_xxxxx');
+
+app.post('/create-checkout-session', async (req, res) => {
+  const { priceId, insertAffiliate, insertAffiliateCompanyId, successUrl, cancelUrl } = req.body;
+
+  const session = await stripe.checkout.sessions.create({
+    mode: 'subscription',
+    line_items: [{
+      price: priceId,
+      quantity: 1,
+    }],
+    metadata: {
+      insertAffiliate: insertAffiliate || '',
+      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
+    },
+    subscription_data: {
+      metadata: {
+        insertAffiliate: insertAffiliate || '',
+        insertAffiliateCompanyId: insertAffiliateCompanyId || '',
+      },
+    },
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+  });
+
+  res.json({ sessionId: session.id });
+});
+```
+
+**Required Metadata Fields:**
+- `insertAffiliate`: The affiliate's short code
+- `insertAffiliateCompanyId`: Your Insert Affiliate company ID
+
+Both fields are required for proper affiliate attribution and commission tracking.
+
+## 3. Stripe Billing with RevenueCat
+
+If you're using RevenueCat's [Stripe Billing](https://www.revenuecat.com/docs/web/integrations/stripe), you can track affiliate conversions through Insert Affiliate while using RevenueCat for subscription management.
+
+**Prerequisites:**
+- You must host your own web checkout page where Stripe Checkout is embedded
+- Follow RevenueCat's [Stripe integration guide](https://www.revenuecat.com/docs/web/integrations/stripe)
+
+**Integration:**
+
+Follow the same steps as [Direct Stripe Checkout Integration](#2-direct-stripe-checkout-integration) above. Since you've connected your Stripe account via Stripe Connect, Insert Affiliate will automatically receive all Stripe events. RevenueCat handles subscription management, while Insert Affiliate handles affiliate attribution through the Stripe metadata.
+
+## 4. RevenueCat Web Billing Integration
+
+If you're using [RevenueCat's Web SDK with Web Billing](https://www.revenuecat.com/docs/web/web-billing/overview), pass UTM parameters as purchase metadata.
+
+**Prerequisites:**
+- RevenueCat Web SDK installed and configured
+- RevenueCat Web Billing set up with Stripe
+- Insert Affiliate SDK initialized on your page
+- Stripe account connected via Stripe Connect
+
+### Implementation
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+import { Purchases } from '@revenuecat/purchases-js';
+
+// Initialize both SDKs
+await InsertAffiliate.initialize('your_company_code');
+const purchases = Purchases.configure('your_revenuecat_web_api_key');
+
+// Get affiliate information
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
+const companyId = await InsertAffiliate.returnCompanyId();
+
+// Prepare metadata with UTM parameters
+const metadata: Record<string, string> = {};
+
+if (affiliateId && affiliateId !== 'none') {
+  metadata.utm_source = 'insertAffiliate';
+  metadata.utm_medium = companyId || 'none';
+  metadata.utm_campaign = affiliateId;
+}
+
+// Get offerings and make purchase
+const offerings = await purchases.getOfferings();
+const selectedPackage = offerings.current?.availablePackages[0];
+
+if (selectedPackage) {
+  const { customerInfo } = await purchases.purchase({
+    rcPackage: selectedPackage,
+    metadata: metadata,
+  });
+  console.log('Purchase successful!');
+}
+```
+
+**UTM Parameter Mapping:**
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `utm_source` | `'insertAffiliate'` | Identifies Insert Affiliate conversions |
+| `utm_medium` | Your company ID | Links to your Insert Affiliate account |
+| `utm_campaign` | Affiliate identifier | Credits the specific affiliate |
+
+## 5. RevenueCat Web Purchase Links
+
+If you're using [RevenueCat Web Purchase Links](https://www.revenuecat.com/docs/web/web-billing/web-purchase-links) for online campaigns, append UTM parameters to the links.
+
+### URL Format
+
+Base URL:
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/
+```
+
+With affiliate parameters:
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/?utm_source=insertAffiliate&utm_medium={companyId}&utm_campaign={affiliateShortCode}
+```
+
+### Full Example
+
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaxa/?utm_source=insertAffiliate&utm_medium=12345&utm_campaign=AFF123
+```
+
+Where:
+- `utm_source=insertAffiliate` - Identifies this as an Insert Affiliate conversion
+- `utm_medium=12345` - Your Insert Affiliate company ID
+- `utm_campaign=AFF123` - The affiliate's short code
+
+The Insert Affiliate SDK automatically processes the UTM parameters when users open these URLs and attributes the resulting purchase to the correct affiliate.
+
+## Using the Callback for Automatic Integration
+
+The SDK provides a callback that fires whenever the affiliate identifier changes, making it easy to automatically update your checkout flow:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+let currentAffiliateId = null;
+
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier changed:', identifier);
+    currentAffiliateId = identifier;
+  }
+});
+
+// Later, when creating a Stripe checkout session
+const companyId = await InsertAffiliate.returnCompanyId();
+
+const response = await fetch('/create-checkout-session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    priceId: 'price_xxxxx',
+    insertAffiliate: currentAffiliateId,
+    insertAffiliateCompanyId: companyId,
+    successUrl: window.location.origin + '/success',
+    cancelUrl: window.location.origin + '/canceled',
+  }),
+});
+```
+
+## Troubleshooting
+
+**Problem:** Affiliate not credited for purchase
+- **Solution:** Verify both `insertAffiliate` and `insertAffiliateCompanyId` are included in Stripe metadata
+- Check that your Stripe account is connected via Stripe Connect in the Insert Affiliate dashboard
+
+**Problem:** Metadata not appearing in Stripe
+- **Solution:** Ensure metadata is passed to both `metadata` and `subscription_data.metadata` in the checkout session
+
+**Problem:** UTM parameters not being captured
+- **Solution:** Initialize the Insert Affiliate SDK before users interact with purchase flows
+- Verify the SDK is processing URL parameters on page load
+
+## Next Steps
+
+- Test with a test affiliate link to verify attribution
+- Make a test purchase to confirm tracking works end-to-end
+- Monitor conversions in your Insert Affiliate dashboard
+
+[Back to Main README](../README.md)

package/package.json

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

package/src/sdk/InsertAffiliate.ts

@@ -25,7 +25,7 @@ export interface AffiliateDetails {
   deeplinkUrl: string;
 }
 
-export type InsertAffiliateIdentifierChangeCallback = (identifier: string | null) => void;
+export type InsertAffiliateIdentifierChangeCallback = (identifier: string | null, offerCode: string | null) => void;
 
 export class InsertAffiliate {
   private static isInitialized: boolean = false;
@@ -33,6 +33,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 +42,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 +162,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 +181,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;
@@ -195,7 +210,7 @@ export class InsertAffiliate {
     }
 
     // Validate that the short code exists in the system
-    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.`);
@@ -255,13 +270,46 @@ export class InsertAffiliate {
     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(): 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
    * 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: string): Promise<AffiliateDetails | null> {
+  static async getAffiliateDetails(affiliateCode: string, options?: { trackUsage?: boolean }): Promise<AffiliateDetails | null> {
     this.verboseLog(`Getting affiliate details for: ${affiliateCode}`);
 
     const companyCode = this.companyCode || await getValue('companyCode');
@@ -276,11 +324,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)}`);
 
@@ -326,28 +378,112 @@ export class InsertAffiliate {
     return companyCode;
   }
 
-  static async getOfferCode(): Promise<string | null> {
-    this.verboseLog('Getting offer code...');
+  /**
+   * 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: 'ios' | 'android' | 'stripe' = 'stripe'): Promise<string | null> {
+    this.verboseLog(`Getting offer code for platform: ${platformType}...`);
+
+    const storageKey = platformType === 'stripe' ? 'offerCode' : `offerCode_${platformType}`;
 
-    // Return cached offer code if available
-    if (this.offerCode) {
+    // Return cached offer code if available (only for default Stripe)
+    if (platformType === 'stripe' && this.offerCode) {
       this.verboseLog(`Returning cached offer code: ${this.offerCode}`);
       return this.offerCode;
     }
 
     // Try to get from storage
-    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;
     }
 
+    // If not in storage, try to fetch it
+    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;
   }
 
-  private static async fetchAndStoreOfferCode(shortCode: string): Promise<void> {
+  /**
+   * 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(): Promise<string | null> {
+    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
+   */
+  private static async fetchOfferCodeForPlatform(shortCode: string, platformType: 'ios' | 'android' | 'stripe'): Promise<string | null> {
+    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;
+      }
+
+      // Store offer code with platform-specific key
+      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;
+    }
+  }
+
+  private static async fetchAndStoreOfferCode(shortCode: string): Promise<string | null> {
     this.verboseLog(`Fetching offer code for short code: ${shortCode}`);
 
     try {
@@ -355,7 +491,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
@@ -368,7 +504,7 @@ 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, '');
@@ -384,15 +520,17 @@ export class InsertAffiliate {
 
       if (errorCodes.includes(offerCode)) {
         this.verboseLog('Offer code not found or invalid');
-        return;
+        return null;
       }
 
       // 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;
     }
   }