@buildbase/sdk 0.0.60 → 0.0.62

package/dist/tracking/index.d.ts

@@ -0,0 +1,657 @@
+import React from 'react';
+
+/**
+ * Remembering where a visitor came from, across a whole product.
+ *
+ * A person clicks an ad, lands on `abc.com`, reads for a while, then signs up
+ * on `app.abc.com`. The click id was in the URL of the first page and is long
+ * gone by the second. Unless it was stored somewhere both subdomains can read,
+ * the sign-up looks like it came from nowhere and the ad that paid for it gets
+ * no credit.
+ *
+ * Google solves this by writing `_gcl_aw` on the registrable domain, so every
+ * subdomain shares it. This does the same thing for the ids we carry into our
+ * own events and, later, into a server-side conversion upload.
+ *
+ * ── Why the domain is probed rather than computed ───────────────────────────
+ * "The registrable domain" cannot be derived by counting labels: `abc.co.uk`
+ * has three, `abc.com` has two, and a hard-coded rule gets one of them wrong.
+ * The Public Suffix List is the correct answer and is far too large to ship in
+ * a tracking bundle.
+ *
+ * So we ask the browser, which already knows: try to set a cookie on the
+ * broadest candidate, read it back, and keep the first that sticks. A browser
+ * refuses `domain=.co.uk` because it is a public suffix, so that candidate
+ * fails and `abc.co.uk` wins - the right answer, from the only party that has
+ * the list.
+ */
+/**
+ * The URL parameters worth keeping.
+ *
+ * Click ids first - they are what an ad network matches a conversion against,
+ * and they are the reason this file exists. UTMs are reporting rather than
+ * billing, but they answer "which campaign" and cost nothing to carry.
+ *
+ * Click ids are handled byte-exactly: they are opaque, mixed-case, base64-ish
+ * strings issued by the network, so lowercasing one silently corrupts it and
+ * the network reports zero conversions with nothing in the logs to explain it.
+ */
+declare const ATTRIBUTION_PARAMS: readonly ["gclid", "gbraid", "wbraid", "dclid", "fbclid", "msclkid", "li_fat_id", "twclid", "ttclid", "rdt_cid", "epik", "irclickid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id"];
+type AttributionParam = (typeof ATTRIBUTION_PARAMS)[number];
+type Attribution = Partial<Record<AttributionParam, string>>;
+/**
+ * Capture what this page arrived with, and return everything known so far.
+ *
+ * First touch wins for any given parameter. A visitor who arrives on an ad,
+ * comes back later through a newsletter, and only then signs up should still
+ * credit the ad - overwriting on the second visit would quietly reassign every
+ * conversion to whatever the last touch happened to be. New parameters are
+ * still added, so a later campaign tag enriches rather than replaces.
+ */
+declare function captureAttribution(): Attribution;
+/** What is stored, without touching the URL. */
+declare function getAttribution(): Attribution;
+
+interface PendingCheckout {
+    eventId: string;
+    planVersionId?: string;
+    /**
+     * The workspace buying. The return from Stripe fires `purchase` (or
+     * `checkout_abandoned`) as soon as the tags are ready, which is before the
+     * page has loaded its workspace - so the account the event belongs to has to
+     * travel with the checkout rather than be read on arrival.
+     */
+    workspaceId?: string;
+    /** Set instead of a plan when what was bought is a credit pack. */
+    creditPackageId?: string;
+    billingInterval?: string;
+    currency?: string;
+    /**
+     * The Stripe session this checkout opened. Stripe puts the same id in the
+     * return URL, which is how a return is recognised without the app having
+     * to say so.
+     */
+    sessionId?: string;
+    /** What is charged today, in major units - what every ad platform expects. */
+    value?: number;
+    /** A card-required trial comes back through Stripe too, and is not a sale. */
+    kind?: 'purchase' | 'trial_started';
+    /** Epoch ms, so an entry that outlived its usefulness can be ignored. */
+    startedAt: number;
+}
+
+/**
+ * The provider allowlist, as the SDK sees it.
+ *
+ * ── Why this is a copy ──────────────────────────────────────────────────────
+ * The server has the same table. It is duplicated here rather than fetched
+ * because this is the last check before a string becomes a `<script>` tag in a
+ * customer's application, and a check that arrives over the network from the
+ * thing being checked is not a check. The server is one deploy; a published
+ * SDK is pinned in a customer's lockfile and may be older or newer than it.
+ * Whichever side is stricter should win, and neither should be able to talk
+ * the other into loading something.
+ *
+ * Kept in step by `tag-providers.parity.test.ts`, which fails when this drifts
+ * from the platform's copy in a way that matters.
+ *
+ * Every rule from the server-side file holds here: patterns anchored at both
+ * ends, character classes only, an id is never a URL, and `scriptOrigin` comes
+ * from this table and is never built from anything a tenant typed.
+ */
+type TagConsentCategory = 'analytics' | 'marketing';
+interface TagProviderSpec {
+    /** Display name, used in the console and in generated disclosure text. */
+    title: string;
+    /** The legal entity, for the tenant's own privacy notice. */
+    vendor: string;
+    /** Link for the tenant's disclosure. */
+    privacyUrl: string;
+    /** What the console calls the id field, in the vendor's own words. */
+    idLabel: string;
+    /**
+     * The only shape we accept. Anchored, character classes only.
+     * Stored as a string rather than a RegExp so it crosses the wire to the
+     * console form and the SDK unchanged - one pattern, three validators.
+     */
+    idPattern: string;
+    /** A real-shaped example. Doubles as the console placeholder. */
+    idExample: string;
+    /** Where the script is fetched from. Never built from tenant input. */
+    scriptOrigin: string;
+    defaultConsentCategory: TagConsentCategory;
+    /**
+     * Whether the vendor honours Google Consent Mode v2. Those that do can load
+     * with all four signals denied and start measuring when consent arrives;
+     * those that do not must not be loaded at all beforehand.
+     */
+    supportsConsentMode: boolean;
+    /**
+     * True when the vendor has no fixed conversion event names and instead uses
+     * per-conversion ids the tenant creates in the ad platform. X, LinkedIn and
+     * Google Ads all work this way, so the console must collect an id per
+     * canonical event or their conversions simply never fire.
+     */
+    needsConversionIds: boolean;
+    /**
+     * Whether the vendor's own API accepts more than one id on a page. Mirrors
+     * the platform's copy; see the note there.
+     */
+    multiInstance?: boolean;
+    /**
+     * Closed set of regional hosts, when the vendor has them. The console shows
+     * a picker; anything not in this list is rejected.
+     */
+    hosts?: readonly string[];
+}
+declare const TAG_PROVIDERS: {
+    readonly gtm: {
+        readonly title: "Google Tag Manager";
+        readonly vendor: "Google LLC";
+        readonly privacyUrl: "https://policies.google.com/privacy";
+        readonly idLabel: "Container ID";
+        readonly idPattern: "^GTM-[A-Z0-9]{4,10}$";
+        readonly idExample: "GTM-ABC1234";
+        readonly scriptOrigin: "https://www.googletagmanager.com";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: true;
+        readonly needsConversionIds: false;
+    };
+    readonly ga4: {
+        readonly title: "Google Analytics 4";
+        readonly vendor: "Google LLC";
+        readonly privacyUrl: "https://policies.google.com/privacy";
+        readonly idLabel: "Measurement ID";
+        readonly idPattern: "^G-[A-Z0-9]{8,12}$";
+        readonly idExample: "G-ABCD123456";
+        readonly scriptOrigin: "https://www.googletagmanager.com";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: true;
+        readonly needsConversionIds: false;
+    };
+    readonly google_ads: {
+        readonly title: "Google Ads";
+        readonly vendor: "Google LLC";
+        readonly privacyUrl: "https://policies.google.com/privacy";
+        readonly idLabel: "Conversion ID";
+        readonly idPattern: "^AW-[0-9]{9,12}$";
+        readonly idExample: "AW-123456789";
+        readonly scriptOrigin: "https://www.googletagmanager.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: true;
+        readonly needsConversionIds: true;
+    };
+    readonly meta_pixel: {
+        readonly title: "Meta Pixel";
+        readonly vendor: "Meta Platforms Ireland Limited";
+        readonly privacyUrl: "https://www.facebook.com/privacy/policy";
+        readonly idLabel: "Pixel ID";
+        readonly idPattern: "^[0-9]{15,16}$";
+        readonly idExample: "123456789012345";
+        readonly scriptOrigin: "https://connect.facebook.net";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+        readonly multiInstance: true;
+    };
+    readonly x_pixel: {
+        readonly title: "X (Twitter) Pixel";
+        readonly vendor: "X Corp.";
+        readonly privacyUrl: "https://x.com/en/privacy";
+        readonly idLabel: "Pixel ID";
+        readonly idPattern: "^o[a-z0-9]{4,6}$";
+        readonly idExample: "o1a2b3";
+        readonly scriptOrigin: "https://static.ads-twitter.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: true;
+        readonly multiInstance: true;
+    };
+    readonly linkedin: {
+        readonly title: "LinkedIn Insight Tag";
+        readonly vendor: "LinkedIn Ireland Unlimited Company";
+        readonly privacyUrl: "https://www.linkedin.com/legal/privacy-policy";
+        readonly idLabel: "Partner ID";
+        readonly idPattern: "^[0-9]{6,9}$";
+        readonly idExample: "1234567";
+        readonly scriptOrigin: "https://snap.licdn.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: true;
+        readonly multiInstance: true;
+    };
+    readonly tiktok: {
+        readonly title: "TikTok Pixel";
+        readonly vendor: "TikTok Information Technologies UK Limited";
+        readonly privacyUrl: "https://www.tiktok.com/legal/privacy-policy";
+        readonly idLabel: "Pixel ID";
+        readonly idPattern: "^[A-Z0-9]{20}$";
+        readonly idExample: "C4A1B2C3D4E5F6G7H8I9";
+        readonly scriptOrigin: "https://analytics.tiktok.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+        readonly multiInstance: true;
+    };
+    readonly reddit: {
+        readonly title: "Reddit Pixel";
+        readonly vendor: "Reddit, Inc.";
+        readonly privacyUrl: "https://www.reddit.com/policies/privacy-policy";
+        readonly idLabel: "Advertiser ID";
+        readonly idPattern: "^t2_[a-z0-9]{4,12}$";
+        readonly idExample: "t2_abc123";
+        readonly scriptOrigin: "https://www.redditstatic.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+        readonly multiInstance: true;
+    };
+    readonly bing_uet: {
+        readonly title: "Microsoft Advertising (UET)";
+        readonly vendor: "Microsoft Corporation";
+        readonly privacyUrl: "https://privacy.microsoft.com/en-us/privacystatement";
+        readonly idLabel: "Tag ID";
+        readonly idPattern: "^[0-9]{7,9}$";
+        readonly idExample: "12345678";
+        readonly scriptOrigin: "https://bat.bing.com";
+        readonly defaultConsentCategory: "marketing";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+        readonly multiInstance: true;
+    };
+    readonly clarity: {
+        readonly title: "Microsoft Clarity";
+        readonly vendor: "Microsoft Corporation";
+        readonly privacyUrl: "https://privacy.microsoft.com/en-us/privacystatement";
+        readonly idLabel: "Project ID";
+        readonly idPattern: "^[a-z0-9]{10}$";
+        readonly idExample: "ab12cd34ef";
+        readonly scriptOrigin: "https://www.clarity.ms";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+    };
+    readonly hotjar: {
+        readonly title: "Hotjar";
+        readonly vendor: "Hotjar Limited";
+        readonly privacyUrl: "https://www.hotjar.com/legal/policies/privacy/";
+        readonly idLabel: "Site ID";
+        readonly idPattern: "^[0-9]{6,9}$";
+        readonly idExample: "1234567";
+        readonly scriptOrigin: "https://static.hotjar.com";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+    };
+    readonly posthog: {
+        readonly title: "PostHog";
+        readonly vendor: "PostHog, Inc.";
+        readonly privacyUrl: "https://posthog.com/privacy";
+        readonly idLabel: "Project API key";
+        readonly idPattern: "^phc_[A-Za-z0-9]{32,48}$";
+        readonly idExample: "phc_abcdefghijklmnopqrstuvwxyz012345";
+        readonly scriptOrigin: "https://us-assets.i.posthog.com";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+        readonly hosts: readonly ["us.i.posthog.com", "eu.i.posthog.com"];
+    };
+    readonly plausible: {
+        readonly title: "Plausible Analytics";
+        readonly vendor: "Plausible Insights OÜ";
+        readonly privacyUrl: "https://plausible.io/privacy";
+        readonly idLabel: "Domain";
+        readonly idPattern: "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$";
+        readonly idExample: "example.com";
+        readonly scriptOrigin: "https://plausible.io";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+    };
+    readonly ahrefs: {
+        readonly title: "Ahrefs Analytics";
+        readonly vendor: "Ahrefs Pte. Ltd.";
+        readonly privacyUrl: "https://ahrefs.com/privacy";
+        readonly idLabel: "Analytics key";
+        readonly idPattern: "^[A-Za-z0-9+/=]{20,64}$";
+        readonly idExample: "AbCdEfGhIjKlMnOpQrStUv==";
+        readonly scriptOrigin: "https://analytics.ahrefs.com";
+        readonly defaultConsentCategory: "analytics";
+        readonly supportsConsentMode: false;
+        readonly needsConversionIds: false;
+    };
+};
+type TagProviderId = keyof typeof TAG_PROVIDERS;
+declare const TAG_PROVIDER_IDS: TagProviderId[];
+declare function isTagProviderId(value: unknown): value is TagProviderId;
+/**
+ * Whether `id` is a valid identifier for `provider`.
+ *
+ * Called on write in the console, again on write at the API, and a third time
+ * by the SDK on read. The triple-check is deliberate: the SDK validates
+ * because a document could have been written by a migration or edited directly
+ * in Mongo, and the SDK is the one that turns a string into a script tag.
+ */
+declare function isValidProviderId(provider: TagProviderId, id: unknown): boolean;
+/**
+ * Every origin a tenant's app may need in its own Content-Security-Policy.
+ *
+ * Published in the docs so a customer running a CSP knows what to allow. We do
+ * not set their policy for them - it is their app - but they should not have
+ * to discover this list one console error at a time.
+ */
+declare const TAG_SCRIPT_ORIGINS: readonly string[];
+
+/** One script, as the platform's `/v1/public/:orgId/tracking` returns it. */
+interface PublicTrackingScript {
+    key: string;
+    provider: string;
+    providerId?: string;
+    host?: string;
+    src?: string;
+    dataAttributes?: Record<string, string>;
+    consentCategory: TagConsentCategory;
+    /** Keyed by event name - ours or the customer's own. */
+    conversionIds?: Record<string, string>;
+}
+/**
+ * One row a consent banner can render.
+ *
+ * Derived from what is actually installed, never from the org's whole library:
+ * a banner that names a vendor the page did not load is asking for consent
+ * under false pretences.
+ */
+interface TrackingConsentEntry {
+    key: string;
+    name: string;
+    vendor: string;
+    category: TagConsentCategory;
+    privacyUrl?: string;
+}
+interface PublicTrackingConfig {
+    enabled: boolean;
+    scripts: PublicTrackingScript[];
+    consent: {
+        manifest: TrackingConsentEntry[];
+    };
+    dataLayerName?: string;
+}
+/** What the visitor has agreed to. `null` until they have been asked. */
+interface ConsentState {
+    analytics: boolean;
+    marketing: boolean;
+}
+/**
+ * The events the SDK fires on the app's behalf.
+ *
+ * Deliberately only the moments BuildBase itself observes. A customer's own
+ * events go through `track()` and reach the data layer, but are never mapped
+ * onto a vendor's standard event - guessing that someone's `upgraded_seat` is
+ * Meta's `Purchase` is how a conversion report becomes fiction.
+ */
+type CanonicalEventName = 'sign_up' | 'login' | 'trial_started' | 'checkout_started' | 'purchase' | 'subscription_created' | 'subscription_upgraded' | 'lead' | 'workspace_created';
+/** Who fires a given event: the SDK, or the app. */
+type EventOwnership = 'auto' | 'manual';
+/** Per-call options for `track`. */
+interface TrackOptions {
+    /**
+     * Use this id instead of generating one.
+     *
+     * The id is what joins a browser event to a later server-side send of the
+     * same occurrence, so a caller that has already written it somewhere the
+     * server will read it back - Stripe checkout metadata is the case this
+     * exists for - has to be able to fire the event with that same id.
+     */
+    eventId?: string;
+}
+interface TrackingEvent {
+    name: CanonicalEventName | string;
+    params: Record<string, unknown>;
+    /** Shared with any later server-side send, so the two can be deduplicated. */
+    eventId: string;
+    handledBy: EventOwnership;
+}
+interface TrackingEventsConfig {
+    /** Default `auto`: the SDK fires to every installed script. */
+    mode?: EventOwnership;
+    /** Per-event override, for the few a customer wants to own. */
+    overrides?: Partial<Record<CanonicalEventName, EventOwnership>>;
+}
+interface TrackingOptions {
+    /** Set false to fetch nothing and render nothing. */
+    enabled?: boolean;
+    /**
+     * `auto` (default) sets Consent Mode v2 to denied and waits for
+     * `setConsent`. `granted` is the app asserting it has a lawful basis
+     * already - documented as their assertion, not ours. `denied` keeps
+     * everything off.
+     */
+    consent?: 'auto' | 'granted' | 'denied';
+    /**
+     * Fire a `page_view` on SPA navigation. Turn it off when the app's GTM
+     * container already does it - double-counted pageviews is the single most
+     * likely support ticket this feature generates.
+     */
+    autoPageview?: boolean;
+    events?: TrackingEventsConfig;
+    /**
+     * Called for every canonical event. Returning `true` tells the SDK the app
+     * handled this occurrence and suppresses its own fire.
+     */
+    onEvent?: (event: TrackingEvent) => boolean | void;
+    /**
+     * Fields added to every event, including the ones the SDK fires itself.
+     *
+     * The events BuildBase owns - a signup, a checkout, a purchase - carry what
+     * BuildBase knows, which is never the thing a particular business builds
+     * its funnel on. A plan intent chosen before signup, an experiment variant,
+     * an industry: without somewhere to put them, the only way to get one onto
+     * a signup was to take the event over as `manual` and hand-write the
+     * fan-out to every vendor, which is a bad trade for one field.
+     *
+     * Use `setProperties` for anything not known at mount.
+     */
+    properties?: Record<string, unknown>;
+    /**
+     * The last word on what an event carries, called just before it is sent.
+     *
+     * Returns fields to merge in - which may overwrite anything already there,
+     * including ours. Use it for values that depend on the event: a plan on
+     * `checkout_started`, a source on `sign_up`. To suppress an event entirely,
+     * return `true` from `onEvent` instead and send nothing.
+     *
+     * It cannot rename an event: the name is what every vendor mapping is keyed
+     * on, and renaming one here would silently unmap it.
+     */
+    enrich?: (event: {
+        name: string;
+        params: Record<string, unknown>;
+    }) => Record<string, unknown> | void;
+    /** Log what was installed, skipped and fired. */
+    debug?: boolean;
+}
+
+interface TrackingContextValue {
+    /** What is installed, for a banner to render. Empty until config loads. */
+    consent: {
+        manifest: TrackingConsentEntry[];
+        state: ConsentState | null;
+        set: (state: ConsentState) => void;
+    };
+    /** Fire an event. Canonical names map to every vendor; others go to the data layer. */
+    track: (name: string, params?: Record<string, unknown>, options?: TrackOptions) => void;
+    /**
+     * Attach a user id to every vendor that supports one, and optionally the
+     * traits a funnel segments on - a plan, a company size, an experiment arm.
+     * Never an email or a name: every ad network forbids it in these fields.
+     */
+    setUser: (userId: string, traits?: Record<string, unknown>) => void;
+    /**
+     * Add fields to every event from here on. For anything not known when the
+     * provider mounted: an experiment assignment, a tenant tier fetched after
+     * login. Merged, so calling it twice keeps both, and setting a key to
+     * `undefined` takes it back - which is what to do on sign-out, so the next
+     * person's events do not carry the last person's.
+     */
+    setProperties: (properties: Record<string, unknown>) => void;
+    /**
+     * What `properties` and `setProperties` currently amount to.
+     *
+     * Read by the checkout hooks, which stamp them onto the Stripe session so
+     * that a conversion sent later from our servers carries the same fields the
+     * browser would have sent. Without it a custom field lands on whichever of
+     * the two hits the vendor happens to keep.
+     */
+    getProperties: () => Record<string, unknown>;
+    /**
+     * Report a checkout that has come back from Stripe, correcting its value
+     * against what was actually charged. Used by the return leg and by
+     * `useCheckoutCompleted`; both spend the same parked checkout, so whichever
+     * runs first is the one that reports.
+     */
+    completeCheckout: (pending: PendingCheckout, extraParams?: Record<string, unknown>) => Promise<void>;
+    /** Which providers are loaded, keyed by script key. */
+    installed: Record<string, string>;
+    /**
+     * True once the org's configuration has been fetched and the scripts it
+     * allows are installed. Anything fired before this reaches `onEvent` and no
+     * vendor, so a caller that owns a once-per-session event waits for it.
+     */
+    ready: boolean;
+    /**
+     * Where this visitor came from - click ids and campaign params, captured on
+     * the first page they landed on anywhere in the product and shared across
+     * subdomains. Rides on every event so a sign-up on `app.abc.com` can still
+     * be credited to the ad that was clicked on `abc.com`.
+     */
+    attribution: Attribution;
+}
+declare function useTracking(): TrackingContextValue;
+interface BuildBaseTrackingProps extends TrackingOptions {
+    /** The BuildBase API base URL. */
+    serverUrl: string;
+    /** The organization id. */
+    orgId: string;
+    /**
+     * The auth client id for *this* app. Required: a client is what an app is,
+     * and it is what decides which scripts load here rather than on the org's
+     * other properties.
+     */
+    clientId: string;
+    /**
+     * A GA4 identity handed over from another domain, so this page measures as
+     * the same user rather than a new one.
+     *
+     * For the hosted sign-in pages, which are on a different registrable domain
+     * from the app the visitor came from. GA4's `_ga` cookie cannot cross that
+     * boundary, so without this the sign-in step lands under somebody who never
+     * visited the app and the funnel cannot be built at all.
+     *
+     * `signIn()` sends it with the auth request; the pages read it back and pass
+     * it here. Ordinary apps never set this.
+     */
+    identity?: {
+        gaClientId?: string;
+        gaSessionId?: string;
+    };
+    children?: React.ReactNode;
+}
+/**
+ * Installs the org's configured tracking scripts into this app.
+ *
+ * Mountable on its own (a marketing site that wants tags and nothing else) and
+ * mounted internally by `SaaSOSProvider`, which additionally knows about
+ * signup, login and checkout and fires those events for you.
+ */
+declare const BuildBaseTracking: React.FC<BuildBaseTrackingProps>;
+/**
+ * Fire `purchase` for a checkout the customer has just come back from paying.
+ *
+ * Call it on the page Stripe returns to, and nowhere else - the SDK has no
+ * way to recognise that page, because its URL is the app's own `successUrl`.
+ *
+ * It is a no-op when no checkout is in flight, so it is safe on a page a
+ * customer might also reach directly, and it consumes what it reads, so a
+ * refresh cannot count the sale twice. The event carries the same id that was
+ * written onto the Stripe subscription as `bb_event_id`.
+ *
+ * @example
+ * ```tsx
+ * export default function BillingSuccess() {
+ *   useCheckoutCompleted({ value: 79, currency: 'USD' });
+ *   return <p>Thanks - your plan is active.</p>;
+ * }
+ * ```
+ */
+declare function useCheckoutCompleted(params?: Record<string, unknown>): void;
+
+/**
+ * What each vendor calls the events we fire.
+ *
+ * `null` means the vendor has no counterpart and we deliberately send nothing.
+ * No ad network treats a returning login as a conversion, and reporting one
+ * inflates every campaign that ever touched an existing customer. An upgrade
+ * is not mapped to `Purchase` for the same reason - it double-counts against
+ * the original subscription.
+ *
+ * X, LinkedIn and Google Ads take no event name at all: they take a
+ * per-conversion id the tenant created in the ad platform, which is why
+ * `conversionIds` rides along on the script config.
+ */
+declare const EVENT_MAPPINGS: Record<CanonicalEventName, {
+    ga4: string | null;
+    meta: string | null;
+    tiktok: string | null;
+    reddit: string | null;
+}>;
+declare function isCanonicalEvent(name: string): name is CanonicalEventName;
+
+/**
+ * The steps between a visit and a paying, retained customer that happen
+ * inside BuildBase's own UI.
+ *
+ * `sign_up` and `purchase` say that someone arrived and that someone paid.
+ * They cannot say where the rest went: who opened the plan picker and closed
+ * it, who picked a plan and backed out of Stripe, who kept hitting a feature
+ * their plan does not include. Those moments happen in the settings modal, the
+ * plan picker and the gates - components the SDK renders - so the SDK is the
+ * only thing that can report them, and it does it for every app without a line
+ * of code on their side.
+ *
+ * Product events, never conversions. None of them map to a Meta, TikTok or
+ * Reddit event, so no ad network sees them; they reach the data layer and the
+ * vendors that take arbitrary names - GA4, PostHog, Clarity, Hotjar, Plausible.
+ * Google Ads, X and LinkedIn hear one only if the tenant attaches a conversion
+ * id to that exact name in the console.
+ *
+ * The names are frozen once released. They become column values in somebody's
+ * warehouse and step names in somebody's saved funnel, and a rename breaks both
+ * without an error.
+ */
+declare const FUNNEL_EVENTS: {
+    readonly sign_in_started: "The sign-in / sign-up button was pressed.";
+    readonly pricing_viewed: "A <PricingPage> finished loading its plans.";
+    readonly pricing_plan_selected: "A plan was chosen on a <PricingPage>.";
+    readonly workspace_switcher_opened: "The workspace switcher was opened.";
+    readonly workspace_settings_opened: "The workspace settings modal was opened.";
+    readonly workspace_settings_section_viewed: "A different section of the settings modal was opened.";
+    readonly plan_picker_opened: "The plan picker was shown.";
+    readonly billing_interval_changed: "Monthly / quarterly / yearly was switched in the plan picker.";
+    readonly plan_selected: "A plan was chosen in the plan picker.";
+    readonly plan_picker_dismissed: "The plan picker was closed without choosing a plan.";
+    readonly checkout_abandoned: "The customer came back from Stripe without paying.";
+    readonly billing_portal_opened: "Stripe’s billing portal was opened.";
+    readonly subscription_cancel_started: "The cancel-subscription confirmation was opened.";
+    readonly subscription_cancelled: "A subscription was cancelled.";
+    readonly subscription_resumed: "A cancelled subscription was resumed.";
+    readonly feature_gate_shown: "A feature gate rendered its \"not on your plan\" side.";
+    readonly quota_limit_reached: "A quota gate rendered because a quota is used up.";
+    readonly quota_threshold_reached: "A usage-threshold gate rendered.";
+    readonly plan_gate_shown: "A plan gate rendered its \"needs another plan\" side.";
+    readonly subscription_notice_shown: "A billing notice (trial ending, payment failed…) was shown.";
+    readonly sdk_error: "An SDK operation failed (component, action and code only).";
+};
+type FunnelEventName = keyof typeof FUNNEL_EVENTS;
+
+export { ATTRIBUTION_PARAMS, BuildBaseTracking, EVENT_MAPPINGS, FUNNEL_EVENTS, TAG_PROVIDERS, TAG_PROVIDER_IDS, TAG_SCRIPT_ORIGINS, captureAttribution, getAttribution, isCanonicalEvent, isTagProviderId, isValidProviderId, useCheckoutCompleted, useTracking };
+export type { Attribution, AttributionParam, BuildBaseTrackingProps, CanonicalEventName, ConsentState, EventOwnership, FunnelEventName, PublicTrackingConfig, PublicTrackingScript, TagConsentCategory, TagProviderId, TagProviderSpec, TrackOptions, TrackingConsentEntry, TrackingContextValue, TrackingEvent, TrackingEventsConfig, TrackingOptions };