insert-affiliate-js-sdk 1.3.0 → 1.5.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+# Publishes to npm via OIDC trusted publishing (no stored token).
+# Trigger: push a version tag like v1.18.0 matching package.json version.
+# One-time setup on npmjs.com (after any account suspension lifts): package ->
+# Settings -> Trusted Publisher -> GitHub Actions -> this repo + workflow
+# ".github/workflows/publish.yml". Requires npm CLI >= 11.5 (installed below).
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for npm OIDC trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest # npm >= 11.5 for trusted publishing
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm publish

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [Unreleased]
+
+### Added
+- **In-app referrals** - Turn app users into affiliates and show them a "Refer a friend" screen
+  - `createAffiliateForUser()`, `verifyAffiliateCode()`, `getMyAffiliateDetails()`, `isUserAnAffiliate()`, `signOutAffiliate()`, `getReferralProgramConfig()`, `shareReferralLink()`
+  - `showReferAFriend()` drop-in web modal (no dependencies, accessible, themeable)
+  - Exported types: `AffiliateEnrolmentResult`, `MyAffiliateDetails`, `ReferralProgramConfig`, `ReferAFriendOptions`, `ReferAFriendHandle` and related
+- **Referrer rewards** - Let the server grant rewards to referrers automatically
+  - `createAffiliateForUser()` and `verifyAffiliateCode()` take optional `{ appUserId, playPurchaseToken }` and send this browser's device id
+  - `setReferrerAccount()` saves those accounts after joining, so waiting rewards are granted
+  - `MyAffiliateDetails` adds `rewardsGranted`, `premiumUntil` and `rewardCodes`
+  - `showReferAFriend()` takes optional `appUserId` and `playPurchaseToken` and passes them on, so modal-only apps need no extra call
+  - The modal shows "Free premium until {date}" and a "Your rewards" list with a Redeem button per App Store offer code or Google Play promo code; each `ReferralRewardCode` has a `store`
+  - Exported types: `ReferrerAccountOptions`, `ReferralRewardCode`
+- **Modal text overrides** - `showReferAFriend({ strings })` replaces any label in the modal, so a site can translate or reword it
+  - Every key is optional: a missing, blank or unknown key keeps the English default, so nothing changes for apps that do not pass `strings`
+  - `codeSentNotice` keeps `{email}` and `premiumUntil` keeps `{date}`
+  - Exported type: `ReferralStrings`
+
+## [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

@@ -462,6 +462,167 @@ InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(null);
 
 </details>
 
+<details>
+<summary><h3>In-App Referrals (Refer a Friend)</h3></summary>
+
+Turn your own users into affiliates from inside your app, show them a ready-made "Refer a friend" screen, and read their referral stats so you can reward them. Referrers are normal affiliates: they get the same dashboard, referrals tab and commission as any other affiliate.
+
+Switch the program on in your Insert Affiliate dashboard first.
+
+**Drop-in modal (quickest):**
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+document.getElementById('refer-button').addEventListener('click', () => {
+  const modal = InsertAffiliate.showReferAFriend({
+    email: currentUser.email, // prefills the form (usually your logged-in user)
+    name: currentUser.name,
+    onClose: () => console.log('Refer a friend closed'),
+  });
+
+  // modal.close() dismisses it from code
+});
+```
+
+The modal handles everything: the "Get my link" form, the 6-digit email code step for existing affiliates, the code and link with Copy buttons, a Share button, stats (referrals and amount earned), a "Free premium until {date}" line while a premium reward is active, a "Your rewards" list of App Store offer codes or Google Play promo codes with a Redeem button each (opens the store's redemption page in a new tab) and an "Open my dashboard" button. It injects its own scoped styles, needs no framework, closes on Escape or a backdrop click, keeps keyboard focus inside while open, and returns focus afterwards. Only one modal is shown at a time: calling `showReferAFriend` again while it is open focuses the open one.
+
+| Option | Description |
+|--------|-------------|
+| `email`, `name` | Prefill the form |
+| `shareMessage` | Share message. May use `{link}` and `{code}` placeholders |
+| `primaryColor` | Overrides the dashboard colour (any CSS colour). Default `#6A0DAD` |
+| `headline`, `rewardText` | Override the dashboard copy. Default headline "Refer a friend" |
+| `fontFamily`, `cornerRadius` | Match your app's look |
+| `appUserId`, `playPurchaseToken` | The user's own accounts, for automatic referrer rewards. Sent when the user joins, or saved once when the modal opens for a user who already joined |
+| `strings` | Replaces any of the modal's labels, for translating or rewording it |
+| `onClose` | Called once when the modal closes |
+
+Headline, reward text and colour set in the dashboard are used when you do not pass them, so wording changes need no release.
+
+**Translating the modal:** pass `strings` with the keys you want to change. Every key is optional: a missing or blank one keeps the English default, and an unknown one is ignored.
+
+```javascript
+InsertAffiliate.showReferAFriend({
+  headline: 'Parrainez un ami',
+  strings: {
+    emailLabel: 'E-mail',
+    nameLabel: 'Nom',
+    joinButton: 'Obtenir mon lien',
+    codeSentNotice: 'Nous avons envoye un code a 6 chiffres a {email}.',
+    verifyButton: 'Valider',
+    copyCodeButton: 'Copier le code',
+    shareButton: 'Partager',
+    referralsLabel: 'Parrainages',
+    earnedLabel: 'Gagne',
+    premiumUntil: 'Premium gratuit jusqu\'au {date}',
+    errorNetwork: 'Connexion impossible. Verifiez votre connexion.',
+  },
+});
+```
+
+Keep the `{email}` placeholder in `codeSentNotice` and `{date}` in `premiumUntil`; they are filled in for you.
+
+| Group | Keys |
+|-------|------|
+| Joining | `emailLabel`, `nameLabel`, `joinButton`, `joiningButton` |
+| Email code step | `codeLabel`, `codeSentNotice` (`{email}`), `verifyButton`, `verifyingButton`, `resendButton`, `sendingNotice`, `codeResentNotice`, `differentEmailButton`, `errorCodeLength` |
+| Joined | `copyCodeButton`, `copyLinkButton`, `copiedNotice`, `copyFailedNotice`, `shareButton`, `shareFailedNotice`, `referralsLabel`, `earnedLabel`, `premiumUntil` (`{date}`), `rewardsHeading`, `redeemButton`, `dashboardLink` |
+| Frame and states | `closeButton`, `loading`, `tryAgainButton` |
+| Errors | `errorProgramDisabled`, `errorAffiliateLimitReached`, `errorInvalidCode`, `errorTooManyCodes`, `errorRateLimited`, `errorInvalidEmail`, `errorNetwork`, `errorServer` |
+
+`headline` and `rewardText` are not in `strings`: they come from the dashboard and are overridden with their own options. The full type is exported as `ReferralStrings`.
+
+**Build your own screen:**
+
+You can skip the modal and use the methods directly. In the order an app calls them:
+
+1. `getReferralProgramConfig()` to check the program is on (`enabled`) and to read the dashboard copy, colour and `companyName`.
+2. `isUserAnAffiliate()` to see whether this browser is already connected (no network call).
+3. `createAffiliateForUser(email, name, options?)` to join. `status` is `created` (connected, `affiliate` holds the code and link), `verificationRequired` (a 6-digit code was emailed) or `error`.
+4. `verifyAffiliateCode(email, code, name?, options?)` for the code step. Call `createAffiliateForUser` again to send a new code.
+5. `getMyAffiliateDetails()` for the code, link, `referralCount`, `totalEarned`, `currency`, `rewardsGranted`, `premiumUntil`, `rewardCodes` (each with `code`, `store` and `redeemUrl`) and `dashboardUrl`.
+6. `setReferrerAccount({ appUserId, playPurchaseToken })` when the user subscribes or logs in after joining.
+7. `shareReferralLink(message?)` from a click handler, or build your own text from `details.affiliateShortCode` and `details.deeplinkurl`.
+8. `signOutAffiliate()` on logout.
+
+States to handle:
+
+| State | How you know | What to show |
+|-------|--------------|--------------|
+| Program off | `config.enabled === false` | Hide the entry point |
+| Not enrolled | `isUserAnAffiliate()` is false | Your email and name form |
+| Code needed | `status === 'verificationRequired'` | A 6-digit code field, with resend and "use a different email" |
+| Enrolled | `getMyAffiliateDetails()` returns details | The code and link with copy and share, plus the stats |
+| Rewards | `premiumUntil` in the future, or `rewardCodes` is not empty | The premium line, and each code with a link to `redeemUrl` |
+| Errors | `result.status === 'error'`, then `result.errorCode` | Your own wording per code |
+| Disconnected | `getMyAffiliateDetails()` returns `null` while `isUserAnAffiliate()` is false | Back to the join form |
+
+`getMyAffiliateDetails()` returns `null` both when the browser is not connected and when the request failed. Check `isUserAnAffiliate()` afterwards to tell them apart: still `true` means the request failed and is worth retrying.
+
+```javascript
+// 1. Make the user a referrer
+const result = await InsertAffiliate.createAffiliateForUser('jane@example.com', 'Jane');
+
+if (result.status === 'verificationRequired') {
+  // The email is already an affiliate: we emailed a 6-digit code
+  const code = prompt('Enter the code we emailed you');
+  const verified = await InsertAffiliate.verifyAffiliateCode('jane@example.com', code);
+  if (verified.status === 'error') alert(verified.errorMessage);
+} else if (result.status === 'error') {
+  console.log(result.errorCode, result.errorMessage); // e.g. PROGRAM_DISABLED
+}
+
+// 2. Read their stats, and load the program config (the app name used in the share text)
+const [details] = await Promise.all([
+  InsertAffiliate.getMyAffiliateDetails(),
+  InsertAffiliate.getReferralProgramConfig(),
+]);
+if (details) {
+  console.log(details.affiliateShortCode, details.deeplinkurl);
+  console.log(`${details.referralCount} referrals, ${details.totalEarned} ${details.currency} earned`);
+  console.log(`${details.rewardsGranted} rewards, premium until ${details.premiumUntil}`);
+  details.rewardCodes.forEach((reward) => console.log(reward.code, reward.redeemUrl));
+}
+
+// 3. Share (call from a click handler, after step 2 has loaded the details)
+await InsertAffiliate.shareReferralLink(); // 'shared' | 'copied' | 'cancelled' | 'failed'
+
+// On logout
+await InsertAffiliate.signOutAffiliate();
+```
+
+- `createAffiliateForUser` creates a new affiliate and connects this browser straight away. If the email is already an affiliate it never connects on the email alone: it emails a 6-digit code and returns `verificationRequired`.
+- Connecting stores a private token in `localStorage`, one per company. `isUserAnAffiliate()` checks for it without a network call. `signOutAffiliate()` removes it; the affiliate account is kept.
+- If the token stops working (for example the affiliate was removed), `getMyAffiliateDetails()` clears it and returns `null`.
+- `referralCount` is the count for the trigger you chose in the dashboard (install, event or purchase). It only ever goes up.
+- Sharing uses the browser share sheet (`navigator.share`), or copies the text to the clipboard where that is not available. Browsers only allow either shortly after the tap, so `shareReferralLink()` never waits on the network: it uses the details and config already loaded by `getMyAffiliateDetails()` and `getReferralProgramConfig()`, and returns `'failed'` if the details are not loaded yet. Default text: `Try {companyName}: {link}`, or `Use my code {code} in {companyName}` when you use Short Code Only.
+- Error codes: `INVALID_EMAIL`, `INVALID_CODE`, `PROGRAM_DISABLED`, `AFFILIATE_LIMIT_REACHED`, `TOO_MANY_CODES`, `RATE_LIMITED`, `COMPANY_NOT_FOUND`, `NETWORK_ERROR`, `NOT_INITIALIZED`.
+
+**Automatic referrer rewards:** when you set up referrer rewards in the dashboard (RevenueCat, Adapty, App Store offer codes or Google Play), pass the user's own accounts so the reward can be granted to them:
+
+```javascript
+// When they join
+await InsertAffiliate.createAffiliateForUser('jane@example.com', 'Jane', {
+  appUserId: 'RevenueCat or Adapty app user id',
+  playPurchaseToken: 'their own Google Play purchase token', // Android apps only
+});
+// verifyAffiliateCode(email, code, name, options) takes the same options
+
+// Or later, if they subscribe or log in after joining
+const saved = await InsertAffiliate.setReferrerAccount({ appUserId: 'rc_user_123' });
+```
+
+- `setReferrerAccount` needs a connected referrer on this browser and returns `false` otherwise. Any rewards that were waiting for these accounts are granted once they are saved.
+- The SDK also sends this browser's device id (the same one in `returnInsertAffiliateIdentifier()`), so a referrer who uses their own link is not counted as their own referral.
+- `rewardCodes` are App Store offer codes or Google Play promo codes, newest first, each with a `redeemUrl` and a `store` (`app_store` or `google_play`). `premiumUntil` is an ISO date or `null`.
+
+**Rewarding referrers yourself:** values read on the device are for display. A modified browser can show anything, so grant anything valuable (credits, premium time) from your server using the `referral.created` webhook or the Public API. The webhook includes a running `referral_count`, so rewarding up to that number is safe to repeat.
+
+**Store rules:** the SDK only uses the share sheet and never asks for contacts. Never lock features behind sharing, and never reward ratings or reviews.
+
+</details>
+
 ### Prevent Affiliate Transfer
 
 By default, clicking a new affiliate link will overwrite any existing attribution. Enable `preventAffiliateTransfer` to lock the first affiliate:
@@ -504,6 +665,20 @@ Learn more: [Prevent Affiliate Transfer Documentation](https://docs.insertaffili
 | `isAffiliateAttributionValid()` | Check if attribution is still valid | `Promise<boolean>` |
 | `setInsertAffiliateIdentifierChangeCallback(fn)` | Set change callback | `void` |
 
+### In-App Referral Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `createAffiliateForUser(email, name, options?)` | Make the app user a referrer, or email a code if they already are one | `Promise<AffiliateEnrolmentResult>` |
+| `verifyAffiliateCode(email, code, name?, options?)` | Finish connecting with the emailed 6-digit code | `Promise<AffiliateEnrolmentResult>` |
+| `setReferrerAccount(options)` | Save the referrer's app user id or Play purchase token after joining | `Promise<boolean>` |
+| `getMyAffiliateDetails()` | Connected referrer's details and stats | `Promise<MyAffiliateDetails \| null>` |
+| `isUserAnAffiliate()` | Whether a referrer is connected on this device (no network) | `Promise<boolean>` |
+| `signOutAffiliate()` | Disconnect the referrer from this device | `Promise<void>` |
+| `getReferralProgramConfig()` | Program on/off plus dashboard copy and colour | `Promise<ReferralProgramConfig \| null>` |
+| `shareReferralLink(message?)` | Share sheet, or copy to clipboard | `Promise<ReferralShareOutcome>` |
+| `showReferAFriend(options?)` | Show the drop-in modal | `ReferAFriendHandle` |
+
 <details>
 <summary><strong>Detailed Method Documentation</strong></summary>
 

package/dist/index.d.ts

@@ -1,3 +1,188 @@
+/** What the company counts as a referral (set in the Insert Affiliate portal). */
+type ReferralTrigger = 'install' | 'event' | 'purchase';
+/** The referrer's own affiliate record, as returned by enrol and verify. */
+interface ReferrerAffiliate {
+    affiliateName: string;
+    affiliateShortCode: string;
+    /** The link to share. For Short Code Only companies this is the short code itself; empty when no link is assigned yet. */
+    deeplinkurl: string;
+}
+/** The referrer's affiliate record plus referral stats. Values are for display only. */
+interface MyAffiliateDetails extends ReferrerAffiliate {
+    referralTrigger: ReferralTrigger;
+    /** The count for the company's configured trigger. Only ever goes up. */
+    referralCount: number;
+    installCount: number;
+    eventCount: number;
+    purchaseCount: number;
+    totalEarned: number;
+    totalPaid: number;
+    totalUnpaid: number;
+    currency: string;
+    dashboardUrl: string;
+    /** How many referral rewards this user has been granted. */
+    rewardsGranted: number;
+    /** ISO date the user's free premium from referrals runs until, or null. */
+    premiumUntil: string | null;
+    /** App Store offer codes or Google Play promo codes granted as rewards, newest first. */
+    rewardCodes: ReferralRewardCode[];
+}
+/** A referral reward code: an App Store offer code or a Google Play promo code. */
+interface ReferralRewardCode {
+    code: string;
+    /** Opens the store's redemption page with the code filled in. */
+    redeemUrl: string;
+    /** Which store the code is for. Older servers don't send it; those are App Store codes. */
+    store: 'app_store' | 'google_play' | string;
+    /** ISO date the code was granted. */
+    grantedAt: string;
+}
+/**
+ * The referrer's own accounts, so rewards can be granted and a referrer
+ * cannot count as their own referral. Supply whichever the app uses.
+ */
+interface ReferrerAccountOptions {
+    /** The user's RevenueCat app user id or Adapty customer user id. */
+    appUserId?: string;
+    /** The user's own Google Play subscription purchase token. */
+    playPurchaseToken?: string;
+}
+/** Program on/off plus the drop-in UI copy and colour configured in the portal. */
+interface ReferralProgramConfig {
+    enabled: boolean;
+    companyName: string;
+    referralTrigger: ReferralTrigger;
+    headline: string;
+    rewardText: string;
+    /** `#RRGGBB`, or empty when the company has not set one. */
+    primaryColor: string;
+}
+type AffiliateEnrolmentStatus = 'created' | 'connected' | 'verificationRequired' | 'error';
+/**
+ * Server error codes, plus two raised by the SDK itself:
+ * `NETWORK_ERROR` (request failed or the response was unreadable) and
+ * `NOT_INITIALIZED` (no company code; call `initialize` first).
+ */
+type ReferralErrorCode = 'INVALID_EMAIL' | 'INVALID_COMPANY_ID' | 'INVALID_CODE' | 'PROGRAM_DISABLED' | 'AFFILIATE_LIMIT_REACHED' | 'COMPANY_NOT_FOUND' | 'TOO_MANY_CODES' | 'RATE_LIMITED' | 'NETWORK_ERROR' | 'NOT_INITIALIZED' | (string & {});
+interface AffiliateEnrolmentResult {
+    status: AffiliateEnrolmentStatus;
+    affiliate?: ReferrerAffiliate;
+    errorCode?: ReferralErrorCode;
+    errorMessage?: string;
+}
+/** How a share ended: the share sheet completed, the text was copied instead, the user dismissed the sheet, or neither was possible. */
+type ReferralShareOutcome = 'shared' | 'copied' | 'cancelled' | 'failed';
+/**
+ * Every label the "Refer a friend" modal shows, so an app can translate or
+ * reword it. Pass only the keys you want to change: the rest keep the English
+ * defaults, and a blank value keeps the default too. Keep the `{email}` and
+ * `{date}` placeholders in the strings that have them.
+ */
+interface ReferralStrings {
+    /** "Email" */
+    emailLabel: string;
+    /** "Name" */
+    nameLabel: string;
+    /** "Get my link" */
+    joinButton: string;
+    /** "Please wait..." while joining */
+    joiningButton: string;
+    /** "Code" */
+    codeLabel: string;
+    /** "We sent a 6-digit code to {email}. Enter it below to connect this device." */
+    codeSentNotice: string;
+    /** "Verify" */
+    verifyButton: string;
+    /** "Verifying..." while the code is checked */
+    verifyingButton: string;
+    /** "Send a new code" */
+    resendButton: string;
+    /** "Sending..." while a new code is sent */
+    sendingNotice: string;
+    /** "We sent a new code." */
+    codeResentNotice: string;
+    /** "Use a different email" */
+    differentEmailButton: string;
+    /** "Enter the 6-digit code from the email." */
+    errorCodeLength: string;
+    /** "Copy code" */
+    copyCodeButton: string;
+    /** "Copy link" */
+    copyLinkButton: string;
+    /** "Copied" */
+    copiedNotice: string;
+    /** "Could not copy. Select the text to copy it." */
+    copyFailedNotice: string;
+    /** "Share" */
+    shareButton: string;
+    /** "Could not share. Copy your code instead." */
+    shareFailedNotice: string;
+    /** "Referrals" */
+    referralsLabel: string;
+    /** "Earned" */
+    earnedLabel: string;
+    /** "Free premium until {date}" */
+    premiumUntil: string;
+    /** "Your rewards" */
+    rewardsHeading: string;
+    /** "Redeem" */
+    redeemButton: string;
+    /** "Open my dashboard" */
+    dashboardLink: string;
+    /** The close button's accessible name, "Close" */
+    closeButton: string;
+    /** "Loading..." */
+    loading: string;
+    /** "Try again" */
+    tryAgainButton: string;
+    /** PROGRAM_DISABLED */
+    errorProgramDisabled: string;
+    /** AFFILIATE_LIMIT_REACHED */
+    errorAffiliateLimitReached: string;
+    /** INVALID_CODE */
+    errorInvalidCode: string;
+    /** TOO_MANY_CODES */
+    errorTooManyCodes: string;
+    /** RATE_LIMITED */
+    errorRateLimited: string;
+    /** INVALID_EMAIL */
+    errorInvalidEmail: string;
+    /** NETWORK_ERROR, and any unreadable response */
+    errorNetwork: string;
+    /** Every other error, "Something went wrong. Please try again." */
+    errorServer: string;
+}
+interface ReferAFriendOptions {
+    /** Prefills the email field (usually the app's logged-in user). */
+    email?: string;
+    /** Prefills the name field. */
+    name?: string;
+    /** Share message. May use `{link}` and `{code}` placeholders. */
+    shareMessage?: string;
+    /** Overrides the portal colour. Any CSS colour. */
+    primaryColor?: string;
+    /** Overrides the portal headline. */
+    headline?: string;
+    /** Overrides the portal reward text. */
+    rewardText?: string;
+    /** CSS font-family for the modal. Defaults to the system font stack. */
+    fontFamily?: string;
+    /** Corner radius of the modal and its controls, in pixels. Defaults to 12. */
+    cornerRadius?: number;
+    /** The user's RevenueCat app user id or Adapty customer user id, used to grant their referral rewards. */
+    appUserId?: string;
+    /** The user's own Google Play subscription purchase token (Android). */
+    playPurchaseToken?: string;
+    /** Replaces any of the modal's labels, for translating or rewording it. */
+    strings?: Partial<ReferralStrings>;
+    /** Called once after the modal closes, however it was closed. */
+    onClose?: () => void;
+}
+interface ReferAFriendHandle {
+    /** Closes the modal. Safe to call more than once. */
+    close(): void;
+}
+
 interface IapticIOSReceipt {
     transactionReceipt: string;
 }
@@ -6,6 +191,11 @@ interface AffiliateDetails {
     affiliateShortCode: string;
     deeplinkUrl: string;
 }
+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;
@@ -15,6 +205,8 @@ declare class InsertAffiliate {
     private static affiliateAttributionActiveTime;
     private static preventAffiliateTransfer;
     private static offerCode;
+    private static lastReferralDetails;
+    private static lastReferralConfig;
     private static verboseLog;
     static initialize(code: string | null, verboseLogging?: boolean, affiliateAttributionActiveTime?: number, preventAffiliateTransfer?: boolean): Promise<void>;
     private static checkForInsertAffiliateParam;
@@ -24,9 +216,13 @@ 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>;
@@ -36,8 +232,21 @@ declare class InsertAffiliate {
      */
     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
+     * 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
      */
@@ -72,8 +281,82 @@ declare class InsertAffiliate {
         transactionReceipt: string;
     }, iapticAppId: string, iapticAppName: string, iapticPublicKey: string): Promise<boolean>;
     static fetchAndConditionallyOpenUrl(affiliateLink: string, offerCodeUrlId: string): Promise<void>;
+    private static referralCompanyId;
+    /**
+     * 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 referralDeviceId;
+    private static notInitializedResult;
+    /**
+     * 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 createAffiliateForUser(email: string, name: string, options?: ReferrerAccountOptions): Promise<AffiliateEnrolmentResult>;
+    /**
+     * 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 verifyAffiliateCode(email: string, code: string, name?: string, options?: ReferrerAccountOptions): Promise<AffiliateEnrolmentResult>;
+    private static referrerAccountFields;
+    /**
+     * 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 setReferrerAccount(options: ReferrerAccountOptions): Promise<boolean>;
+    private static loadMyAffiliateDetails;
+    /**
+     * 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 getMyAffiliateDetails(): Promise<MyAffiliateDetails | null>;
+    /**
+     * Whether this device has a referrer connected for this company.
+     * Local check only, no network.
+     */
+    static isUserAnAffiliate(): Promise<boolean>;
+    /** Disconnects the referrer from this device (call on app logout). The affiliate account is kept. */
+    static signOutAffiliate(): Promise<void>;
+    /** The company's in-app referral settings (program on/off, copy, colour), or null if unavailable. */
+    static getReferralProgramConfig(): Promise<ReferralProgramConfig | null>;
+    /**
+     * 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 shareReferralLink(message?: string): Promise<ReferralShareOutcome>;
+    /**
+     * 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;
     private static getOrCreateUserID;
     private static fetchShortLink;
 }
 
-export { type AffiliateDetails, InsertAffiliate, type InsertAffiliateIdentifierChangeCallback };
+export { type AffiliateDetails, type AffiliateEnrolmentResult, type AffiliateEnrolmentStatus, type AffiliateLookupResult, type AffiliateLookupStatus, InsertAffiliate, type InsertAffiliateIdentifierChangeCallback, type MyAffiliateDetails, type ReferAFriendHandle, type ReferAFriendOptions, type ReferralErrorCode, type ReferralProgramConfig, type ReferralRewardCode, type ReferralShareOutcome, type ReferralStrings, type ReferralTrigger, type ReferrerAccountOptions, type ReferrerAffiliate };