tracklane 0.5.0 → 0.7.0

package/README.md

@@ -91,7 +91,7 @@ build, so it is never ahead of the library.
 | -------- | -------------------- | ------ |
 | GA4      | Measurement Protocol | shipped |
 | Meta     | Conversions API      | shipped |
-| LinkedIn | Conversions API      | next   |
+| LinkedIn | Conversions API      | shipped |
 | PostHog  | Capture API          | shipped |
 | X        | Conversions API      | next   |
 

package/dist/{browser-CddkJdvX.d.ts → browser-34-CHcxK.d.ts}

@@ -1,3 +1,62 @@
+//#region src/errors.d.ts
+/**
+ * Thrown by a server provider when the vendor's endpoint answers with a
+ * non-2xx status. The message stays exactly what the provider composed,
+ * free of the payload, per `TrackingError`'s guarantee, and the vendor's own
+ * answer travels separately on `status` and `body`, for a host that asks for
+ * it via `onError` rather than a host that logs by default.
+ *
+ * See ADR-0013 for why the split exists and why `body` is a property rather
+ * than `cause`.
+ *
+ * @param message - The same one-line message the provider already throws
+ * today (e.g. `meta: the Conversions API answered 400`). Not composed here.
+ * @param details - The vendor's own answer: `provider` is the name it
+ * registers under, `status` is the HTTP status, and `body` is the response
+ * body verbatim, capped at 2048 characters with a `…[truncated]` suffix that
+ * fits inside the cap.
+ *
+ * @example
+ * ```ts
+ * throw new VendorResponseError(`meta: the Conversions API answered ${status}`, {
+ *   provider: 'meta',
+ *   status,
+ *   body: await response.text().catch(() => ''),
+ * });
+ * ```
+ */
+declare class VendorResponseError extends Error {
+  readonly provider: string;
+  readonly status: number;
+  readonly body: string;
+  constructor(message: string, details: {
+    provider: string;
+    status: number;
+    body: string;
+  });
+}
+/**
+ * Tests the brand `VendorResponseError` sets, not `instanceof`: two copies
+ * of this package in one `node_modules` produce two constructors, and
+ * `instanceof` would say `false` for an instance the other copy built. The
+ * `Symbol.for` brand is the same symbol across both.
+ *
+ * @param value - Anything a `catch` block might hand back.
+ * @returns Whether `value` carries the `VendorResponseError` brand.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await track.server('purchase', data, context);
+ * } catch (error) {
+ *   if (isVendorResponseError(error)) {
+ *     reportWithFingerprint(error.provider, error.status, error.body);
+ *   }
+ * }
+ * ```
+ */
+declare function isVendorResponseError(value: unknown): value is VendorResponseError;
+//#endregion
 //#region src/providers/ga4.server.d.ts
 /** Credentials for the GA4 Measurement Protocol. */
 interface Ga4ServerCredentials {
@@ -30,6 +89,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 {
@@ -76,6 +170,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.
@@ -267,8 +366,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.
@@ -278,7 +378,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;
@@ -374,6 +474,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;
 }
@@ -440,8 +542,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`.
  *
@@ -450,13 +554,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 {
@@ -502,6 +643,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`.
  *
@@ -589,8 +735,13 @@ 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;
+  /**
+   * 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. */
   identify?(user: UserData, traits?: Record<string, unknown>): void;
   /** Absent where the vendor documents no consent command. */
@@ -603,6 +754,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;
 }
@@ -639,5 +792,5 @@ interface BrowserTracking {
  */
 declare function createTracking(options: BrowserTrackingOptions): BrowserTracking;
 //#endregion
-export { MetaServerCredentials as A, ProviderDefault as C, PosthogServerCredentials as D, PosthogServerConfig as E, 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-CddkJdvX.d.ts.map
+export { posthog$1 as A, VendorResponseError as B, EventData as C, UserData as D, TrackingError as E, LinkedinServerCredentials as F, linkedin$1 as I, Ga4ServerConfig as L, MetaServerCredentials as M, meta$1 as N, PosthogServerConfig as O, LinkedinServerConfig as P, Ga4ServerCredentials as R, EventBinding as S, ProviderDefault as T, isVendorResponseError as V, ServerTracking as _, createTracking as a, ActionSource as b, MetaBrowserConfig as c, linkedin as d, Ga4BrowserConfig as f, ServerProvider as g, ResolvedContext as h, TrackOptions as i, MetaServerConfig as j, PosthogServerCredentials 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, ServerTrackingOptions as v, EventItem as w, ConsentState as x, createTracking$1 as y, ga4$1 as z };
+//# sourceMappingURL=browser-34-CHcxK.d.ts.map