tracklane 0.1.1 → 0.3.0

package/dist/server-DRda44Tb.d.ts

@@ -1,166 +0,0 @@
-import { c as UserData, i as EventData, n as ConsentState, o as ProviderDefault, r as EventBinding, s as TrackingError, t as ActionSource } from "./vocabulary-fzM9ZuE1.js";
-//#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(credentials: Ga4ServerCredentials, config?: Ga4ServerConfig): ServerProvider;
-//#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(options: ServerTrackingOptions): ServerTracking;
-//#endregion
-export { ServerTrackingOptions as a, Ga4ServerCredentials as c, ServerTracking as i, ga4 as l, ResolvedContext as n, createTracking as o, ServerProvider as r, Ga4ServerConfig as s, EventContext as t };
-//# sourceMappingURL=server-DRda44Tb.d.ts.map

package/dist/vocabulary-fzM9ZuE1.d.ts

@@ -1,129 +0,0 @@
-//#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
-export { EventItem as a, UserData as c, EventData as i, ConsentState as n, ProviderDefault as o, EventBinding as r, TrackingError as s, ActionSource as t };
-//# sourceMappingURL=vocabulary-fzM9ZuE1.d.ts.map