insert-affiliate-js-sdk 1.3.0 → 1.5.0

package/src/referrals/referrerTokenStore.ts

@@ -0,0 +1,42 @@
+// src/referrals/referrerTokenStore.ts
+// The device token that lets this browser read its own referrer's stats.
+// One token per company ID in localStorage. Storage can be unavailable
+// (private mode, blocked site data, a full quota), so every access is
+// guarded; when saving throws, the token lives in memory for this page load
+// only and reads fall back to it. The token is never logged.
+
+const KEY_PREFIX = 'insertAffiliateReferrerToken_';
+const memoryTokens: Record<string, string> = {};
+
+const keyFor = (companyId: string): string => `${KEY_PREFIX}${companyId}`;
+
+export const readReferrerToken = (companyId: string): string | null => {
+  let stored: string | null = null;
+  try {
+    stored = localStorage.getItem(keyFor(companyId));
+  } catch {
+    // Storage unreadable; use the in-memory copy.
+  }
+  return stored || memoryTokens[companyId] || null;
+};
+
+/** Returns false when only the in-memory copy could be kept. */
+export const saveReferrerToken = (companyId: string, token: string): boolean => {
+  try {
+    localStorage.setItem(keyFor(companyId), token);
+    delete memoryTokens[companyId];
+    return true;
+  } catch {
+    memoryTokens[companyId] = token;
+    return false;
+  }
+};
+
+export const clearReferrerToken = (companyId: string): void => {
+  delete memoryTokens[companyId];
+  try {
+    localStorage.removeItem(keyFor(companyId));
+  } catch {
+    // Nothing stored that we can reach.
+  }
+};

package/src/sdk/InsertAffiliate.ts

@@ -1,6 +1,27 @@
 // src/sdk/InsertAffiliate.ts
 import { getValue, saveValue } from '../utils/asyncStorage';
-import { generateUUID, generateShortDeviceID } from '../utils/helpers';
+import { generateShortDeviceID, generateUUID } from '../utils/helpers';
+import {
+  buildReferralShareText,
+  fetchMyAffiliateDetails,
+  fetchReferralProgramConfig,
+  MyDetailsFetch,
+  normalizeVerificationCode,
+  postEnrolment,
+  postReferrerIdentity,
+  shareText,
+} from '../referrals/referralApi';
+import { clearReferrerToken, readReferrerToken } from '../referrals/referrerTokenStore';
+import { presentReferAFriend } from '../referrals/referAFriendModal';
+import type {
+  AffiliateEnrolmentResult,
+  MyAffiliateDetails,
+  ReferAFriendHandle,
+  ReferAFriendOptions,
+  ReferralProgramConfig,
+  ReferralShareOutcome,
+  ReferrerAccountOptions,
+} from '../referrals/referralTypes';
 
 interface IapticAndroidReceipt {
   orderId: string;
@@ -25,6 +46,15 @@ export interface AffiliateDetails {
   deeplinkUrl: string;
 }
 
+// '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 {
@@ -35,6 +65,11 @@ export class InsertAffiliate {
   private static affiliateAttributionActiveTime: number | null = null; // in milliseconds
   private static preventAffiliateTransfer: boolean = false;
   private static offerCode: string | null = null;
+  // Last referral details and config seen. shareReferralLink uses only these,
+  // so the share sheet opens without a network round trip (browsers require
+  // the share to follow the user's tap closely).
+  private static lastReferralDetails: MyAffiliateDetails | null = null;
+  private static lastReferralConfig: ReferralProgramConfig | null = null;
 
   private static verboseLog(message: string): void {
     if (this.verboseLogging) {
@@ -196,9 +231,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);
@@ -210,12 +247,16 @@ export class InsertAffiliate {
     }
 
     // Validate that the short code exists in the system
-    const affiliateDetails = await this.getAffiliateDetails(shortCode, { trackUsage: true });
-    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}`);
@@ -304,18 +345,20 @@ 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
+   * 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, options?: { trackUsage?: boolean }): 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")
@@ -346,13 +389,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,
@@ -360,17 +409,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');
@@ -453,21 +515,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);
@@ -507,22 +571,23 @@ export class InsertAffiliate {
         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 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);
@@ -739,21 +804,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');
@@ -763,6 +830,243 @@ export class InsertAffiliate {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // In-app referrals: make the app's own user an affiliate and read their stats
+  // ---------------------------------------------------------------------------
+
+  private static async referralCompanyId(): Promise<string | null> {
+    try {
+      return this.companyCode || await getValue('companyCode');
+    } catch {
+      return this.companyCode;
+    }
+  }
+
+  /**
+   * The device id in this browser's "{shortCode}-{deviceId}" identifier, so the
+   * server can tell a referrer apart from the friends they refer.
+   * Null when storage is unavailable.
+   */
+  private static async referralDeviceId(): Promise<string | null> {
+    try {
+      return await this.getOrCreateUserID();
+    } catch {
+      return null;
+    }
+  }
+
+  private static notInitializedResult(): AffiliateEnrolmentResult {
+    this.verboseLog('Cannot use referrals: no company code available. Call initialize first.');
+    return {
+      status: 'error',
+      errorCode: 'NOT_INITIALIZED',
+      errorMessage: 'The Insert Affiliate SDK is not initialized with a company code.',
+    };
+  }
+
+  /**
+   * Makes the app's user an affiliate (a referrer) of this company.
+   * A new email is created straight away and this device is connected.
+   * An email that is already an affiliate is sent a 6-digit code instead:
+   * the result is `verificationRequired`; finish with verifyAffiliateCode.
+   * @param email The user's email (usually the app's logged-in user)
+   * @param name The user's display name
+   * @param options The user's own accounts (RevenueCat / Adapty app user id,
+   *   Google Play purchase token), used to grant their referral rewards
+   */
+  static async createAffiliateForUser(
+    email: string,
+    name: string,
+    options?: ReferrerAccountOptions
+  ): Promise<AffiliateEnrolmentResult> {
+    this.verboseLog('Creating affiliate for app user...');
+    const companyId = await this.referralCompanyId();
+    if (!companyId) return this.notInitializedResult();
+
+    const result = await postEnrolment('enrol', companyId, {
+      email: (email || '').trim(),
+      name: (name || '').trim(),
+      ...await this.referrerAccountFields(options),
+    }, (message) => this.verboseLog(message));
+    if (result.status !== 'error') this.lastReferralDetails = null;
+    return result;
+  }
+
+  /**
+   * Finishes connecting this device with the 6-digit code emailed by
+   * createAffiliateForUser. On success the device is connected.
+   * @param email The same email passed to createAffiliateForUser
+   * @param code The 6-digit code from the email
+   * @param name Optional display name, used if the affiliate is created now
+   * @param options The user's own accounts, as for createAffiliateForUser
+   */
+  static async verifyAffiliateCode(
+    email: string,
+    code: string,
+    name?: string,
+    options?: ReferrerAccountOptions
+  ): Promise<AffiliateEnrolmentResult> {
+    this.verboseLog('Verifying affiliate code...');
+    const companyId = await this.referralCompanyId();
+    if (!companyId) return this.notInitializedResult();
+
+    const result = await postEnrolment('verify', companyId, {
+      email: (email || '').trim(),
+      code: normalizeVerificationCode(code),
+      name: (name || '').trim(),
+      ...await this.referrerAccountFields(options),
+    }, (message) => this.verboseLog(message));
+    if (result.status !== 'error') this.lastReferralDetails = null;
+    return result;
+  }
+
+  private static async referrerAccountFields(options?: ReferrerAccountOptions): Promise<Record<string, string | undefined>> {
+    return {
+      deviceId: (await this.referralDeviceId()) || undefined,
+      appUserId: options && options.appUserId,
+      playPurchaseToken: options && options.playPurchaseToken,
+    };
+  }
+
+  /**
+   * Saves the connected referrer's own accounts, for apps whose user
+   * subscribes or logs in after joining. The server then grants any
+   * rewards that were waiting for them.
+   * @param options The RevenueCat / Adapty app user id and/or the Google Play purchase token
+   * @returns True when saved; false when no referrer is connected on this device
+   *   or the request failed. A revoked connection is cleared.
+   */
+  static async setReferrerAccount(options: ReferrerAccountOptions): Promise<boolean> {
+    this.verboseLog('Saving referrer account...');
+    const companyId = await this.referralCompanyId();
+    const token = companyId ? readReferrerToken(companyId) : null;
+    if (!companyId || !token) {
+      this.verboseLog('Cannot save referrer account: no referrer connected on this device');
+      return false;
+    }
+    const saved = await postReferrerIdentity(
+      companyId,
+      token,
+      await this.referrerAccountFields(options),
+      (message) => this.verboseLog(message)
+    );
+    if (!readReferrerToken(companyId)) this.lastReferralDetails = null;
+    this.verboseLog(`Referrer account saved: ${saved}`);
+    return saved;
+  }
+
+  private static async loadMyAffiliateDetails(): Promise<MyDetailsFetch> {
+    const companyId = await this.referralCompanyId();
+    const token = companyId ? readReferrerToken(companyId) : null;
+    if (!companyId || !token) {
+      this.verboseLog('No referrer connected on this device');
+      this.lastReferralDetails = null;
+      return { kind: 'signedOut' };
+    }
+    const loaded = await fetchMyAffiliateDetails(companyId, token, (message) => this.verboseLog(message));
+    if (loaded.kind === 'ok') this.lastReferralDetails = loaded.details;
+    if (loaded.kind === 'signedOut') this.lastReferralDetails = null;
+    return loaded;
+  }
+
+  /**
+   * The connected user's affiliate details and referral stats.
+   * Values are for display: grant anything valuable from your server.
+   * @returns The details, or null when this device has no referrer connected
+   *   (or the request failed). A revoked connection is cleared.
+   */
+  static async getMyAffiliateDetails(): Promise<MyAffiliateDetails | null> {
+    this.verboseLog('Getting my affiliate details...');
+    const loaded = await this.loadMyAffiliateDetails();
+    return loaded.kind === 'ok' ? loaded.details : null;
+  }
+
+  /**
+   * Whether this device has a referrer connected for this company.
+   * Local check only, no network.
+   */
+  static async isUserAnAffiliate(): Promise<boolean> {
+    const companyId = await this.referralCompanyId();
+    return !!companyId && !!readReferrerToken(companyId);
+  }
+
+  /** Disconnects the referrer from this device (call on app logout). The affiliate account is kept. */
+  static async signOutAffiliate(): Promise<void> {
+    this.verboseLog('Signing out referrer on this device');
+    const companyId = await this.referralCompanyId();
+    if (companyId) clearReferrerToken(companyId);
+    this.lastReferralDetails = null;
+  }
+
+  /** The company's in-app referral settings (program on/off, copy, colour), or null if unavailable. */
+  static async getReferralProgramConfig(): Promise<ReferralProgramConfig | null> {
+    this.verboseLog('Getting referral program config...');
+    const companyId = await this.referralCompanyId();
+    if (!companyId) {
+      this.verboseLog('Cannot get referral config: no company code available');
+      return null;
+    }
+    const config = await fetchReferralProgramConfig(companyId, (message) => this.verboseLog(message));
+    if (config) this.lastReferralConfig = config;
+    return config;
+  }
+
+  /**
+   * Shares the connected user's referral link with the system share sheet,
+   * or copies it to the clipboard where sharing is unavailable.
+   * Call from a click handler. Browsers only allow sharing and copying
+   * shortly after the tap, so this never waits on the network: it uses the
+   * details from the last getMyAffiliateDetails call and the app name from
+   * the last getReferralProgramConfig call. Load both before the user taps.
+   * Without loaded details it returns 'failed' and starts loading them, so a
+   * later tap can share.
+   * @param message Optional message. May use {link} and {code} placeholders.
+   */
+  static async shareReferralLink(message?: string): Promise<ReferralShareOutcome> {
+    this.verboseLog('Sharing referral link...');
+    const details = this.lastReferralDetails;
+    const config = this.lastReferralConfig;
+    if (!config) void this.getReferralProgramConfig();
+    if (!details) {
+      this.verboseLog('Cannot share: referrer details not loaded. Call getMyAffiliateDetails before the tap');
+      void this.getMyAffiliateDetails();
+      return 'failed';
+    }
+    const text = buildReferralShareText(details, config ? config.companyName : '', message);
+    const outcome = await shareText(text);
+    this.verboseLog(`Share outcome: ${outcome}`);
+    return outcome;
+  }
+
+
+  /**
+   * Presents the drop-in "Refer a friend" modal. Handles enrolment, the
+   * email code step, sharing and stats. Browser only. Only one modal is
+   * shown at a time: calling this while it is open focuses the open one.
+   * @returns A handle whose close() dismisses the modal
+   */
+  static showReferAFriend(options: ReferAFriendOptions = {}): ReferAFriendHandle {
+    if (typeof document === 'undefined' || !document.body) {
+      console.error('[Insert Affiliate] showReferAFriend needs a browser document.');
+      return { close: () => undefined };
+    }
+    if (!this.companyCode) {
+      this.verboseLog('showReferAFriend called before initialize; using the stored company code if any');
+    }
+    const account: ReferrerAccountOptions = {
+      appUserId: options.appUserId,
+      playPurchaseToken: options.playPurchaseToken,
+    };
+    return presentReferAFriend(options, {
+      hasToken: () => this.isUserAnAffiliate(),
+      loadConfig: () => this.getReferralProgramConfig(),
+      loadDetails: () => this.loadMyAffiliateDetails(),
+      enrol: (email, name) => this.createAffiliateForUser(email, name, account),
+      verify: (email, code, name) => this.verifyAffiliateCode(email, code, name, account),
+      saveAccount: () => this.setReferrerAccount(account),
+    });
+  }
+
   private static async getOrCreateUserID(): Promise<string> {
     this.verboseLog('Getting or creating user ID...');
     let id = await getValue('userId');

package/.claude/settings.local.json

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