@leapio/web 0.0.0-stage → 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,267 @@
+//#region src/sdk-config.d.ts
+type EventPayload = {
+  name: string;
+  channel?: string | null;
+  message?: string | null;
+  notify?: boolean | null;
+  user_id?: string | null;
+  anonymous_id?: string | null;
+  metadata?: any | null;
+  hostname?: string | null;
+  url?: string | null;
+  referrer?: string | null;
+  language?: string | null;
+  screen?: string | null;
+  value?: number | null;
+  currency?: string | null;
+  privacy_categories?: string;
+  privacy_signals?: string;
+  consent_source?: string | null;
+};
+/**
+ * Mirrors the org-level `consentBehavior` setting. `notRequired` (default)
+ * preserves the SDK's existing send-immediately behavior byte-for-byte.
+ * `implied` sends until analytics is explicitly denied. `express` queues
+ * events until analytics is explicitly granted (denial drops the queue).
+ */
+type ConsentBehavior = "notRequired" | "implied" | "express";
+/**
+ * Per-type autocapture toggles. Each capture type can be enabled/disabled
+ * independently. Unset keys fall back to {@link AUTOCAPTURE_DEFAULTS}.
+ *
+ * - `outboundLinks` — clicks on `<a>` whose host differs from `location.host`
+ * - `fileDownloads` — clicks on `<a>` whose href ends in a download extension
+ *   (or that carry a `download` attribute); metadata only, no PII
+ * - `formSubmissions` — `submit` events (metadata only, never field values)
+ * - `clicks` — clicks on interactive elements (noisy; off by default)
+ * - `inputChanges` — `change` events on inputs (metadata only; off by default)
+ * - `mediaPlayback` — native `<video>`/`<audio>` engagement (play/pause/progress/
+ *   complete); metadata only, never a recording. Audience-dependent; off by
+ *   default.
+ */
+type AutocaptureConfig = {
+  outboundLinks?: boolean;
+  fileDownloads?: boolean;
+  formSubmissions?: boolean;
+  clicks?: boolean;
+  inputChanges?: boolean;
+  mediaPlayback?: boolean;
+};
+/**
+ * Snippet-shaped autocapture config used by the CDN wrapper (`leapio-js`). It
+ * separates the **master** enablement (the `data-autocapture` attribute) from
+ * per-**type** overrides (`data-autocapture-<type>`), so a bare per-type
+ * attribute can override that type *without* force-enabling autocapture.
+ *
+ * - `master` — `true`/`false` when `data-autocapture` is explicitly set;
+ *   `undefined` when only per-type attributes are present (enablement then
+ *   defers to the server / dashboard).
+ * - `types` — the per-type overrides parsed from `data-autocapture-<type>`.
+ *
+ * The plain {@link AutocaptureConfig} object form (used by direct `init()`
+ * callers) keeps its historical meaning: passing an object enables autocapture.
+ * Only this `{ master, types }` shape decouples the two.
+ */
+type AutocaptureSnippetConfig = {
+  master?: boolean;
+  types?: AutocaptureConfig;
+};
+interface SdkConfig {
+  publicKey: string;
+  pageviewsChannel?: string;
+  cookiesDisabled?: boolean;
+  enableAutoPageviews?: boolean;
+  /**
+   * Escape hatch: fall back to the legacy MutationObserver-based SPA route
+   * detection instead of the default History-API method (patching
+   * `pushState`/`replaceState` + `popstate`/`hashchange`). Default `false`.
+   * Only relevant when `enableAutoPageviews` is true. The History-API method is
+   * more accurate (it does not fire spurious pageviews on unrelated DOM churn
+   * and dedupes URL-normalizing `replaceState` calls), so this exists purely as
+   * a safety valve for sites that depend on the old heuristic.
+   */
+  legacySpaDetection?: boolean;
+  /**
+   * Legacy single-toggle "capture every click" flag. Retained for back-compat:
+   * it maps to `autocapture: { clicks: true }`. Prefer `autocapture`.
+   */
+  enableAutoClicks?: boolean;
+  /**
+   * Delegated autocapture.
+   *
+   * - `true` / `false` — master toggle.
+   * - {@link AutocaptureConfig} object — enables autocapture and applies the
+   *   per-type overrides (direct-`init()` convenience; an object means enable).
+   * - {@link AutocaptureSnippetConfig} `{ master, types }` — the snippet form,
+   *   which separates master enablement from per-type overrides so a bare
+   *   per-type attribute does NOT by itself enable autocapture.
+   *
+   * Per-type resolution uses {@link AUTOCAPTURE_DEFAULTS}. When unset (and
+   * `enableAutoClicks` is false), no autocapture listeners are attached and
+   * default behavior is byte-identical.
+   */
+  autocapture?: boolean | AutocaptureConfig | AutocaptureSnippetConfig;
+  externalApiUrl?: string;
+  identifyApiUrl?: string;
+  /** Override for the `POST /consent` endpoint (pattern of `identifyApiUrl`). */
+  consentApiUrl?: string;
+  /** Override for the `POST /group` endpoint (pattern of `identifyApiUrl`). */
+  groupApiUrl?: string;
+  /** Gating behavior for consent. Default `notRequired` (no behavior change). */
+  consentBehavior?: ConsentBehavior;
+  /**
+   * Names of consent sources to register (e.g. `['onetrust', 'gcm']`).
+   * Plumbed through from the CDN wrapper's `data-consent-source` attribute; the
+   * plugin registry (consent-sources/) consumes these ids.
+   */
+  consentSources?: string[];
+  /**
+   * Defense-in-depth URL privacy. When `true`, the SDK removes query params not
+   * in {@link queryParamAllowlist} (and always the hash) from BOTH the event url
+   * and the referrer before sending, so PII/secrets in the query string never
+   * leave the browser. The referrer matters most for SPAs, where it becomes the
+   * previous in-app URL on each route change. The server applies the
+   * authoritative per-project rule regardless; this only keeps the wire clean.
+   * Default `false` (url + referrer sent unchanged). UTM attribution is
+   * unaffected (captured from `window.location`, not the payload url).
+   */
+  stripQueryParams?: boolean;
+  /**
+   * Query-param names kept on the url when {@link stripQueryParams} is on
+   * (case-insensitive). Defaults to UTM params + common ad click-ids + `ref`.
+   */
+  queryParamAllowlist?: string[];
+  stickyCampaigns?: boolean;
+  stickyCampaignsExpirationInSeconds?: number;
+  cookieDomain?: string;
+  cookieExpirationInSeconds?: number;
+  enableBrowserDNT?: boolean;
+  /**
+   * Add the anonymous id as `client_reference_id` to Stripe Payment Link
+   * (`buy.stripe.com`) hrefs when they are pressed, so the payment is
+   * attributed without hand-built URLs. An existing `client_reference_id` is
+   * never overwritten, and nothing is tagged while consent withholds sending.
+   * Default `true`.
+   */
+  tagPaymentLinks?: boolean;
+  /**
+   * Engaged-time tracking: `"leave"` sends a "Page Leave" event when a page is
+   * hidden or left; `"heartbeat"` also sends a "Page Heartbeat" each visible
+   * minute. Both carry `engaged_seconds` and count as events. Overrides the
+   * dashboard setting; default is the dashboard's, which defaults to `"off"`.
+   */
+  engagement?: "off" | "leave" | "heartbeat";
+  /**
+   * Track browsers driven by WebDriver (`navigator.webdriver`), e.g. to test
+   * the integration end to end with Playwright or Selenium. Default `false`.
+   */
+  trackAutomatedBrowsers?: boolean;
+  onLoad?: () => void | Promise<void>;
+  eventMapper?: (payload: EventPayload) => EventPayload | Promise<EventPayload>;
+}
+//#endregion
+//#region src/super-properties.d.ts
+type Property = string | number | boolean;
+type Properties = Record<string, Property>;
+//#endregion
+//#region src/consent.d.ts
+type ConsentCategory = "analytics" | "functional" | "marketing";
+type PrivacySignals = {
+  doNotSellShare?: boolean;
+  gpc?: boolean;
+  gppDetected?: boolean;
+  /** Raw GPP string when present; detection + raw value only in V1. */
+  gppString?: string;
+};
+/**
+ * A persisted consent snapshot. `categories` is a partial map: an absent key
+ * means "this source never spoke about that category" (falls through to the
+ * org's consentBehavior server-side), distinct from an explicit `false` (denied).
+ */
+type ConsentSnapshot = {
+  categories: Partial<Record<ConsentCategory, boolean>>;
+  signals: PrivacySignals;
+  source: string;
+  updatedAt: string;
+  /** Optional vendor payload / consent version / region for `/consent`. */
+  sourceMetadata?: Record<string, unknown>;
+};
+//#endregion
+//#region src/api.d.ts
+type IdentifyOptions = {
+  identityVerification?: {
+    token: string;
+  };
+};
+type IdentifyResult = {
+  ok: boolean;
+  status?: number;
+  reason?: string;
+};
+type ConsentResult = {
+  ok: boolean;
+  status?: number;
+  reason?: string;
+};
+//#endregion
+//#region src/url-privacy.d.ts
+export declare const DEFAULT_QUERY_PARAM_ALLOWLIST: string[];
+//#endregion
+//#region src/index.d.ts
+/** Public argument shape for `setConsent()` — all fields optional (partial). */
+export type SetConsentInput = {
+  analytics?: boolean;
+  functional?: boolean;
+  marketing?: boolean;
+  doNotSellShare?: boolean;
+};
+/** Options for `revenue()`. `currency` is ISO-4217; the rest become metadata. */
+export type RevenueOptions = {
+  currency?: string;
+  /** Override the reserved revenue event name (defaults to "Payment"). */
+  event?: string;
+  channel?: string | null;
+  userId?: string;
+  [key: string]: any;
+};
+export declare const leapio: {
+  init: (config: SdkConfig) => Promise<void>;
+  track: (data: {
+    event: string;
+    channel?: string | null;
+    userId?: string;
+    message?: string;
+    notify?: boolean;
+    metadata?: Record<string, any>;
+    value?: number;
+    currency?: string;
+    /** Associate this event with a group/account (Segment `$groups` style).
+     *  With groupType "company" (the default when groupId is set) the platform
+     *  resolves and stamps the company on the event. */
+    groupId?: string;
+    groupType?: string;
+  }) => Promise<void>;
+  revenue: (amount: number, options?: RevenueOptions) => Promise<void>;
+  pageview: (data?: {
+    userId?: string;
+    metadata?: Record<string, any>;
+  }) => Promise<void>;
+  register: (properties: Properties) => void | true;
+  unregister: (property: string) => void;
+  reset: () => void;
+  identify: (newUserId: string, traits?: Record<string, any>, opts?: IdentifyOptions) => Promise<IdentifyResult>;
+  group: (groupId: string, traits?: Record<string, any>, opts?: IdentifyOptions & {
+    type?: string;
+  }) => Promise<IdentifyResult>;
+  setConsent: (input: SetConsentInput, opts?: {
+    identityVerification?: {
+      token: string;
+    };
+  }) => Promise<ConsentResult>;
+  getConsent: () => ConsentSnapshot | null;
+  applyConsentSnapshot: (snapshot: ConsentSnapshot) => Promise<boolean>;
+  getProperties: () => Record<string, Property>;
+  getAnonymousId: () => string | null;
+};
+//#endregion
+export { type AutocaptureConfig, type AutocaptureSnippetConfig, type ConsentBehavior, type EventPayload, type SdkConfig, leapio as default };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+//#region src/sdk-config.d.ts
+type EventPayload = {
+  name: string;
+  channel?: string | null;
+  message?: string | null;
+  notify?: boolean | null;
+  user_id?: string | null;
+  anonymous_id?: string | null;
+  metadata?: any | null;
+  hostname?: string | null;
+  url?: string | null;
+  referrer?: string | null;
+  language?: string | null;
+  screen?: string | null;
+  value?: number | null;
+  currency?: string | null;
+  privacy_categories?: string;
+  privacy_signals?: string;
+  consent_source?: string | null;
+};
+/**
+ * Mirrors the org-level `consentBehavior` setting. `notRequired` (default)
+ * preserves the SDK's existing send-immediately behavior byte-for-byte.
+ * `implied` sends until analytics is explicitly denied. `express` queues
+ * events until analytics is explicitly granted (denial drops the queue).
+ */
+type ConsentBehavior = "notRequired" | "implied" | "express";
+/**
+ * Per-type autocapture toggles. Each capture type can be enabled/disabled
+ * independently. Unset keys fall back to {@link AUTOCAPTURE_DEFAULTS}.
+ *
+ * - `outboundLinks` — clicks on `<a>` whose host differs from `location.host`
+ * - `fileDownloads` — clicks on `<a>` whose href ends in a download extension
+ *   (or that carry a `download` attribute); metadata only, no PII
+ * - `formSubmissions` — `submit` events (metadata only, never field values)
+ * - `clicks` — clicks on interactive elements (noisy; off by default)
+ * - `inputChanges` — `change` events on inputs (metadata only; off by default)
+ * - `mediaPlayback` — native `<video>`/`<audio>` engagement (play/pause/progress/
+ *   complete); metadata only, never a recording. Audience-dependent; off by
+ *   default.
+ */
+type AutocaptureConfig = {
+  outboundLinks?: boolean;
+  fileDownloads?: boolean;
+  formSubmissions?: boolean;
+  clicks?: boolean;
+  inputChanges?: boolean;
+  mediaPlayback?: boolean;
+};
+/**
+ * Snippet-shaped autocapture config used by the CDN wrapper (`leapio-js`). It
+ * separates the **master** enablement (the `data-autocapture` attribute) from
+ * per-**type** overrides (`data-autocapture-<type>`), so a bare per-type
+ * attribute can override that type *without* force-enabling autocapture.
+ *
+ * - `master` — `true`/`false` when `data-autocapture` is explicitly set;
+ *   `undefined` when only per-type attributes are present (enablement then
+ *   defers to the server / dashboard).
+ * - `types` — the per-type overrides parsed from `data-autocapture-<type>`.
+ *
+ * The plain {@link AutocaptureConfig} object form (used by direct `init()`
+ * callers) keeps its historical meaning: passing an object enables autocapture.
+ * Only this `{ master, types }` shape decouples the two.
+ */
+type AutocaptureSnippetConfig = {
+  master?: boolean;
+  types?: AutocaptureConfig;
+};
+interface SdkConfig {
+  publicKey: string;
+  pageviewsChannel?: string;
+  cookiesDisabled?: boolean;
+  enableAutoPageviews?: boolean;
+  /**
+   * Escape hatch: fall back to the legacy MutationObserver-based SPA route
+   * detection instead of the default History-API method (patching
+   * `pushState`/`replaceState` + `popstate`/`hashchange`). Default `false`.
+   * Only relevant when `enableAutoPageviews` is true. The History-API method is
+   * more accurate (it does not fire spurious pageviews on unrelated DOM churn
+   * and dedupes URL-normalizing `replaceState` calls), so this exists purely as
+   * a safety valve for sites that depend on the old heuristic.
+   */
+  legacySpaDetection?: boolean;
+  /**
+   * Legacy single-toggle "capture every click" flag. Retained for back-compat:
+   * it maps to `autocapture: { clicks: true }`. Prefer `autocapture`.
+   */
+  enableAutoClicks?: boolean;
+  /**
+   * Delegated autocapture.
+   *
+   * - `true` / `false` — master toggle.
+   * - {@link AutocaptureConfig} object — enables autocapture and applies the
+   *   per-type overrides (direct-`init()` convenience; an object means enable).
+   * - {@link AutocaptureSnippetConfig} `{ master, types }` — the snippet form,
+   *   which separates master enablement from per-type overrides so a bare
+   *   per-type attribute does NOT by itself enable autocapture.
+   *
+   * Per-type resolution uses {@link AUTOCAPTURE_DEFAULTS}. When unset (and
+   * `enableAutoClicks` is false), no autocapture listeners are attached and
+   * default behavior is byte-identical.
+   */
+  autocapture?: boolean | AutocaptureConfig | AutocaptureSnippetConfig;
+  externalApiUrl?: string;
+  identifyApiUrl?: string;
+  /** Override for the `POST /consent` endpoint (pattern of `identifyApiUrl`). */
+  consentApiUrl?: string;
+  /** Override for the `POST /group` endpoint (pattern of `identifyApiUrl`). */
+  groupApiUrl?: string;
+  /** Gating behavior for consent. Default `notRequired` (no behavior change). */
+  consentBehavior?: ConsentBehavior;
+  /**
+   * Names of consent sources to register (e.g. `['onetrust', 'gcm']`).
+   * Plumbed through from the CDN wrapper's `data-consent-source` attribute; the
+   * plugin registry (consent-sources/) consumes these ids.
+   */
+  consentSources?: string[];
+  /**
+   * Defense-in-depth URL privacy. When `true`, the SDK removes query params not
+   * in {@link queryParamAllowlist} (and always the hash) from BOTH the event url
+   * and the referrer before sending, so PII/secrets in the query string never
+   * leave the browser. The referrer matters most for SPAs, where it becomes the
+   * previous in-app URL on each route change. The server applies the
+   * authoritative per-project rule regardless; this only keeps the wire clean.
+   * Default `false` (url + referrer sent unchanged). UTM attribution is
+   * unaffected (captured from `window.location`, not the payload url).
+   */
+  stripQueryParams?: boolean;
+  /**
+   * Query-param names kept on the url when {@link stripQueryParams} is on
+   * (case-insensitive). Defaults to UTM params + common ad click-ids + `ref`.
+   */
+  queryParamAllowlist?: string[];
+  stickyCampaigns?: boolean;
+  stickyCampaignsExpirationInSeconds?: number;
+  cookieDomain?: string;
+  cookieExpirationInSeconds?: number;
+  enableBrowserDNT?: boolean;
+  /**
+   * Add the anonymous id as `client_reference_id` to Stripe Payment Link
+   * (`buy.stripe.com`) hrefs when they are pressed, so the payment is
+   * attributed without hand-built URLs. An existing `client_reference_id` is
+   * never overwritten, and nothing is tagged while consent withholds sending.
+   * Default `true`.
+   */
+  tagPaymentLinks?: boolean;
+  /**
+   * Engaged-time tracking: `"leave"` sends a "Page Leave" event when a page is
+   * hidden or left; `"heartbeat"` also sends a "Page Heartbeat" each visible
+   * minute. Both carry `engaged_seconds` and count as events. Overrides the
+   * dashboard setting; default is the dashboard's, which defaults to `"off"`.
+   */
+  engagement?: "off" | "leave" | "heartbeat";
+  /**
+   * Track browsers driven by WebDriver (`navigator.webdriver`), e.g. to test
+   * the integration end to end with Playwright or Selenium. Default `false`.
+   */
+  trackAutomatedBrowsers?: boolean;
+  onLoad?: () => void | Promise<void>;
+  eventMapper?: (payload: EventPayload) => EventPayload | Promise<EventPayload>;
+}
+//#endregion
+//#region src/super-properties.d.ts
+type Property = string | number | boolean;
+type Properties = Record<string, Property>;
+//#endregion
+//#region src/consent.d.ts
+type ConsentCategory = "analytics" | "functional" | "marketing";
+type PrivacySignals = {
+  doNotSellShare?: boolean;
+  gpc?: boolean;
+  gppDetected?: boolean;
+  /** Raw GPP string when present; detection + raw value only in V1. */
+  gppString?: string;
+};
+/**
+ * A persisted consent snapshot. `categories` is a partial map: an absent key
+ * means "this source never spoke about that category" (falls through to the
+ * org's consentBehavior server-side), distinct from an explicit `false` (denied).
+ */
+type ConsentSnapshot = {
+  categories: Partial<Record<ConsentCategory, boolean>>;
+  signals: PrivacySignals;
+  source: string;
+  updatedAt: string;
+  /** Optional vendor payload / consent version / region for `/consent`. */
+  sourceMetadata?: Record<string, unknown>;
+};
+//#endregion
+//#region src/api.d.ts
+type IdentifyOptions = {
+  identityVerification?: {
+    token: string;
+  };
+};
+type IdentifyResult = {
+  ok: boolean;
+  status?: number;
+  reason?: string;
+};
+type ConsentResult = {
+  ok: boolean;
+  status?: number;
+  reason?: string;
+};
+//#endregion
+//#region src/url-privacy.d.ts
+export declare const DEFAULT_QUERY_PARAM_ALLOWLIST: string[];
+//#endregion
+//#region src/index.d.ts
+/** Public argument shape for `setConsent()` — all fields optional (partial). */
+export type SetConsentInput = {
+  analytics?: boolean;
+  functional?: boolean;
+  marketing?: boolean;
+  doNotSellShare?: boolean;
+};
+/** Options for `revenue()`. `currency` is ISO-4217; the rest become metadata. */
+export type RevenueOptions = {
+  currency?: string;
+  /** Override the reserved revenue event name (defaults to "Payment"). */
+  event?: string;
+  channel?: string | null;
+  userId?: string;
+  [key: string]: any;
+};
+export declare const leapio: {
+  init: (config: SdkConfig) => Promise<void>;
+  track: (data: {
+    event: string;
+    channel?: string | null;
+    userId?: string;
+    message?: string;
+    notify?: boolean;
+    metadata?: Record<string, any>;
+    value?: number;
+    currency?: string;
+    /** Associate this event with a group/account (Segment `$groups` style).
+     *  With groupType "company" (the default when groupId is set) the platform
+     *  resolves and stamps the company on the event. */
+    groupId?: string;
+    groupType?: string;
+  }) => Promise<void>;
+  revenue: (amount: number, options?: RevenueOptions) => Promise<void>;
+  pageview: (data?: {
+    userId?: string;
+    metadata?: Record<string, any>;
+  }) => Promise<void>;
+  register: (properties: Properties) => void | true;
+  unregister: (property: string) => void;
+  reset: () => void;
+  identify: (newUserId: string, traits?: Record<string, any>, opts?: IdentifyOptions) => Promise<IdentifyResult>;
+  group: (groupId: string, traits?: Record<string, any>, opts?: IdentifyOptions & {
+    type?: string;
+  }) => Promise<IdentifyResult>;
+  setConsent: (input: SetConsentInput, opts?: {
+    identityVerification?: {
+      token: string;
+    };
+  }) => Promise<ConsentResult>;
+  getConsent: () => ConsentSnapshot | null;
+  applyConsentSnapshot: (snapshot: ConsentSnapshot) => Promise<boolean>;
+  getProperties: () => Record<string, Property>;
+  getAnonymousId: () => string | null;
+};
+//#endregion
+export { type AutocaptureConfig, type AutocaptureSnippetConfig, type ConsentBehavior, type EventPayload, type SdkConfig, leapio as default };