tracklane 0.1.0 → 0.2.0

package/dist/server-cNxLsKhl.d.ts

@@ -1,152 +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-ByyXHVWd.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 {
-  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;
-  url?: string;
-  ip?: string;
-  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"> {
-  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 is
- * never a throw: by then the send happened, and throwing would tell a host's
- * retry logic to resend a delivered conversion.
- */
-interface ServerProvider<Target = string> {
-  name: string;
-  default: ProviderDefault;
-  events?: Record<string, EventBinding<Target>>;
-  track(name: Target, data: EventData, context: ResolvedContext, report: (message: string) => void): Promise<void>;
-}
-/** Options accepted by {@link createTracking}. */
-interface ServerTrackingOptions {
-  providers: readonly ServerProvider[];
-  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-cNxLsKhl.d.ts.map

package/dist/vocabulary-ByyXHVWd.d.ts

@@ -1,107 +0,0 @@
-//#region src/vocabulary.d.ts
-/**
- * The vocabulary shared by the browser and server libraries.
- *
- * These two libraries never talk to each other — 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. It is the only sharing with a reason to exist.
- */
-/** One item inside an ecommerce event, spelled the way GA4 spells it. */
-interface EventItem {
-  item_id?: string;
-  item_name?: string;
-  price?: number;
-  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 {
-  transaction_id?: string;
-  value?: number;
-  currency?: string;
-  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;
-  email?: string;
-  phone?: string;
-  firstName?: string;
-  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: silence is not a denial, and converting
- * it into one would put words in the visitor's mouth just as a grant would.
- */
-interface ConsentState {
-  ad_storage?: "granted" | "denied";
-  analytics_storage?: "granted" | "denied";
-  ad_user_data?: "granted" | "denied";
-  ad_personalization?: "granted" | "denied";
-}
-/**
- * Where a conversion happened.
- *
- * Meta's vocabulary, adopted verbatim — it is the only vendor of the five
- * that documents the concept, and it 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 {
-  provider: string;
-  event: string;
-  severity: "error" | "warning";
-  message: string;
-  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-ByyXHVWd.d.ts.map