insert-affiliate-js-sdk 1.4.0 → 1.5.0

package/src/referrals/referralApi.ts

@@ -0,0 +1,385 @@
+// src/referrals/referralApi.ts
+// HTTP calls and response parsing for the /V1/sdk/affiliate endpoints.
+// The parsers are pure so they can be checked without a network.
+import type {
+  AffiliateEnrolmentResult,
+  MyAffiliateDetails,
+  ReferralProgramConfig,
+  ReferralRewardCode,
+  ReferralShareOutcome,
+  ReferralTrigger,
+  ReferrerAffiliate,
+} from './referralTypes';
+import { clearReferrerToken, readReferrerToken, saveReferrerToken } from './referrerTokenStore';
+
+const BASE_URL = 'https://api.insertaffiliate.com/V1/sdk/affiliate';
+const TOKEN_HEADER = 'X-Insert-Affiliate-Token';
+const PLATFORM = 'web';
+const TRIGGERS: ReferralTrigger[] = ['install', 'event', 'purchase'];
+
+export type ReferralLog = (message: string) => void;
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+const num = (value: unknown): number => {
+  const n = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(n) ? n : 0;
+};
+
+const trigger = (value: unknown): ReferralTrigger =>
+  TRIGGERS.includes(value as ReferralTrigger) ? (value as ReferralTrigger) : 'purchase';
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+export const parseReferrerAffiliate = (raw: unknown): ReferrerAffiliate => {
+  const data = isObject(raw) ? raw : {};
+  return {
+    affiliateName: str(data.affiliateName),
+    affiliateShortCode: str(data.affiliateShortCode),
+    deeplinkurl: str(data.deeplinkurl),
+  };
+};
+
+const parseRewardCodes = (value: unknown): ReferralRewardCode[] =>
+  (Array.isArray(value) ? value : [])
+    .filter(isObject)
+    .map((item) => ({
+      code: str(item.code),
+      redeemUrl: str(item.redeemUrl),
+      store: str(item.store) || 'app_store',
+      grantedAt: str(item.grantedAt),
+    }))
+    .filter((item) => item.code);
+
+export const parseMyAffiliateDetails = (raw: unknown): MyAffiliateDetails => {
+  const data = isObject(raw) ? raw : {};
+  return {
+    ...parseReferrerAffiliate(data),
+    referralTrigger: trigger(data.referralTrigger),
+    referralCount: num(data.referralCount),
+    installCount: num(data.installCount),
+    eventCount: num(data.eventCount),
+    purchaseCount: num(data.purchaseCount),
+    totalEarned: num(data.totalEarned),
+    totalPaid: num(data.totalPaid),
+    totalUnpaid: num(data.totalUnpaid),
+    currency: str(data.currency) || 'USD',
+    dashboardUrl: str(data.dashboardUrl),
+    rewardsGranted: num(data.rewardsGranted),
+    premiumUntil: str(data.premiumUntil) || null,
+    rewardCodes: parseRewardCodes(data.rewardCodes),
+  };
+};
+
+export const parseReferralProgramConfig = (raw: unknown): ReferralProgramConfig => {
+  const data = isObject(raw) ? raw : {};
+  const color = str(data.primaryColor);
+  return {
+    enabled: data.enabled === true,
+    companyName: str(data.companyName),
+    referralTrigger: trigger(data.referralTrigger),
+    headline: str(data.headline),
+    rewardText: str(data.rewardText),
+    primaryColor: /^#[0-9a-fA-F]{6}$/.test(color) ? color : '',
+  };
+};
+
+const errorResult = (code: string, message: string): AffiliateEnrolmentResult => ({
+  status: 'error',
+  errorCode: code,
+  errorMessage: message,
+});
+
+/**
+ * Turns an enrol or verify response into a result. A token is only returned
+ * alongside `created` or `connected`; the caller stores it.
+ */
+export const parseEnrolmentResponse = (
+  httpStatus: number,
+  body: unknown
+): { result: AffiliateEnrolmentResult; token: string | null } => {
+  const data = isObject(body) ? body : {};
+
+  if (httpStatus < 200 || httpStatus >= 300) {
+    return {
+      result: errorResult(
+        str(data.code) || `HTTP_${httpStatus}`,
+        str(data.error) || `Request failed with status ${httpStatus}.`
+      ),
+      token: null,
+    };
+  }
+
+  if (data.status === 'verificationRequired') {
+    return { result: { status: 'verificationRequired' }, token: null };
+  }
+
+  const token = str(data.token);
+  if ((data.status === 'created' || data.status === 'connected') && token) {
+    return {
+      result: { status: data.status, affiliate: parseReferrerAffiliate(data.affiliate) },
+      token,
+    };
+  }
+
+  return { result: errorResult('NETWORK_ERROR', 'Unexpected response from the server.'), token: null };
+};
+
+// Built at runtime: the compile target (ES2017) predates regex property escapes.
+const DECIMAL_DIGIT = new RegExp('\\p{Nd}', 'u');
+
+/**
+ * The emailed verification code as ASCII digits. Any Unicode decimal digit
+ * (Arabic-Indic, full-width and so on) becomes its 0-9 value; spaces, dashes
+ * and every other character are dropped.
+ */
+export const normalizeVerificationCode = (value: unknown): string => {
+  let out = '';
+  Array.from(String(value == null ? '' : value)).forEach((char) => {
+    if (char >= '0' && char <= '9') {
+      out += char;
+      return;
+    }
+    if (!DECIMAL_DIGIT.test(char)) return;
+    // Unicode encodes decimal digits in contiguous runs of whole 0-9 sets,
+    // so the value is the distance from the start of the run, mod 10.
+    const point = char.codePointAt(0) as number;
+    let start = point;
+    while (start > 0 && DECIMAL_DIGIT.test(String.fromCodePoint(start - 1))) start -= 1;
+    out += String((point - start) % 10);
+  });
+  return out;
+};
+
+// ---------------------------------------------------------------------------
+// Share text
+// ---------------------------------------------------------------------------
+
+/**
+ * The text to share. A real link shares "<message> <link>" (default message
+ * "Try {companyName}:"). Short Code Only companies (the "link" is the code
+ * itself) share "Use my code {code} in {companyName}". An app message that
+ * contains `{link}` or `{code}` is used as is with those filled in.
+ * Returns an empty string when there is nothing to share.
+ */
+export const buildReferralShareText = (
+  affiliate: Pick<ReferrerAffiliate, 'affiliateShortCode' | 'deeplinkurl'>,
+  companyName: string,
+  message?: string
+): string => {
+  const code = affiliate.affiliateShortCode || '';
+  const hasLink = /^http/i.test(affiliate.deeplinkurl || '');
+  const link = hasLink ? affiliate.deeplinkurl : code;
+  const appName = companyName || 'the app';
+  const custom = (message || '').trim();
+
+  if (!link) return '';
+
+  if (custom && /\{link\}|\{code\}/.test(custom)) {
+    return custom.replace(/\{link\}/g, link).replace(/\{code\}/g, code);
+  }
+  if (hasLink) {
+    return `${custom || `Try ${companyName || 'this app'}:`} ${link}`;
+  }
+  return custom ? `${custom} ${code}` : `Use my code ${code} in ${appName}`;
+};
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const readJson = async (response: Response): Promise<unknown> => {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+};
+
+/** Drops empty and missing values, so optional fields are only sent when set. */
+export const withoutEmpty = (payload: Record<string, string | null | undefined>): Record<string, string> => {
+  const out: Record<string, string> = {};
+  Object.keys(payload).forEach((key) => {
+    const value = payload[key];
+    if (typeof value === 'string' && value.trim()) out[key] = value.trim();
+  });
+  return out;
+};
+
+const networkError = (): AffiliateEnrolmentResult =>
+  errorResult('NETWORK_ERROR', 'Could not reach Insert Affiliate. Check the connection and try again.');
+
+/** GET /config/{companyId}. Null when the request fails. */
+export const fetchReferralProgramConfig = async (
+  companyId: string,
+  log: ReferralLog
+): Promise<ReferralProgramConfig | null> => {
+  const url = `${BASE_URL}/config/${encodeURIComponent(companyId)}`;
+  log(`Making API call to: ${url}`);
+  try {
+    const response = await fetch(url);
+    log(`Referral config response status: ${response.status}`);
+    if (!response.ok) return null;
+    return parseReferralProgramConfig(await readJson(response));
+  } catch (error) {
+    log(`Error fetching referral config: ${error}`);
+    return null;
+  }
+};
+
+/** POST /enrol or /verify, storing the token on success. Never logs the body (it holds the token). */
+export const postEnrolment = async (
+  path: 'enrol' | 'verify',
+  companyId: string,
+  payload: Record<string, string | undefined>,
+  log: ReferralLog
+): Promise<AffiliateEnrolmentResult> => {
+  const url = `${BASE_URL}/${path}`;
+  log(`Making API call to: ${url}`);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ companyId, platform: PLATFORM, ...withoutEmpty(payload) }),
+    });
+    log(`Referral ${path} response status: ${response.status}`);
+
+    const { result, token } = parseEnrolmentResponse(response.status, await readJson(response));
+    if (token && !saveReferrerToken(companyId, token)) {
+      log('localStorage unavailable; referrer token kept for this page load only');
+    }
+    log(`Referral ${path} result: ${result.status}${result.errorCode ? ` (${result.errorCode})` : ''}`);
+    return result;
+  } catch (error) {
+    log(`Network error during referral ${path}: ${error}`);
+    return networkError();
+  }
+};
+
+/**
+ * True when the server says the token itself no longer works: 401
+ * INVALID_TOKEN or 404 AFFILIATE_NOT_FOUND. Other 401/404 responses (a proxy,
+ * a wrong URL) leave the token alone.
+ */
+export const isRevokedTokenResponse = (httpStatus: number, body: unknown): boolean => {
+  const code = isObject(body) ? str(body.code) : '';
+  return (httpStatus === 401 && code === 'INVALID_TOKEN') || (httpStatus === 404 && code === 'AFFILIATE_NOT_FOUND');
+};
+
+/**
+ * Clears the stored token after the server revoked `sentToken`, unless another
+ * request has already stored a newer one.
+ */
+const clearRevokedToken = (companyId: string, sentToken: string, log: ReferralLog): void => {
+  if (readReferrerToken(companyId) !== sentToken) {
+    log('Referrer token no longer valid; a newer token is stored, keeping it');
+    return;
+  }
+  clearReferrerToken(companyId);
+  log('Referrer token no longer valid; cleared');
+};
+
+export type MyDetailsFetch =
+  | { kind: 'ok'; details: MyAffiliateDetails }
+  | { kind: 'signedOut' }
+  | { kind: 'failed' };
+
+/**
+ * GET /me with the device token. A revoked token (401 INVALID_TOKEN or
+ * 404 AFFILIATE_NOT_FOUND) is cleared and the user counts as signed out.
+ */
+export const fetchMyAffiliateDetails = async (
+  companyId: string,
+  token: string,
+  log: ReferralLog
+): Promise<MyDetailsFetch> => {
+  const url = `${BASE_URL}/me`;
+  log(`Making API call to: ${url}`);
+  try {
+    const response = await fetch(url, { headers: { [TOKEN_HEADER]: token } });
+    log(`Referral details response status: ${response.status}`);
+
+    const body = await readJson(response);
+    if (isRevokedTokenResponse(response.status, body)) {
+      clearRevokedToken(companyId, token, log);
+      return { kind: 'signedOut' };
+    }
+    if (!response.ok || !isObject(body)) return { kind: 'failed' };
+    return { kind: 'ok', details: parseMyAffiliateDetails(body) };
+  } catch (error) {
+    log(`Error fetching referral details: ${error}`);
+    return { kind: 'failed' };
+  }
+};
+
+/**
+ * POST /me/identity with the device token: saves the referrer's own accounts
+ * (app user id, Play purchase token, device id). A revoked token is cleared
+ * like fetchMyAffiliateDetails. True when the server saved them.
+ */
+export const postReferrerIdentity = async (
+  companyId: string,
+  token: string,
+  payload: Record<string, string | null | undefined>,
+  log: ReferralLog
+): Promise<boolean> => {
+  const url = `${BASE_URL}/me/identity`;
+  log(`Making API call to: ${url}`);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', [TOKEN_HEADER]: token },
+      body: JSON.stringify(withoutEmpty(payload)),
+    });
+    log(`Referrer identity response status: ${response.status}`);
+
+    const body = await readJson(response);
+    if (isRevokedTokenResponse(response.status, body)) {
+      clearRevokedToken(companyId, token, log);
+      return false;
+    }
+    return response.ok && isObject(body) && body.saved === true;
+  } catch (error) {
+    log(`Error saving referrer identity: ${error}`);
+    return false;
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Sharing (browser)
+// ---------------------------------------------------------------------------
+
+export const copyText = async (text: string): Promise<boolean> => {
+  try {
+    if (typeof navigator !== 'undefined' && navigator.clipboard && navigator.clipboard.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // Clipboard blocked (no permission or no user gesture).
+  }
+  return false;
+};
+
+/**
+ * Opens the system share sheet, or copies the text when sharing is not
+ * available. Only the share sheet is used: no contacts access.
+ */
+export const shareText = async (text: string): Promise<ReferralShareOutcome> => {
+  if (!text) return 'failed';
+  if (typeof navigator !== 'undefined' && typeof navigator.share === 'function') {
+    try {
+      await navigator.share({ text });
+      return 'shared';
+    } catch (error) {
+      if (error && (error as { name?: string }).name === 'AbortError') return 'cancelled';
+      // Share sheet refused (for example no user gesture); fall back to copying.
+    }
+  }
+  return (await copyText(text)) ? 'copied' : 'failed';
+};

package/src/referrals/referralStrings.ts

@@ -0,0 +1,85 @@
+// src/referrals/referralStrings.ts
+// The English text the "Refer a friend" modal shows, and the merge that lets
+// an app translate or reword any of it. Headline and reward text are not here:
+// they come from the portal and from the modal's own options.
+import type { ReferralStrings } from './referralTypes';
+
+export const DEFAULT_REFERRAL_STRINGS: ReferralStrings = {
+  // Joining
+  emailLabel: 'Email',
+  nameLabel: 'Name',
+  joinButton: 'Get my link',
+  joiningButton: 'Please wait...',
+
+  // Email code step
+  codeLabel: 'Code',
+  codeSentNotice: 'We sent a 6-digit code to {email}. Enter it below to connect this device.',
+  verifyButton: 'Verify',
+  verifyingButton: 'Verifying...',
+  resendButton: 'Send a new code',
+  sendingNotice: 'Sending...',
+  codeResentNotice: 'We sent a new code.',
+  differentEmailButton: 'Use a different email',
+  errorCodeLength: 'Enter the 6-digit code from the email.',
+
+  // Joined
+  copyCodeButton: 'Copy code',
+  copyLinkButton: 'Copy link',
+  copiedNotice: 'Copied',
+  copyFailedNotice: 'Could not copy. Select the text to copy it.',
+  shareButton: 'Share',
+  shareFailedNotice: 'Could not share. Copy your code instead.',
+  referralsLabel: 'Referrals',
+  earnedLabel: 'Earned',
+  premiumUntil: 'Free premium until {date}',
+  rewardsHeading: 'Your rewards',
+  redeemButton: 'Redeem',
+  dashboardLink: 'Open my dashboard',
+
+  // Frame and states
+  closeButton: 'Close',
+  loading: 'Loading...',
+  tryAgainButton: 'Try again',
+
+  // Errors, by the server's error code
+  errorProgramDisabled: 'Referrals are not available in this app right now.',
+  errorAffiliateLimitReached: 'The referral program is full right now. Please try again later.',
+  errorInvalidCode: 'That code is wrong or has expired. Check it or send a new code.',
+  errorTooManyCodes: 'Too many codes have been sent. Please wait a while and try again.',
+  errorRateLimited: 'Too many attempts. Please try again later.',
+  errorInvalidEmail: 'Please enter a valid email address.',
+  errorNetwork: 'Could not connect. Check your connection and try again.',
+  errorServer: 'Something went wrong. Please try again.',
+};
+
+/** The error string for a server error code, or the generic one. */
+export const ERROR_STRING_KEYS: Record<string, keyof ReferralStrings> = {
+  PROGRAM_DISABLED: 'errorProgramDisabled',
+  AFFILIATE_LIMIT_REACHED: 'errorAffiliateLimitReached',
+  INVALID_CODE: 'errorInvalidCode',
+  TOO_MANY_CODES: 'errorTooManyCodes',
+  RATE_LIMITED: 'errorRateLimited',
+  INVALID_EMAIL: 'errorInvalidEmail',
+  NETWORK_ERROR: 'errorNetwork',
+};
+
+/**
+ * The app's overrides on top of the English defaults. A missing, blank or
+ * non-string value keeps the default, and an unknown key is ignored.
+ */
+export const resolveReferralStrings = (overrides?: Partial<ReferralStrings>): ReferralStrings => {
+  const resolved: ReferralStrings = { ...DEFAULT_REFERRAL_STRINGS };
+  if (!overrides) return resolved;
+  (Object.keys(DEFAULT_REFERRAL_STRINGS) as (keyof ReferralStrings)[]).forEach((key) => {
+    const value = overrides[key];
+    if (typeof value === 'string' && value.trim()) resolved[key] = value;
+  });
+  return resolved;
+};
+
+/** Fills `{name}` placeholders, leaving any the app did not use alone. */
+export const fillPlaceholders = (text: string, values: Record<string, string>): string =>
+  Object.keys(values).reduce(
+    (out, name) => out.split(`{${name}}`).join(values[name]),
+    text
+  );

package/src/referrals/referralTypes.ts

@@ -0,0 +1,211 @@
+// src/referrals/referralTypes.ts
+// Types for in-app referrals: turning an app's own user into an affiliate,
+// reading their referral stats and presenting the "Refer a friend" modal.
+
+/** What the company counts as a referral (set in the Insert Affiliate portal). */
+export type ReferralTrigger = 'install' | 'event' | 'purchase';
+
+/** The referrer's own affiliate record, as returned by enrol and verify. */
+export 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. */
+export 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. */
+export 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.
+ */
+export 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. */
+export interface ReferralProgramConfig {
+  enabled: boolean;
+  companyName: string;
+  referralTrigger: ReferralTrigger;
+  headline: string;
+  rewardText: string;
+  /** `#RRGGBB`, or empty when the company has not set one. */
+  primaryColor: string;
+}
+
+export 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).
+ */
+export 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 & {});
+
+export 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. */
+export 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.
+ */
+export 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;
+}
+
+export 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;
+}
+
+export interface ReferAFriendHandle {
+  /** Closes the modal. Safe to call more than once. */
+  close(): void;
+}