tracklane 0.1.1 → 0.3.0

package/README.md

@@ -1,14 +1,20 @@
 # tracklane
 
-> One interface between your application and every tool that receives events.
+> One interface between your application and every analytics and advertising tool, in the browser
+> and through their conversion APIs.
 
 Every analytics and advertising tool arrives with its own SDK, its own event names and its own
 payload format. Add a second one and the tracking call at each conversion point stops being a line
 and becomes a block. Add a third and every one of those blocks has to change.
 
-`tracklane` gives your application one interface. Name what happened once, in GA4's vocabulary,
-and it reaches every tool you configured, in the browser and through their server-side conversion
-APIs.
+The server-side half is worse. Each vendor ships a separate conversion API with a different name
+and a different contract: Google's Measurement Protocol, Meta's Conversions API, LinkedIn's
+Conversions API, PostHog's Capture API. Each wants its own identifiers, its own hashing rules, and
+its own way of tying a server event back to the browser event so the two are not counted twice.
+
+`tracklane` gives your application one interface for both. Name what happened once, in GA4's
+vocabulary, and it reaches every tool you configured, translated into that tool's event names,
+payload shape and identifiers.
 
 **Documentation:** https://tracklane.codar.me
 
@@ -40,6 +46,10 @@ consent('update', { ad_storage: 'granted', analytics_storage: 'granted' });
 
 ## Server
 
+Each vendor's conversion API, behind the call you already wrote. The credentials are that vendor's
+own: GA4's Measurement Protocol wants a `measurementId` alongside its `apiSecret`, exactly as its
+own endpoint does.
+
 ```ts
 import { createTracking, ga4 } from 'tracklane/server';
 
@@ -72,7 +82,20 @@ install vendor tags.
 
 ## Providers
 
-**GA4** ships today, on both surfaces. **Meta, LinkedIn, PostHog and X** are next.
+Both surfaces, or it does not count as shipped. This table is checked against the source on every
+build, so it is never ahead of the library.
+
+<!-- providers:start -->
+
+| Vendor   | Conversion API       | Status |
+| -------- | -------------------- | ------ |
+| GA4      | Measurement Protocol | shipped |
+| Meta     | Conversions API      | shipped |
+| LinkedIn | Conversions API      | next   |
+| PostHog  | Capture API          | shipped |
+| X        | Conversions API      | next   |
+
+<!-- providers:end -->
 
 Any tool that receives events about what your users do can be a destination, and writing your own
 uses the same public contract the built-in ones use, without a registry entry, an allow-list, or a

package/dist/browser-FeV5oRFZ.d.ts

@@ -0,0 +1,628 @@
+//#region src/providers/ga4.server.d.ts
+/** Credentials for the GA4 Measurement Protocol. */
+interface Ga4ServerCredentials {
+  /** The `G-` id of the data stream. */
+  measurementId: string;
+  /** Created under Admin → Data Streams → Measurement Protocol. */
+  apiSecret: string;
+}
+/** Optional configuration for the GA4 server provider. */
+interface Ga4ServerConfig {
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * Google Analytics 4 on the server, through the Measurement Protocol.
+ *
+ * @param credentials - The measurement id and API secret.
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/server`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret: process.env.GA4_SECRET! })],
+ * });
+ *
+ * await track('purchase', order, { cookies: request.headers.get('cookie') });
+ * ```
+ */
+declare function ga4$1(credentials: Ga4ServerCredentials, config?: Ga4ServerConfig): ServerProvider;
+//#endregion
+//#region src/providers/meta.server.d.ts
+/** Credentials for Meta's Conversions API. */
+interface MetaServerCredentials {
+  /** The pixel (dataset) id events are posted to. */
+  pixelId: string;
+  /** A system user or page access token with `ads_management`. It is a credential. */
+  accessToken: string;
+}
+/** Optional configuration for the Meta server provider. */
+interface MetaServerConfig {
+  /** How this pixel spells each canonical event, merged over the built-in map. */
+  events?: Record<string, EventBinding<string>>;
+  /**
+   * Where conversions happen by default. Meta requires `action_source` on
+   * every event, so there is always a value; `context.source` overrides it
+   * per call, which is what a webhook and a checkout need.
+   */
+  actionSource?: ActionSource;
+  /** The Graph API version in the URL. Defaults to a pinned one. */
+  apiVersion?: string;
+  /**
+   * Routes events to the Test Events tab in Events Manager instead of the
+   * live dataset. **Testing only**: Meta says to remove it before
+   * production, and it is the only instrument that shows what a payload
+   * actually became.
+   */
+  testEventCode?: string;
+  /**
+   * Meta's Limited Data Use marking, forwarded verbatim: `['LDU']` to enable
+   * it, `[]` to disable it.
+   *
+   * This is a processing marking that some US state laws require, not a
+   * consent declaration, which is why it is configuration on this factory and
+   * not a reading of `context.consent`. The browser half has no equivalent:
+   * `fbq('dataProcessingOptions', …)` is documented as running before
+   * `fbq('init')`, and the snippet is the host's.
+   */
+  dataProcessingOptions?: readonly string[];
+  /** `0` lets Meta geolocate. Meaningless without `dataProcessingOptions`. */
+  dataProcessingOptionsCountry?: number;
+  /** `0` lets Meta geolocate. Meaningless without `dataProcessingOptions`. */
+  dataProcessingOptionsState?: number;
+}
+/**
+ * Meta's Conversions API.
+ *
+ * @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.
+ * @returns A provider for `createTracking` from `tracklane/server`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, meta } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [meta({ pixelId: '1234567890', accessToken: process.env.META_TOKEN! })],
+ * });
+ *
+ * await track('purchase', order, {
+ *   user: { email: order.email },
+ *   cookies: request.headers.get('cookie'),
+ *   dedupId: order.id,
+ *   ip,
+ *   userAgent,
+ * });
+ * ```
+ */
+declare function meta$1(credentials: MetaServerCredentials, config?: MetaServerConfig): ServerProvider;
+//#endregion
+//#region src/providers/posthog.server.d.ts
+/** Credentials for PostHog's Capture API. */
+interface PosthogServerCredentials {
+  /** The project API key, the same one the browser SDK is initialised with (`phc_...`). */
+  apiKey: string;
+  /**
+   * Where this project ingests events, when it is not PostHog's default US
+   * Cloud instance — `https://eu.i.posthog.com` for the EU Cloud, or a
+   * self-hosted deployment's own origin. Defaults to `https://us.i.posthog.com`.
+   */
+  host?: string;
+}
+/** Optional configuration for the PostHog server provider. */
+interface PosthogServerConfig {
+  /**
+   * How this project spells each canonical event. Rarely needed: `capture()`
+   * accepts any string, so the canonical vocabulary already is PostHog's.
+   */
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * PostHog on the server, through the Capture API.
+ *
+ * @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.
+ * @returns A provider for `createTracking` from `tracklane/server`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, posthog } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [posthog({ apiKey: process.env.POSTHOG_API_KEY! })],
+ * });
+ *
+ * await track('purchase', order, {
+ *   user: { userId: order.userId },
+ *   cookies: request.headers.get('cookie'),
+ * });
+ * ```
+ */
+declare function posthog$1(credentials: PosthogServerCredentials, config?: PosthogServerConfig): ServerProvider;
+//#endregion
+//#region src/vocabulary.d.ts
+/**
+ * The vocabulary shared by the browser and server libraries.
+ *
+ * These two libraries never talk to each other. They share no runtime, no
+ * state, no instance in common. What they share is this: the names of
+ * events and the shape of the data that travels with them, so that
+ * `purchase` means the same thing on both sides. This is the only overlap
+ * that exists on purpose.
+ */
+/** One item inside an ecommerce event, spelled the way GA4 spells it. */
+interface EventItem {
+  /** The SKU or catalogue id for this line. */
+  item_id?: string;
+  /** The product name for this line, shown in reports. */
+  item_name?: string;
+  /** The unit price for this line, before `quantity`. */
+  price?: number;
+  /** How many units of this line. */
+  quantity?: number;
+  [key: string]: unknown;
+}
+/**
+ * The business payload of an event.
+ *
+ * The named fields are the ones adapters read to build vendor-specific value
+ * and content slots. The index signature is deliberate: a business measures
+ * things this vocabulary does not name, and closing the bag would make the
+ * library the arbiter of what may be measured.
+ */
+interface EventData {
+  /** The order id. GA4 needs it, together with `items`, to record a purchase. */
+  transaction_id?: string;
+  /** The monetary amount, paired with `currency`. */
+  value?: number;
+  /** An ISO 4217 code. GA4 requires it whenever `value` is set. */
+  currency?: string;
+  /** The cart or order lines, required by GA4 alongside `transaction_id` for a purchase. */
+  items?: EventItem[];
+  [key: string]: unknown;
+}
+/**
+ * Who the person is.
+ *
+ * One identifier for the person, which every vendor receives under its own
+ * name. Values are always raw: hashing and normalisation are field formats
+ * each vendor defines, applied inside the adapter that owns the field.
+ *
+ * Everything else that identifies someone arrives through cookies on the
+ * server, read by whichever adapter knows the format.
+ */
+interface UserData {
+  /** One id for the person, translated per vendor. */
+  userId?: string;
+  /** Raw and unhashed. Adapters that need it hashed (Meta, LinkedIn) do that themselves. */
+  email?: string;
+  /** Raw, in whatever format the host has it. An adapter normalises it if its vendor needs to. */
+  phone?: string;
+  /** Raw, read only by vendors whose identity match uses names, such as Meta. */
+  firstName?: string;
+  /** Raw, read only by vendors whose identity match uses names, such as Meta. */
+  lastName?: string;
+  /** From the URL rather than a cookie, which is why it is named here. */
+  twclid?: string;
+}
+/**
+ * Consent signals, in Google's own spelling.
+ *
+ * Google's is the most granular surface any of the five vendors exposes, so
+ * every other vendor receives a *collapse* of it. Carrying the finest
+ * resolution and reducing per vendor means a projection never claims more
+ * than the host declared. Expanding a coarse answer into fine signals would
+ * invent information, and this library never does that.
+ *
+ * An absent signal produces no key. Treating silence as a denial would put
+ * words in the visitor's mouth, just as treating it as a grant would.
+ */
+interface ConsentState {
+  /** Governs Google's ad cookies. Browser only, since GA4's server-side API has no slot for it. */
+  ad_storage?: "granted" | "denied";
+  /** Governs Google's analytics cookies. Browser only, since GA4's server-side API has no slot. */
+  analytics_storage?: "granted" | "denied";
+  /** Whether user data may be sent for ads. GA4's server-side API reads this one, uppercased. */
+  ad_user_data?: "granted" | "denied";
+  /** Whether ads may be personalised. GA4's server-side API reads this one too, uppercased. */
+  ad_personalization?: "granted" | "denied";
+}
+/**
+ * Where a conversion happened.
+ *
+ * Meta's vocabulary, adopted verbatim, because it is the only vendor of the
+ * five that documents the concept and requires the field on every server
+ * event. Inventing a taxonomy and translating it would be both incomplete
+ * for Meta and meaningless to everyone else.
+ */
+type ActionSource = "website" | "app" | "email" | "phone_call" | "chat" | "physical_store" | "system_generated" | "business_messaging" | "other";
+/**
+ * How a canonical event name is spelled for one vendor, or `null` to say
+ * "never send this event here".
+ */
+type EventBinding<Target> = Target | null;
+/** What a provider does with a canonical event it has no binding for. */
+type ProviderDefault = "passthrough" | "ignore";
+/**
+ * Reported out of band, never thrown at the call site.
+ *
+ * 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".
+ *
+ * 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.
+ */
+interface TrackingError {
+  /** Which vendor produced this. It matches the `name` on the provider that registered it. */
+  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. */
+  severity: "error" | "warning";
+  /** What happened, in one line, excluding the payload: event data never appears here. */
+  message: string;
+  /** The original thrown value, where one exists, for a host that wants more than `message`. */
+  cause?: unknown;
+}
+//#endregion
+//#region src/server.d.ts
+/**
+ * Everything a conversion API needs beyond the event itself: who the person
+ * is, when it happened, and where it was observed.
+ *
+ * None of this is "what happened", which is why it does not travel in the
+ * event data: putting it there would leak identity into the pass-through
+ * event params of the vendors that forward the payload as-is.
+ */
+interface EventContext {
+  /** The person's identity, the server-side counterpart to `identify()` on the browser. */
+  user?: UserData;
+  /**
+   * The request's raw `Cookie` header, or an already-parsed map.
+   *
+   * These are cookies the vendors' own browser tags set. This library never
+   * writes one. On the server each adapter reads the cookies belonging to
+   * its own vendor: Meta forwards its value as-is, Google's holds several
+   * things at once and has to be opened. That knowledge lives in the
+   * adapters; the core only splits `name=value; name=value` into pairs.
+   *
+   * **It splits, it does not interpret.** Values are handed over exactly as
+   * they appear, with no percent-decoding. The cookies these vendors set do
+   * not need it; a host reading some other cookie should decode it itself.
+   */
+  cookies?: string | Record<string, string> | null;
+  /** Ties this send to a browser hit. Never invented by the library. */
+  dedupId?: string;
+  /**
+   * When the conversion actually happened. Defaults to now.
+   *
+   * A webhook arrives after the fact and LinkedIn rejects conversions older
+   * than 90 days, so reporting "now" for everything would quietly distort
+   * attribution.
+   */
+  timestamp?: number | Date;
+  /** Overrides the factory default. Meta requires it on every event. */
+  source?: ActionSource;
+  /** The page the conversion happened on. Meta's Conversions API reads it as `event_source_url`. */
+  url?: string;
+  /** The visitor's IP. Meta's Conversions API reads it as one of the identifiers in `user_data`. */
+  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`. */
+  traits?: Record<string, unknown>;
+  /**
+   * 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
+   * signals; the others have no slot and ignore it.
+   */
+  consent?: ConsentState;
+}
+/** The context an adapter receives, with the ambiguity resolved. */
+interface ResolvedContext extends Omit<EventContext, "cookies" | "timestamp"> {
+  /** 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;
+}
+/**
+ * A destination for server events.
+ *
+ * `track` may throw, on a non-2xx or where a vendor documents a
+ * precondition the event cannot meet. The dispatcher isolates and reports
+ * it, so adapters stay honest and loud.
+ *
+ * `report` is for a caveat about a request that already succeeded. It does
+ * not throw: by then the send happened, and throwing would tell a host's
+ * retry logic to resend a delivered conversion.
+ */
+interface ServerProvider<Target = string> {
+  /** The vendor's fixed name. Registering one twice is an error. */
+  name: string;
+  /** What happens to a canonical event this vendor has no binding for. */
+  default: ProviderDefault;
+  /** How this vendor spells each canonical event. */
+  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>;
+}
+/** Options accepted by {@link createTracking}. */
+interface ServerTrackingOptions {
+  /** The vendors to send every event to. Registering the same `name` twice throws. */
+  providers: readonly ServerProvider[];
+  /**
+   * The one diagnostic channel. Without it the library is silent, exactly as
+   * a hand-written vendor call is.
+   */
+  onError?: (error: TrackingError) => void;
+}
+/** What {@link createTracking} returns. */
+interface ServerTracking {
+  /**
+   * Sends one event to every configured conversion API.
+   *
+   * Resolves once every provider has settled and never rejects: one vendor
+   * being down is not the caller's failure to handle. Awaiting is about the
+   * request surviving a serverless runtime, not about delivery being
+   * guaranteed.
+   */
+  track(name: string, data?: EventData, context?: EventContext): 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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/server';
+ *
+ * const { track } = createTracking({
+ *   providers: [ga4({ measurementId: 'G-XXXXXXX', apiSecret })],
+ * });
+ *
+ * await track('purchase', order, { cookies: request.headers.get('cookie') });
+ * ```
+ */
+declare function createTracking$1(options: ServerTrackingOptions): ServerTracking;
+//#endregion
+//#region src/providers/ga4.browser.d.ts
+/** Optional configuration for the GA4 browser provider. */
+interface Ga4BrowserConfig {
+  /**
+   * How this property spells each canonical event. Rarely needed: the
+   * canonical vocabulary already is GA4's.
+   */
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * Google Analytics 4 in the browser, through `gtag.js`.
+ *
+ * **This provider does not load Google's tag.** The tag belongs on the page,
+ * installed the way Google documents it: a snippet in the HTML, or a tag
+ * manager. This library talks to the tag that is already there; it never
+ * injects a third-party script into your page, and it never issues the
+ * property configuration that would emit a second page view.
+ *
+ * Which also means the initial consent declaration is not ours to make:
+ * Google requires it before the property is configured, and the snippet that
+ * 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.
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/browser`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/browser';
+ *
+ * // Google's own snippet is already in the page.
+ * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+ *
+ * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+ * ```
+ */
+declare function ga4(measurementId: string, config?: Ga4BrowserConfig): BrowserProvider;
+//#endregion
+//#region src/providers/meta.browser.d.ts
+/** Optional configuration for the Meta browser provider. */
+interface MetaBrowserConfig {
+  /**
+   * How this pixel spells each canonical event, merged over the built-in map.
+   *
+   * This is how the eight standard events with no GA4 counterpart are
+   * reached, and how an event is kept out of Meta entirely with `null`.
+   */
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * The Meta pixel in the browser, through `fbq`.
+ *
+ * **This provider does not load Meta's pixel.** The base code belongs on the
+ * page, installed the way
+ * [Meta documents it](https://developers.facebook.com/docs/meta-pixel/get-started):
+ * a snippet in the HTML, or a tag manager. This library talks to the pixel
+ * that is already there; it never injects a third-party script and never
+ * issues `fbq('init')`.
+ *
+ * Three consequences follow from that, and all three are Meta's rules rather
+ * than ours:
+ *
+ * - **There is no `identify` here.** Meta accepts advanced matching only in
+ *   the base code ("be sure to place advanced matching parameters in the
+ *   pixel base code or the values will not be treated as manual advanced
+ *   matching values"), and the base code is yours. Put `em`, `ph`, `fn`, `ln`
+ *   in your own `fbq('init')`, where the pixel normalises and hashes them for
+ *   you. On the server, where there is no snippet, the same identity travels
+ *   in `context.user` and is hashed by the adapter.
+ * - **The initial consent declaration is not ours.** Meta wants
+ *   `fbq('consent', 'revoke')` before `init`, and by the time you hold what
+ *   `createTracking` returns that moment has passed. Ours is every
+ *   declaration after it, through `consent()`.
+ * - **Limited Data Use is not ours either.** `fbq('dataProcessingOptions', …)`
+ *   is documented as running before `init`. It belongs in your snippet. The
+ *   server half, which has no snippet, carries it on its factory.
+ *
+ * **There is no pixel id here**, and that is deliberate rather than an
+ * omission. `fbq('track')` reaches every pixel the page initialised, so an id
+ * passed in would address nothing and the parameter would promise something
+ * this adapter cannot deliver. Which pixels exist is declared by your snippet,
+ * in `fbq('init')`.
+ *
+ * @param config - Event name overrides, merged over the built-in map.
+ * @returns A provider for `createTracking` from `tracklane/browser`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, meta } from 'tracklane/browser';
+ *
+ * // Meta's own base code is already in the page, and it named the pixel.
+ * const { track } = createTracking({ providers: [meta()] });
+ *
+ * // fbq('track', 'Purchase', { value: 49.9, currency: 'BRL' }, { eventID: 'T-1' })
+ * track('purchase', { value: 49.9, currency: 'BRL' }, { dedupId: 'T-1' });
+ * ```
+ */
+declare function meta(config?: MetaBrowserConfig): BrowserProvider;
+//#endregion
+//#region src/providers/posthog.browser.d.ts
+/** Optional configuration for the PostHog browser provider. */
+interface PosthogBrowserConfig {
+  /**
+   * How this project spells each canonical event. Rarely needed: `capture()`
+   * accepts any string, so the canonical vocabulary already is PostHog's.
+   */
+  events?: Record<string, EventBinding<string>>;
+}
+/**
+ * PostHog in the browser, through `posthog-js`.
+ *
+ * **This provider does not load PostHog's snippet.** It belongs on the page,
+ * installed the way PostHog documents it: a snippet in the HTML, or a tag
+ * manager. This library talks to the instance that is already there; it
+ * never injects a third-party script into your page.
+ *
+ * @param config - Rarely needed event name overrides.
+ * @returns A provider for `createTracking` from `tracklane/browser`.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, posthog } from 'tracklane/browser';
+ *
+ * // PostHog's own snippet is already in the page.
+ * const { track } = createTracking({ providers: [posthog()] });
+ *
+ * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+ * ```
+ */
+declare function posthog(config?: PosthogBrowserConfig): BrowserProvider;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * Everything the browser needs beyond the event itself.
+ *
+ * There is one field, and that is the point: in the browser each vendor tag
+ * reads its own cookies and holds its own session, so the only thing left
+ * for the host to supply is the value that ties this hit to a server-side
+ * one.
+ */
+interface TrackOptions {
+  /**
+   * The value that lets a vendor recognise this hit and a server-side hit as
+   * one event. The library never invents it: the browser and the server do
+   * not share a process, so only a value the host already owns (an order id)
+   * can match on both sides.
+   */
+  dedupId?: string;
+}
+/**
+ * A destination for browser events.
+ *
+ * This is the whole contract. A provider written outside this package
+ * implements it exactly as the providers shipped here do.
+ */
+interface BrowserProvider<Target = string> {
+  /** The vendor's fixed name. Registering one twice is an error. */
+  name: string;
+  /** What happens to a canonical event this vendor has no binding for. */
+  default: ProviderDefault;
+  /** How this vendor spells each canonical event. */
+  events?: Record<string, EventBinding<Target>>;
+  /**
+   * Loads the vendor tag, at creation.
+   *
+   * **Make it idempotent.** A host that rebuilds its tracking, as
+   * `@tracklane/consent` does on every consent answer, creates again and
+   * 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;
+  /** Absent where the vendor documents no consent command. */
+  consent?(command: "default" | "update", state: ConsentState): void;
+}
+/** Options accepted by {@link createTracking}. */
+interface BrowserTrackingOptions {
+  /** The vendors to send every event to. Registering the same `name` twice throws. */
+  providers: readonly BrowserProvider[];
+  /**
+   * The one diagnostic channel. Without it the library is silent, exactly as
+   * a hand-written vendor call is.
+   */
+  onError?: (error: TrackingError) => void;
+}
+/** What {@link createTracking} returns. */
+interface BrowserTracking {
+  /** Sends one event to every configured vendor. Never throws. */
+  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;
+  /**
+   * Forwards a consent declaration to every vendor that documents a command
+   * for it. It never decides, stores or withholds anything.
+   */
+  consent(command: "default" | "update", state: ConsentState): void;
+}
+/**
+ * Creates the browser tracking surface.
+ *
+ * Providers install eagerly, which is what pasting a vendor snippet does and
+ * what lets each vendor record its own initial page view. Every vendor
+ * shipped here queues its own commands until its script lands, so nothing is
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { createTracking, ga4 } from 'tracklane/browser';
+ *
+ * const { track } = createTracking({ providers: [ga4('G-XXXXXXX')] });
+ * track('purchase', { transaction_id: 'T-1', value: 49.9, currency: 'BRL' });
+ * ```
+ */
+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-FeV5oRFZ.d.ts.map