@atlasauth/js 0.13.0 → 0.15.0

package/dist/referral.d.ts

@@ -4,28 +4,51 @@
  * whoever referred them.
  *
  * What is captured, when the instance has referrals on (`referrals` in
- * `GET /v1/client/environment`):
- *  - the referral code from the page URL — the instance's URL parameters
- *    (default `ref`, `via`, `aff`) on the current page, the page the SDK first
- *    loaded on, and the `redirect_url` / `after_url` query of either;
- *  - with consent, the referral platform's first-party tracking cookie (the
- *    instance's `context_cookie`): JSON or URL-encoded JSON
- *    `{code?, clickId?, anonId?}`, or a plain click id. A URL code wins over the
- *    cookie's code.
+ * `GET /v1/client/environment`): ONE source, in precedence order, never
+ * mixing fields across sources:
+ *  1. the app's own reader (`referralSource`), for any referral program;
+ *  2. a referral program's script on the page, among the instance's
+ *     `browser_sources` (Referally's `aff.getReferral()`, Rewardful, Tolt,
+ *     PromoteKit; see ./referral-detect);
+ *  3. explicit `ref_*` parameters (`ref`, `ref_click_id`, `ref_anon_id`,
+ *     `ref_consent`, `ref_captured_at`) on the page URL;
+ *  4. the referral code from the page URL — the instance's URL parameters
+ *     (default `ref`, `via`, `aff`) on the current page, the page the SDK first
+ *     loaded on, and the `redirect_url` / `after_url` query of either;
+ *  5. the instance's tracking cookie (`context_cookie`): JSON or URL-encoded
+ *     JSON `{code?, clickId?, anonId?, ts?, exp?}`, or a plain click id. An
+ *     expired cookie is ignored;
+ *  6. a referral program's own cookies, among `browser_sources`
+ *     (FirstPromoter, PartnerStack, Dub).
+ * Click and anonymous ids are sent only with consent; without it only the
+ * code goes. The capture says where it came from (`source`) and who decided
+ * consent (`consent_by`), for the delivery log.
  *
- * Consent: when Cookie Munch is on the page (`window.CookieMunch`), the cookie
- * is read only when the instance's consent category is granted (else its
- * fallback category). Without a consent manager the cookie is read only when
- * the app says its own consent manager allowed it (`referralConsent:
- * 'granted'`). Otherwise the URL code alone is sent. The SDK never writes the
+ * Consent: the consent manager on the page decides (the instance's
+ * `consent_provider`: `auto` finds Cookie Munch, OneTrust, Cookiebot, Didomi,
+ * Usercentrics, Osano, CookieYes, Complianz, Klaro, any IAB TCF v2 manager or
+ * Google Consent Mode), for the instance's consent category, else its fallback
+ * category. With no manager on the page, or `consent_provider: 'app'`, the
+ * app's own decision (`referralConsent`) applies. Otherwise only the code is
+ * sent. The SDK never writes a
  * cookie. Nothing captured is trusted: the server re-validates every field.
  *
  * Opt out with `referral: false` (per client, or page-wide with
- * {@link configureReferralCapture}).
+ * {@link configureReferralCapture}). `'auto'` is the default.
+ *
+ * Redirects to a hosted page or `/oauth2/authorize` carry the same referral as
+ * `ref_*` query parameters: {@link signIn} / {@link signUp},
+ * {@link withReferralParams} and {@link referralParams}.
  */
+import { type ReferralSourceReader } from './referral-detect';
+export type { ReferralSourceReader } from './referral-detect';
 /** The instance's public referral settings, camelCased. */
 export interface ReferralConfig {
     enabled: boolean;
+    /** The referral programs' scripts and cookies to read (`browser_sources`), in order. */
+    sources: string[];
+    /** Which consent manager decides: `auto`, a manager id, or `app` (only the app's `referralConsent`). */
+    consentProvider: string;
     /** URL query parameters that carry a code, in priority order. */
     urlParams: string[];
     /** The tracking cookie to read under consent; null = never read a cookie. */
@@ -34,6 +57,10 @@ export interface ReferralConfig {
     consentFallbackCategory: string | null;
     /** `always`: a sign-up carrying a referral code must pass the bot challenge. */
     challengeReferredSignups: 'always' | 'inherit';
+    /** Public "Invited by" lookup URL template with `{code}`, or null. See {@link lookupReferralCode}. */
+    codeLookupUrl: string | null;
+    /** The instance shows an optional "Referral code" field on sign-up. */
+    signupCodeField: boolean;
 }
 /** The `referral` object a sign-in / sign-up request carries (snake_case, as the API takes it). */
 export interface ReferralCapture {
@@ -43,6 +70,10 @@ export interface ReferralCapture {
     consent: 'granted' | 'not_required';
     /** ISO 8601. */
     captured_at: string;
+    /** Where it came from: `custom`, a program id (e.g. `rewardful`), `url` or `cookie`. */
+    source?: string;
+    /** Who decided consent for the ids: `app`, `url`, a consent manager id, or `none`. */
+    consent_by?: string;
 }
 /**
  * The app's own consent decision for the referral cookie, used only when no
@@ -52,10 +83,15 @@ export interface ReferralCapture {
 export type ReferralConsent = 'granted' | 'denied' | boolean | (() => 'granted' | 'denied' | boolean | null | undefined);
 /** The referral options a FAPI client and the prebuilt components take. */
 export interface ReferralCaptureOptions {
-    /** `false` turns referral capture off. */
-    referral?: false | undefined;
+    /** `false` turns referral capture off; `'auto'` (the default) captures when the instance has referrals on. */
+    referral?: false | 'auto' | undefined;
     /** See {@link ReferralConsent}. */
     referralConsent?: ReferralConsent;
+    /**
+     * Your own reader, for a referral program the SDK doesn't know: return
+     * `{code, clickId, anonId}` (any of them) or null. Tried before everything else.
+     */
+    referralSource?: ReferralSourceReader;
 }
 export declare const DISABLED_REFERRAL_CONFIG: Readonly<ReferralConfig>;
 /** A well-formed code / click id / anonymous id, or null. */
@@ -69,21 +105,31 @@ export declare function referralConfigFrom(body: unknown): ReferralConfig;
 export declare function referralCodeFromSearch(search: string | null | undefined, params: readonly string[]): string | null;
 /** The query strings a code may be in: each search, plus its `redirect_url` / `after_url` targets' queries. */
 export declare function referralSearches(searches: readonly string[], base?: string): string[];
-/**
- * Parse a tracking-cookie value: JSON or URL-encoded JSON `{code?, clickId?,
- * anonId?}` (snake_case accepted too); a plain value is a click id.
- */
-export declare function parseReferralCookie(value: string | null | undefined): {
+/** An ISO time from an ISO string or unix seconds / milliseconds, or null. */
+export declare function referralTime(value: unknown): string | null;
+/** One referral source's raw fields. */
+export interface ReferralSourceFields {
     code: string | null;
     clickId: string | null;
     anonId: string | null;
-} | null;
+    /** ISO 8601, when the source says when it captured the referral. */
+    capturedAt?: string;
+}
+/**
+ * Parse a tracking-cookie value: JSON or URL-encoded JSON `{code?, clickId?,
+ * anonId?, ts?, exp?}` (snake_case accepted too); a plain value is a click id.
+ * `ts` (unix seconds or ms) becomes `capturedAt`; a cookie past its `exp` is
+ * ignored.
+ */
+export declare function parseReferralCookie(value: string | null | undefined, now?: number): ReferralSourceFields | null;
 /** A cookie's value from a `document.cookie` string, or null. */
 export declare function readCookieValue(cookies: string | null | undefined, name: string): string | null;
 /**
- * Whether the referral cookie may be read. Cookie Munch on the page decides
- * when present (the instance's category, else its fallback category); else
- * the app's own `referralConsent`.
+ * Whether the referral cookie may be read, with only Cookie Munch to ask (the
+ * shape before consent managers were detected generally). Cookie Munch on the
+ * page decides when present (the instance's category, else its fallback
+ * category); else the app's own `referralConsent`. See {@link detectConsent}
+ * for every manager.
  */
 export declare function referralConsentGranted(config: Pick<ReferralConfig, 'consentCategory' | 'consentFallbackCategory'>, cookieMunch: unknown, appConsent: ReferralConsent | undefined): boolean;
 /** Everything {@link captureReferral} reads from the page. */
@@ -92,15 +138,31 @@ export interface ReferralPage {
     searches: readonly string[];
     /** `document.cookie`. */
     cookies?: string | null;
-    /** `window.CookieMunch`, if any. */
+    /** `window`: its referral scripts and consent manager are read. */
+    win?: unknown;
+    /** `window.CookieMunch`, when no `win` is given (older callers). */
     cookieMunch?: unknown;
+    /** `window.aff`, when no `win` is given (older callers). */
+    aff?: unknown;
     /** Base for resolving a relative redirect_url. */
     base?: string;
     /** ISO time of capture. */
     capturedAt?: string;
 }
-/** Capture the referral for a request, or null when there is nothing to send. Pure. */
-export declare function captureReferral(config: ReferralConfig, page: ReferralPage, appConsent?: ReferralConsent): ReferralCapture | null;
+/** What the page's referral script (`window.aff.getReferral()`) holds, or null. Never throws. */
+export declare function referralFromScript(aff: unknown): ReferralSourceFields | null;
+/** The explicit `ref_*` referral in a query string, or null. `consent` is whether ids may be kept. */
+export declare function explicitReferralFromSearch(search: string | null | undefined): (ReferralSourceFields & {
+    consentGranted: boolean;
+}) | null;
+/**
+ * Capture the referral for a request, or null when there is nothing to send.
+ * Pure. One source wins, in the order described at the top of this module;
+ * fields are never mixed across sources. Ids need consent: the app's
+ * `referralConsent`, `ref_consent=granted` on an explicit URL, or the consent
+ * manager on the page.
+ */
+export declare function captureReferral(config: ReferralConfig, page: ReferralPage, appConsent?: ReferralConsent, customSource?: ReferralSourceReader): ReferralCapture | null;
 /** Whether a FAPI POST path starts or continues a sign-in / sign-up (and so takes `referral`). */
 export declare function acceptsReferral(path: string): boolean;
 /**
@@ -147,3 +209,74 @@ export declare function currentReferral(client: ReferralClient): Promise<Referra
  * sign-ups (even with the captcha otherwise off).
  */
 export declare function referralChallengeRequired(client: ReferralClient): Promise<boolean>;
+/** Options for {@link referralParams}, {@link withReferralParams}, {@link signIn} and {@link signUp}. */
+export interface ReferralRedirectOptions {
+    /** `false`: add nothing. `'auto'` (default): capture as described above. */
+    referral?: false | 'auto';
+    /**
+     * The app's consent for referral tracking (click and anonymous ids). When
+     * omitted, the page-wide `referralConsent` applies, else the consent manager
+     * on the page (`referrals`, else `marketing`), else no consent (code only).
+     */
+    consent?: ReferralConsent;
+    /** Your own reader for a referral program the SDK doesn't know (see {@link ReferralCaptureOptions.referralSource}). */
+    source?: ReferralSourceReader;
+    /**
+     * The instance's config, when the app has it. Defaults: `ref` / `via` /
+     * `aff`, no tracking cookie, every known referral script and cookie, and
+     * any consent manager.
+     */
+    config?: ReferralConfig;
+}
+/**
+ * The referral this page would send, as `ref_*` query parameters (`[]` when
+ * there is none). Synchronous: it uses the instance config when one was
+ * loaded on this page (or passed), else the default URL parameters. Consent
+ * comes from `consent`, else Cookie Munch on the page.
+ */
+export declare function referralParams(options?: ReferralRedirectOptions): Array<[string, string]>;
+/** `url` with the page's referral added as `ref_*` parameters (existing ones are kept, never replaced). */
+export declare function withReferralParams(url: string, options?: ReferralRedirectOptions): string;
+/** Where {@link signIn} / {@link signUp} go. */
+export interface HostedRedirectOptions extends ReferralRedirectOptions {
+    /**
+     * A full URL to go to: a hosted page, `/oauth2/authorize?...`, or your own
+     * login route. Wins over `frontendApi`.
+     */
+    url?: string;
+    /** The instance's Frontend API host or origin (e.g. `accounts.example.com`), for its hosted page. */
+    frontendApi?: string;
+    /** Where the hosted page sends the user afterwards (`redirect_url`). */
+    redirectUrl?: string;
+    /** `false`: return the URL without navigating. Default true. */
+    navigate?: boolean;
+}
+/**
+ * Send the visitor to the hosted sign-in page (or `url`), carrying the
+ * referral they arrived with as `ref_*` parameters (`referral: 'auto'`, the
+ * default). Returns the URL it went to.
+ *
+ * ```ts
+ * signIn({ frontendApi: 'accounts.example.com', redirectUrl: location.href, consent: () => cmp.granted('referrals') });
+ * ```
+ */
+export declare function signIn(options: HostedRedirectOptions): string;
+/** {@link signIn} for the hosted sign-up page. */
+export declare function signUp(options: HostedRedirectOptions): string;
+/** What a code lookup answers. */
+export interface ReferralCodeLookup {
+    valid: boolean;
+    partnerDisplayName?: string;
+    /** Platform-defined; a string or an object with a `description`. */
+    refereeReward?: unknown;
+}
+/**
+ * Ask the instance's public code lookup (`code_lookup_url`) about a code, for
+ * an "X invited you" line. No credentials, `timeoutMs` (default 3000). Null
+ * when there is no lookup, the code is malformed, or the lookup fails: never
+ * block a sign-up on it.
+ */
+export declare function lookupReferralCode(config: Pick<ReferralConfig, 'codeLookupUrl'> | string | null | undefined, code: string, options?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<ReferralCodeLookup | null>;