tracklane 0.6.0 → 0.8.0

package/dist/{browser-_0LRgTpx.d.ts → browser-k4gaaQgF.d.ts}

@@ -67,13 +67,28 @@ interface Ga4ServerCredentials {
 }
 /** Optional configuration for the GA4 server provider. */
 interface Ga4ServerConfig {
+  /** How this property spells each canonical event. Rarely needed. */
   events?: Record<string, EventBinding<string>>;
+  /**
+   * Sends `user_data` built from `user` (email, phone, first and last name),
+   * normalised and SHA-256 hashed the way Google documents. Off by default:
+   * it starts a new flow of personal data to Google, and the property needs
+   * user-provided data collection turned on in GA4's admin.
+   *
+   * There is no consent check in it. To withhold it, pass `user: { userId }`.
+   */
+  userProvidedData?: boolean;
 }
 /**
  * Google Analytics 4 on the server, through the Measurement Protocol.
  *
+ * **`identify` sends user properties with no event**, which Google
+ * documents. With no user property to send it sends nothing, because each
+ * `track` already carries `user_id`.
+ *
  * @param credentials - The measurement id and API secret.
- * @param config - Rarely needed event name overrides.
+ * @param config - Rarely needed event name overrides, and the opt-in for
+ * user-provided data.
  * @returns A provider for `createTracking` from `tracklane/server`.
  *
  * @example
@@ -89,6 +104,41 @@ interface Ga4ServerConfig {
  */
 declare function ga4$1(credentials: Ga4ServerCredentials, config?: Ga4ServerConfig): ServerProvider;
 //#endregion
+//#region src/providers/linkedin.server.d.ts
+/** Credentials for LinkedIn's Conversions API. */
+interface LinkedinServerCredentials {
+  /** An access token authorized for the conversion's ad account. */
+  accessToken: string;
+}
+/** Configuration for the LinkedIn Conversions API provider. */
+interface LinkedinServerConfig {
+  /** Conversion IDs minted in Campaign Manager. `null` explicitly suppresses an event. */
+  events: Record<string, EventBinding<string>>;
+  /** LinkedIn's Marketing API version, in YYYYMM form. Defaults to `202609`. */
+  apiVersion?: string;
+}
+/**
+ * Sends event-specific conversions to LinkedIn's Conversions API.
+ * Value and currency become conversionValue; items, transaction_id, custom
+ * properties, traits and consent have no documented field on this endpoint.
+ * The host's deduplication ID becomes eventId, without generating one.
+ *
+ * @param credentials - The ad account's Conversions API access token.
+ * @param config - Canonical event to conversion ID map and API version.
+ * @returns A server provider for `createTracking`.
+ * @example
+ * ```ts
+ * import { createTracking, linkedin } from 'tracklane/server';
+ * const { track } = createTracking({
+ *   providers: [linkedin({ accessToken }, { events: { purchase: '12345' } })],
+ * });
+ * await track('purchase', { value: 15, currency: 'BRL' }, {
+ *   user: { email: 'buyer@example.com' }, dedupId: 'order-1',
+ * });
+ * ```
+ */
+declare function linkedin$1(credentials: LinkedinServerCredentials, config: LinkedinServerConfig): ServerProvider;
+//#endregion
 //#region src/providers/meta.server.d.ts
 /** Credentials for Meta's Conversions API. */
 interface MetaServerCredentials {
@@ -135,6 +185,11 @@ interface MetaServerConfig {
 /**
  * Meta's Conversions API.
  *
+ * If any item lacks a nonempty `item_id`, the complete `contents` list is
+ * omitted while totals and order metadata remain unchanged. This avoids
+ * presenting a partial order or inventing product identifiers. The error
+ * channel receives one payload-free warning after HTTP acceptance.
+ *
  * @param credentials - The pixel id and an access token.
  * @param config - Event overrides, the default action source, and Meta's own
  * levers: the API version, a test event code, and Limited Data Use.
@@ -193,6 +248,12 @@ interface PosthogServerConfig {
  * Deduplication is also eventual, happening during a background merge, so both
  * rows are visible for a while and a test that counts immediately will fail.
  *
+ * **`identify` sends one `$identify`**, with `$set` and `$unset` from the
+ * traits. It merges a visitor into the user only when the context carries
+ * `anonymousId`, never from the cookie: a merge is irreversible, and PostHog
+ * reports a refused one only as an ingestion warning in its own interface.
+ * Identified events are billed with person processing.
+ *
  * @param credentials - The project API key, and the ingestion host for
  * anything other than PostHog's default US Cloud instance.
  * @param config - Rarely needed event name overrides.
@@ -326,8 +387,9 @@ type ProviderDefault = "passthrough" | "ignore";
  *
  * Fanning out to N vendors means no single call site can catch anything, so
  * this is the replica of the `try/catch` a host would have written around a
- * hand-made call. `severity` separates "this did not arrive" from "this
- * arrived, and here is something you should know".
+ * hand-made call. `severity` separates an observed failure from a caveat.
+ * Neither proves delivery: a browser command may only be queued, an HTTP
+ * success does not prove processing, and a network error may follow acceptance.
  *
  * It never carries event contents: the payload holds raw personal data by
  * design, and no library-owned surface re-emits it into a host's logs.
@@ -337,7 +399,7 @@ interface TrackingError {
   provider: string;
   /** The canonical event name being sent when this happened. */
   event: string;
-  /** `'error'` when the event did not arrive; `'warning'` when it arrived but is worth a look. */
+  /** `'error'` for an observed failure; `'warning'` for a caveat. Neither guarantees delivery. */
   severity: "error" | "warning";
   /** What happened, in one line, excluding the payload: event data never appears here. */
   message: string;
@@ -389,8 +451,31 @@ interface EventContext {
   ip?: string;
   /** The visitor's user agent. Meta's Conversions API reads it alongside `ip`. */
   userAgent?: string;
-  /** What is known *about* the person: GA4 user properties, PostHog `$set`. */
+  /**
+   * What is known *about* the person: GA4 user properties, PostHog `$set`.
+   *
+   * A trait set to `null` means "no longer known". PostHog receives it in
+   * `$unset`. GA4 leaves it out and reports that it did, because clearing a
+   * user property through the Measurement Protocol is not yet verified.
+   */
   traits?: Record<string, unknown>;
+  /**
+   * When the traits were true, if not when the event happened. Same units as
+   * `timestamp`. GA4 stamps each user property with it; vendors with no slot
+   * ignore it.
+   */
+  traitsAt?: number | Date;
+  /**
+   * Your own stable id for a visitor nobody has identified yet. Never
+   * generated by the library.
+   *
+   * PostHog uses it as `distinct_id` when there is no `user.userId`, ahead of
+   * its cookie, and `identify` merges it into the user. It must be the id the
+   * earlier PostHog events were captured under, or it merges nothing.
+   */
+  anonymousId?: string;
+  /** Cancels the vendor requests. An aborted send is reported as an error. */
+  signal?: AbortSignal;
   /**
    * Travels inside the event, for the vendors that document such a field.
    * Today that is GA4's Measurement Protocol, and it reads two of the
@@ -399,11 +484,23 @@ interface EventContext {
   consent?: ConsentState;
 }
 /** The context an adapter receives, with the ambiguity resolved. */
-interface ResolvedContext extends Omit<EventContext, "cookies" | "timestamp"> {
+interface ResolvedContext extends Omit<EventContext, "cookies" | "timestamp" | "traitsAt"> {
   /** The request's cookies, already split into a `name → value` map. */
   cookies: Record<string, string>;
   /** Epoch milliseconds. Adapters convert to their vendor's spelling. */
   timestamp: number;
+  /** Epoch milliseconds, when the host gave one. */
+  traitsAt?: number;
+}
+/**
+ * The context {@link ServerTracking.identify} takes: the same one `track`
+ * takes, with the person's id required.
+ */
+interface IdentifyContext extends EventContext {
+  /** Who the person is. `userId` is required: identifying nobody is not a call. */
+  user: UserData & {
+    userId: string;
+  };
 }
 /**
  * A destination for server events.
@@ -425,6 +522,11 @@ interface ServerProvider<Target = string> {
   events?: Record<string, EventBinding<Target>>;
   /** Sends one event to this vendor's conversion API. May throw, or call `report` for a caveat. */
   track(name: Target, data: EventData, context: ResolvedContext, report: (message: string) => void): Promise<void>;
+  /**
+   * Tells this vendor who the person is, with no event. Absent where the
+   * vendor keeps no person of its own. May throw, or call `report` for a caveat.
+   */
+  identify?(context: ResolvedContext, report: (message: string) => void): Promise<void>;
 }
 /** Options accepted by {@link createTracking}. */
 interface ServerTrackingOptions {
@@ -433,6 +535,8 @@ interface ServerTrackingOptions {
   /**
    * The one diagnostic channel. Without it the library is silent, exactly as
    * a hand-written vendor call is.
+   * Unmapped events on an `ignore` provider report warnings; explicit `null`
+   * exclusions stay silent. Attach a reporter in development to catch omissions.
    */
   onError?: (error: TrackingError) => void;
 }
@@ -447,21 +551,31 @@ interface ServerTracking {
    * guaranteed.
    */
   track(name: string, data?: EventData, context?: EventContext): Promise<void>;
+  /**
+   * Tells every vendor that keeps a person who this one is, with no event:
+   * PostHog's `$identify` and a GA4 request with user properties only.
+   * Vendors that keep no person receive nothing.
+   *
+   * A merge happens only when `anonymousId` is given. PostHog merges are
+   * irreversible, so pass it only when you know that visitor is this person.
+   * Resolves once every provider has settled and never rejects.
+   */
+  identify(context: IdentifyContext): Promise<void>;
 }
 /**
  * Creates the server tracking surface.
  *
- * There is no `identify` here and nothing is held between calls: a server
- * instance is shared by every request, so a retained identity would attach
- * one visitor to another visitor's conversion. Identity travels with the
- * call, which is also what every conversion API expects.
+ * Nothing is held between calls: a server instance is shared by every
+ * request, so a retained identity would attach one visitor to another
+ * visitor's conversion. Identity travels with each call, `identify`
+ * included, which is also what every conversion API expects.
  *
  * There is no `consent` call either. Consent commands are properties of a
  * vendor's on-page tag, and a server request has no tag. The one vendor that
  * accepts consent server-side reads it from the context.
  *
  * @param options - The providers to send to, and an optional error channel.
- * @returns The `track` call.
+ * @returns The `track` and `identify` calls.
  *
  * @example
  * ```ts
@@ -499,8 +613,10 @@ interface Ga4BrowserConfig {
  * configures the property is yours. Use {@link ConsentState} through
  * `consent()` for changes after that.
  *
- * @param measurementId - The `G-` id of the data stream, matching the tag on
- * the page.
+ * With no measurement ID, events keep the tag's configured routing. Pass a
+ * measurement ID to address that destination through `send_to` instead.
+ * Neither form installs or configures the tag.
+ *
  * @param config - Rarely needed event name overrides.
  * @returns A provider for `createTracking` from `tracklane/browser`.
  *
@@ -509,13 +625,50 @@ interface Ga4BrowserConfig {
  * import { createTracking, ga4 } from 'tracklane/browser';
  *
  * // Google's own snippet is already in the page.
- * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+ * const { track } = createTracking({ providers: [ga4()] });
  *
  * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
  * ```
  */
+declare function ga4(config?: Ga4BrowserConfig): BrowserProvider;
+/**
+ * Addresses one configured Google destination instead of using the tag's
+ * default routing. Existing calls keep their `send_to` behavior.
+ *
+ * @param measurementId - The `G-` ID of the configured data stream.
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/browser`.
+ * @example
+ * ```ts
+ * const provider = ga4('G-XXXXXXX', { events: { my_event: 'my_ga4_name' } });
+ * ```
+ */
 declare function ga4(measurementId: string, config?: Ga4BrowserConfig): BrowserProvider;
 //#endregion
+//#region src/providers/linkedin.browser.d.ts
+/** Configuration for the LinkedIn Insight Tag provider. */
+interface LinkedinBrowserConfig {
+  /** Conversion IDs minted in Campaign Manager. `null` explicitly suppresses an event. */
+  events: Record<string, EventBinding<string>>;
+}
+/**
+ * Calls the host-installed LinkedIn Insight Tag for event-specific conversions.
+ * LinkedIn has no event names, user-identification command or consent command.
+ * Items and custom parameters have no documented slot and are not forwarded.
+ *
+ * @param config - The canonical event to conversion ID map.
+ * @returns A browser provider; it does not install the Insight Tag.
+ * @example
+ * ```ts
+ * import { createTracking, linkedin } from 'tracklane/browser';
+ * const { track } = createTracking({
+ *   providers: [linkedin({ events: { purchase: '12345' } })],
+ * });
+ * track('purchase', { value: 15, currency: 'BRL' }, { dedupId: 'order-1' });
+ * ```
+ */
+declare function linkedin(config: LinkedinBrowserConfig): BrowserProvider;
+//#endregion
 //#region src/providers/meta.browser.d.ts
 /** Optional configuration for the Meta browser provider. */
 interface MetaBrowserConfig {
@@ -561,6 +714,11 @@ interface MetaBrowserConfig {
  * this adapter cannot deliver. Which pixels exist is declared by your snippet,
  * in `fbq('init')`.
  *
+ * If any item lacks a nonempty `item_id`, the complete `contents` list is
+ * omitted while totals and order metadata remain unchanged. This avoids
+ * presenting a partial order or inventing product identifiers. The error
+ * channel receives one payload-free warning after the browser command returns.
+ *
  * @param config - Event name overrides, merged over the built-in map.
  * @returns A provider for `createTracking` from `tracklane/browser`.
  *
@@ -648,10 +806,21 @@ interface BrowserProvider<Target = string> {
    * installs again, including providers that were already there.
    */
   install?(): void | Promise<void>;
-  /** Sends one event to this vendor. Throwing here reaches `onError`, not the caller. */
-  track(name: Target, data: EventData, options: TrackOptions): void;
-  /** Absent where the vendor keeps no user of its own. */
-  identify?(user: UserData, traits?: Record<string, unknown>): void;
+  /**
+   * Sends one event to this vendor. Throwing here reaches `onError`, not the caller.
+   * The optional report callback emits a payload-free warning; it is not proof
+   * of delivery or provider-side processing. Older three-argument providers
+   * and direct calls remain supported.
+   */
+  track(name: Target, data: EventData, options: TrackOptions, report?: (message: string) => void): void;
+  /**
+   * Absent where the vendor keeps no user of its own. A trait set to `null`
+   * means "no longer known". The optional report callback emits a
+   * payload-free warning, as on `track`.
+   */
+  identify?(user: UserData, traits?: Record<string, unknown>, report?: (message: string) => void): void;
+  /** Forgets the user, at sign-out. Absent where the vendor keeps no user of its own. */
+  reset?(): void;
   /** Absent where the vendor documents no consent command. */
   consent?(command: "default" | "update", state: ConsentState): void;
 }
@@ -662,6 +831,8 @@ interface BrowserTrackingOptions {
   /**
    * The one diagnostic channel. Without it the library is silent, exactly as
    * a hand-written vendor call is.
+   * Unmapped events on an `ignore` provider report warnings; explicit `null`
+   * exclusions stay silent. Attach a reporter in development to catch omissions.
    */
   onError?: (error: TrackingError) => void;
 }
@@ -671,6 +842,14 @@ interface BrowserTracking {
   track(name: string, data?: EventData, options?: TrackOptions): void;
   /** Forwards the user to the vendors that hold one, and to nobody else. */
   identify(user: UserData, traits?: Record<string, unknown>): void;
+  /**
+   * Forgets the user in every vendor that holds one, at sign-out. Never throws.
+   *
+   * Vendors differ: GA4 clears `user_id` and keeps user properties until the
+   * page reloads; PostHog's own reset also forgets its opt-in, so call
+   * `consent('update', …)` again after it.
+   */
+  reset(): void;
   /**
    * Forwards a consent declaration to every vendor that documents a command
    * for it. It never decides, stores or withholds anything.
@@ -686,7 +865,7 @@ interface BrowserTracking {
  * lost to loading and this library needs no queue of its own.
  *
  * @param options - The providers to send to, and an optional error channel.
- * @returns The `track`, `identify` and `consent` calls.
+ * @returns The `track`, `identify`, `reset` and `consent` calls.
  *
  * @example
  * ```ts
@@ -698,5 +877,5 @@ interface BrowserTracking {
  */
 declare function createTracking(options: BrowserTrackingOptions): BrowserTracking;
 //#endregion
-export { MetaServerCredentials as A, ProviderDefault as C, PosthogServerCredentials as D, PosthogServerConfig as E, VendorResponseError as F, isVendorResponseError as I, Ga4ServerConfig as M, Ga4ServerCredentials as N, posthog$1 as O, ga4$1 as P, EventItem as S, UserData as T, createTracking$1 as _, createTracking as a, EventBinding as b, MetaBrowserConfig as c, ga4 as d, EventContext as f, ServerTrackingOptions as g, ServerTracking as h, TrackOptions as i, meta$1 as j, MetaServerConfig as k, meta as l, ServerProvider as m, BrowserTracking as n, PosthogBrowserConfig as o, ResolvedContext as p, BrowserTrackingOptions as r, posthog as s, BrowserProvider as t, Ga4BrowserConfig as u, ActionSource as v, TrackingError as w, EventData as x, ConsentState as y };
-//# sourceMappingURL=browser-_0LRgTpx.d.ts.map
+export { PosthogServerCredentials as A, ga4$1 as B, EventBinding as C, TrackingError as D, ProviderDefault as E, LinkedinServerConfig as F, isVendorResponseError as H, LinkedinServerCredentials as I, linkedin$1 as L, MetaServerConfig as M, MetaServerCredentials as N, UserData as O, meta$1 as P, Ga4ServerConfig as R, ConsentState as S, EventItem as T, VendorResponseError as V, ServerProvider as _, createTracking as a, createTracking$1 as b, MetaBrowserConfig as c, linkedin as d, Ga4BrowserConfig as f, ResolvedContext as g, IdentifyContext as h, TrackOptions as i, posthog$1 as j, PosthogServerConfig as k, meta as l, EventContext as m, BrowserTracking as n, PosthogBrowserConfig as o, ga4 as p, BrowserTrackingOptions as r, posthog as s, BrowserProvider as t, LinkedinBrowserConfig as u, ServerTracking as v, EventData as w, ActionSource as x, ServerTrackingOptions as y, Ga4ServerCredentials as z };
+//# sourceMappingURL=browser-k4gaaQgF.d.ts.map

package/dist/browser.d.ts

@@ -1,2 +1,2 @@
-import { a as createTracking, c as MetaBrowserConfig, d as ga4, i as TrackOptions, l as meta, n as BrowserTracking, o as PosthogBrowserConfig, r as BrowserTrackingOptions, s as posthog, t as BrowserProvider, u as Ga4BrowserConfig } from "./browser-_0LRgTpx.js";
-export { BrowserProvider, BrowserTracking, BrowserTrackingOptions, type Ga4BrowserConfig, type MetaBrowserConfig, type PosthogBrowserConfig, TrackOptions, createTracking, ga4, meta, posthog };
+import { a as createTracking, c as MetaBrowserConfig, d as linkedin, f as Ga4BrowserConfig, i as TrackOptions, l as meta, n as BrowserTracking, o as PosthogBrowserConfig, p as ga4, r as BrowserTrackingOptions, s as posthog, t as BrowserProvider, u as LinkedinBrowserConfig } from "./browser-k4gaaQgF.js";
+export { BrowserProvider, BrowserTracking, BrowserTrackingOptions, type Ga4BrowserConfig, type LinkedinBrowserConfig, type MetaBrowserConfig, type PosthogBrowserConfig, TrackOptions, createTracking, ga4, linkedin, meta, posthog };