@studio-vaai/js-tracking 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) studio vaai GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @studio-vaai/js-tracking
+
+Typed analytics events for studio vaai, plus a beacon-based [Umami](https://umami.is)
+transport.
+
+## Public surface
+
+```ts
+interface TrackingClient {
+  trackEvent(event: TrackingEvent, options?: TrackOptions): TrackResult;
+}
+```
+
+Synchronous and fire-and-forget — the default transport dispatches via
+`navigator.sendBeacon` so events survive page unload and navigation. The
+returned `TrackResult` reflects whether the browser accepted the beacon (or
+the event was queued for later flush), not whether the server acknowledged it.
+
+Event-specific by design: every event must appear in `TrackingEvent` (see
+[`src/events.ts`](src/events.ts)). Until the first variant lands, `trackEvent`
+is uncallable — which forces a central declaration of every event the SDK can
+send.
+
+The Umami-script-style `track()` / `identify()` overloads live as
+closure-private helpers inside the transport in
+[`src/impl/fetch-umami-tracking-client.ts`](src/impl/fetch-umami-tracking-client.ts);
+they are not part of the public API.
+
+## Usage
+
+```ts
+import { createFetchUmamiTrackingClient } from "@studio-vaai/js-tracking";
+
+// Static config: websiteId known at construction.
+const tracking = createFetchUmamiTrackingClient({
+  sdkVersion: "@studio-vaai/react-components@0.1.3",
+  websiteId: "00000000-0000-0000-0000-000000000000",
+  // baseUrl defaults to https://a.studio-vaai.com
+});
+
+// Once you've declared the event in src/events.ts:
+tracking.trackEvent({ name: "try_on_started", data: { productId } });
+```
+
+### Lazy resolver (per-shop config)
+
+Pass `resolveConfig` instead of `websiteId` when the Umami website is only
+known after an async lookup (e.g. fetched via `client.tracking.getTracking()`).
+Events fired before the resolver settles are buffered internally and flushed
+in order on success.
+
+```ts
+const tracking = createFetchUmamiTrackingClient({
+  sdkVersion: "@studio-vaai/react-components@0.1.3",
+  resolveConfig: async () => {
+    const r = await client.tracking.getTracking({});
+    if (!r.ok) throw new ApiFailureError(r.error);
+    return { websiteId: r.data.umamiWebsiteId, baseUrl: r.data.umamiBaseUrl };
+  },
+});
+```
+
+## Adding an event
+
+Declare it in [`src/events.ts`](src/events.ts) as a new `TrackingEvent` union
+variant (snake_case `name`, flat-primitive `data`). Call sites then get full
+autocomplete + type-checking on `name` and `data`.
+
+## License
+
+MIT

package/dist/base.d.ts

@@ -0,0 +1,52 @@
+export type TrackErrorKind = "network" | "rejected" | "unknown";
+export interface TrackError {
+    kind: TrackErrorKind;
+    message: string;
+    details?: unknown;
+}
+export interface TrackSuccess {
+    ok: true;
+}
+export interface TrackFailure {
+    ok: false;
+    error: TrackError;
+}
+/**
+ * Fire-and-mostly-forget result. Tracking is best-effort: callers should not
+ * branch product behaviour on `ok`, but may surface a warning in dev.
+ *
+ * Returned synchronously from {@link TrackingClient.trackEvent} — reflects
+ * whether the event was queued for delivery (via the Beacon API or a buffer
+ * waiting on a lazy resolver), not whether the server received it.
+ */
+export type TrackResult = TrackSuccess | TrackFailure;
+/**
+ * Ambient page/session metadata that decorates every event. Mirrors the Umami
+ * `/api/send` payload so transports can pass it through unchanged.
+ *
+ * Browser transports auto-populate these from `window`/`document`/`navigator`
+ * when fields are absent; pass overrides via {@link TrackOptions.context} for
+ * SSR, web workers, or tests.
+ */
+export interface EventContext {
+    /** Page URL path + query, e.g. `/products/abc?ref=hero`. */
+    url?: string;
+    /** Document title. */
+    title?: string;
+    /** Hostname seen by the visitor, e.g. `shop.example.com`. */
+    hostname?: string;
+    /** HTTP `Referer` (sic) — origin page that linked to the current one. */
+    referrer?: string;
+    /** BCP-47 language tag, e.g. `en-US`. */
+    language?: string;
+    /** Screen size as `"<width>x<height>"`, e.g. `"1920x1080"`. */
+    screen?: string;
+}
+export interface TrackOptions {
+    /**
+     * Per-call overrides merged on top of whatever the transport auto-derives.
+     * Use this to attach SSR-known values or to scrub a field for a single event.
+     */
+    context?: EventContext;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,IAAI,CAAC;CACV;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB"}

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import type { TrackOptions, TrackResult } from "./base.js";
+import type { TrackingEvent } from "./events.js";
+/** Npm package id. */
+export declare const SDK_PACKAGE_ID: "@studio-vaai/js-tracking";
+/** Marker config every transport extends. */
+export type TrackingClientConfig = Record<never, never>;
+/**
+ * Transport-agnostic event sender. Implementations live under `impl/` (e.g.
+ * the Umami beacon transport) — consumers depend on this interface so the
+ * underlying analytics backend can be swapped without touching call sites.
+ */
+export interface TrackingClient {
+    /**
+     * Send a single typed event. Synchronous and fire-and-forget — implementations
+     * dispatch via the page-unload-safe Beacon API. Returns a {@link TrackResult}
+     * reflecting whether the event was successfully queued for delivery, NOT
+     * whether the server acknowledged it. Never throws — analytics must not
+     * break the host app.
+     *
+     * Buffered events (e.g. while a lazy resolver is in flight) return
+     * `{ ok: true }` immediately; if the eventual flush fails, the caller is
+     * not notified — that's the price of fire-and-forget analytics.
+     */
+    trackEvent(event: TrackingEvent, options?: TrackOptions): TrackResult;
+}
+/** Contract-only stub — throws; a transport package supplies a real implementation. */
+export declare function createTrackingClient(_config: TrackingClientConfig): TrackingClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,sBAAsB;AACtB,eAAO,MAAM,cAAc,EAAG,0BAAmC,CAAC;AAElE,6CAA6C;AAC7C,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;CACvE;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAElF"}

package/dist/client.js

@@ -0,0 +1,10 @@
+import { TrackingClientNotImplementedError } from "./errors.js";
+//#region src/client.ts
+/** Npm package id. */
+var SDK_PACKAGE_ID = "@studio-vaai/js-tracking";
+/** Contract-only stub — throws; a transport package supplies a real implementation. */
+function createTrackingClient(_config) {
+	throw new TrackingClientNotImplementedError();
+}
+//#endregion
+export { SDK_PACKAGE_ID, createTrackingClient };

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** Thrown by the contract-only {@link createTrackingClient} stub. */
+export declare class TrackingClientNotImplementedError extends Error {
+    readonly code: "tracking_client_not_implemented";
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,IAAI,EAAG,iCAAiC,CAAU;IAE3D,cAKC;CACF"}

package/dist/errors.js

@@ -0,0 +1,11 @@
+//#region src/errors.ts
+/** Thrown by the contract-only {@link createTrackingClient} stub. */
+var TrackingClientNotImplementedError = class extends Error {
+	code = "tracking_client_not_implemented";
+	constructor() {
+		super("@studio-vaai/js-tracking: createTrackingClient has no runtime implementation; use a transport like createFetchUmamiTrackingClient.");
+		this.name = "TrackingClientNotImplementedError";
+	}
+};
+//#endregion
+export { TrackingClientNotImplementedError };

package/dist/events.d.ts

@@ -0,0 +1,127 @@
+import type { Step } from "./steps.js";
+/**
+ * Shape every tracked event must satisfy. The `name` field is the
+ * discriminator Umami uses for the event name; `data` becomes Umami's event
+ * `data` payload — each variant declares its own concrete data shape so call
+ * sites get field-level autocomplete.
+ *
+ * Wire convention: event names and `data` keys are kebab-case so they read
+ * cleanly in Umami's event-data viewer. Values must be string/number/boolean
+ * primitives — the transport doesn't recursively serialize nested objects.
+ */
+export interface TrackingEventBase {
+    /** Stable event name (kebab-case). Becomes the Umami event name. */
+    readonly name: string;
+    /** Flat primitive payload. Each variant tightens this to a concrete shape. */
+    readonly data?: object;
+}
+/**
+ * Fields present on every event's `data`. The transport additionally injects
+ * `sdk-version` from {@link FetchUmamiTrackingClientConfig.sdkVersion}, so
+ * callers never set that themselves.
+ */
+interface CommonData {
+    readonly "product-id": string;
+}
+interface EntrypointImpressionEvent extends TrackingEventBase {
+    readonly name: "entrypoint-impression";
+    readonly data: CommonData & {
+        /** Merchant-defined identifier for the entrypoint placement. */
+        readonly entry: string;
+    };
+}
+interface EntrypointClickedEvent extends TrackingEventBase {
+    readonly name: "entrypoint-clicked";
+    readonly data: CommonData & {
+        readonly entry: string;
+        /**
+         * Optional finer-grained placement classifier within `entry` (e.g.
+         * `entry: "pdp-button"` + `subentry: "size-row"`). Merchant-defined.
+         */
+        readonly subentry?: string;
+        readonly "current-step": Step;
+    };
+}
+interface IntroOpenedEvent extends TrackingEventBase {
+    readonly name: "intro-opened";
+    readonly data: CommonData & {
+        /** Typically `entry` | `image-rejection` | `image-record`. */
+        readonly source: Step;
+    };
+}
+interface ConsentGrantedEvent extends TrackingEventBase {
+    readonly name: "consent-granted";
+    readonly data: CommonData;
+}
+interface ImageRecordInitiatedEvent extends TrackingEventBase {
+    readonly name: "image-record-initiated";
+    readonly data: CommonData & {
+        /** Typically `intro` | `height`. */
+        readonly source: Step;
+    };
+}
+interface ImageUploadInitiatedEvent extends TrackingEventBase {
+    readonly name: "image-upload-initiated";
+    readonly data: CommonData & {
+        /** Typically `intro` | `height`. */
+        readonly source: Step;
+    };
+}
+interface ImageUploadAbortedEvent extends TrackingEventBase {
+    readonly name: "image-upload-aborted";
+    readonly data: CommonData;
+}
+interface ImageUploadedEvent extends TrackingEventBase {
+    readonly name: "image-uploaded";
+    readonly data: CommonData & {
+        readonly "image-source": "record-self-timer" | "record-system-dialog" | "select";
+    };
+}
+interface HeightEnteredEvent extends TrackingEventBase {
+    readonly name: "height-entered";
+    readonly data: CommonData & {
+        /** Typically `image-upload` | `variant-selection`. */
+        readonly source: Step;
+    };
+}
+interface VariantSelectionInitiatedEvent extends TrackingEventBase {
+    readonly name: "variant-selection-initiated";
+    readonly data: CommonData & {
+        /** Typically `height` | `try-on`. */
+        readonly source: Step;
+    };
+}
+/**
+ * Selected variant axes carried by events that fire after the user has chosen
+ * a specific variant (try-on, cart add, order). Emitted as flat
+ * `variant-<axis>` keys (e.g. `variant-color`, `variant-size`,
+ * `variant-length`). Axis names are open so merchants can configure new axes
+ * without an SDK change.
+ */
+type VariantData = Readonly<Partial<Record<`variant-${string}`, string>>>;
+interface TryOnInitiatedEvent extends TrackingEventBase {
+    readonly name: "try-on-initiated";
+    readonly data: CommonData & VariantData;
+}
+interface CartItemAddedEvent extends TrackingEventBase {
+    readonly name: "cart-item-added";
+    readonly data: CommonData & VariantData;
+}
+interface OrderPlacedEvent extends TrackingEventBase {
+    readonly name: "order-placed";
+    readonly data: CommonData & VariantData;
+}
+interface ViewClosedEvent extends TrackingEventBase {
+    readonly name: "view-closed";
+    readonly data: CommonData & {
+        readonly "current-step": Step;
+    };
+}
+/**
+ * Discriminated union of every event the SDK can send. Add new events by
+ * declaring a variant interface above and appending it to the union — call
+ * sites get full autocomplete + type-checking on `name` and `data`.
+ */
+export type TrackingEvent = EntrypointImpressionEvent | EntrypointClickedEvent | IntroOpenedEvent | ConsentGrantedEvent | ImageRecordInitiatedEvent | ImageUploadInitiatedEvent | ImageUploadAbortedEvent | ImageUploadedEvent | HeightEnteredEvent | VariantSelectionInitiatedEvent | TryOnInitiatedEvent | CartItemAddedEvent | OrderPlacedEvent | ViewClosedEvent;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/impl/fetch-umami-tracking-client.d.ts

@@ -0,0 +1,69 @@
+import type { EventContext } from "../base.js";
+import type { TrackingClient, TrackingClientConfig } from "../client.js";
+/** Default Umami base URL (int/prod Umami). */
+export declare const DEFAULT_UMAMI_BASE_URL: "https://a.studio-vaai.com";
+/** Per-shop Umami config the {@link FetchUmamiTrackingClientConfig.resolveConfig} resolver returns. */
+export interface ResolvedUmamiConfig {
+    /** Umami website UUID for this shop. */
+    websiteId: string;
+    /** Optional override; defaults to {@link DEFAULT_UMAMI_BASE_URL} when omitted. */
+    baseUrl?: string;
+}
+/**
+ * Sync sender used by the transport. The default delegates to
+ * `navigator.sendBeacon` — the page-unload-safe analytics primitive. Tests
+ * inject their own recorder.
+ */
+export type SendBeaconFn = (url: string, data: BodyInit) => boolean;
+export interface FetchUmamiTrackingClientConfig extends TrackingClientConfig {
+    /**
+     * Stamped on every event as the `sdk-version` field. Higher SDK layers
+     * (e.g. `@studio-vaai/react-components`) pass their own
+     * `"<pkg>@<version>"` here so the analytics view shows the version of the
+     * SDK merchants actually install — not this internal tracking package.
+     */
+    sdkVersion: string;
+    /**
+     * Static Umami website UUID. Provide this OR {@link resolveConfig}, not both.
+     * Use the static form when the website id is known at client construction.
+     */
+    websiteId?: string;
+    /** Static Umami base URL. Used together with {@link websiteId}. Defaults to {@link DEFAULT_UMAMI_BASE_URL}. */
+    baseUrl?: string;
+    /**
+     * Lazy resolver for per-shop Umami config. Provide this OR {@link websiteId},
+     * not both. Runs once when the client is constructed; events fired before
+     * the promise settles are buffered internally and flushed (in order) the
+     * moment the resolver returns. Buffered events have already returned
+     * `{ ok: true }` to the caller — if the eventual flush fails (resolver
+     * rejected or sendBeacon refused) the caller is not notified.
+     */
+    resolveConfig?: () => Promise<ResolvedUmamiConfig>;
+    /**
+     * Override the beacon sender. Defaults to `navigator.sendBeacon` bound to
+     * `navigator` when available; falls back to a no-op that reports `false`
+     * (so the call site can surface `{ ok: false }` in SSR / older browsers).
+     */
+    sendBeacon?: SendBeaconFn;
+    /**
+     * Ambient context applied to every payload, before per-call overrides. Useful
+     * for SSR-known fields or to pin a hostname different from `window.location`.
+     */
+    defaultContext?: EventContext;
+}
+/**
+ * Umami `/api/send` transport for {@link TrackingClient}. Dispatches via the
+ * Beacon API so events survive page unload and navigation; the return value
+ * reports whether the browser accepted the beacon, not whether the server
+ * acknowledged it. Errors are never thrown — analytics cannot break the host app.
+ *
+ * Supports two configuration modes:
+ * - **Static**: pass `websiteId` (and optionally `baseUrl`) at construction.
+ *   Events fire immediately.
+ * - **Lazy**: pass `resolveConfig` for per-shop Umami config that's only known
+ *   asynchronously (e.g. fetched via `client.tracking.getTracking()`). Events
+ *   fired before the resolver settles are buffered in order and flushed once
+ *   the config is available.
+ */
+export declare function createFetchUmamiTrackingClient(config: FetchUmamiTrackingClientConfig): TrackingClient;
+//# sourceMappingURL=fetch-umami-tracking-client.d.ts.map

package/dist/impl/fetch-umami-tracking-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-umami-tracking-client.d.ts","sourceRoot":"","sources":["../../src/impl/fetch-umami-tracking-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAyC,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzE,+CAA+C;AAC/C,eAAO,MAAM,sBAAsB,EAAG,2BAAoC,CAAC;AAE3E,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;AAEpE,MAAM,WAAW,8BAA+B,SAAQ,oBAAoB;IAC1E;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACnD;;;;OAIG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B;AAkHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,GACrC,cAAc,CAgJhB"}

package/dist/impl/fetch-umami-tracking-client.js

@@ -0,0 +1,154 @@
+//#region src/impl/fetch-umami-tracking-client.ts
+/** Default Umami base URL (int/prod Umami). */
+var DEFAULT_UMAMI_BASE_URL = "https://a.studio-vaai.com";
+function deriveBrowserContext() {
+	const ctx = {};
+	if (typeof globalThis === "undefined") return ctx;
+	const w = globalThis.window;
+	if (typeof w === "undefined") return ctx;
+	const loc = w.location;
+	if (typeof loc !== "undefined") {
+		ctx.hostname = loc.hostname;
+		ctx.url = `${loc.pathname}${loc.search}`;
+	}
+	const doc = w.document;
+	if (typeof doc !== "undefined") {
+		ctx.title = doc.title;
+		if (doc.referrer !== "") ctx.referrer = doc.referrer;
+	}
+	const nav = w.navigator;
+	if (typeof nav !== "undefined") ctx.language = nav.language;
+	const scr = w.screen;
+	if (typeof scr !== "undefined") ctx.screen = `${String(scr.width)}x${String(scr.height)}`;
+	return ctx;
+}
+function mergeContext(base, defaults, overrides) {
+	return {
+		...base,
+		...defaults,
+		...overrides
+	};
+}
+function applyContext(payload, ctx) {
+	if (typeof ctx.hostname !== "undefined") payload.hostname = ctx.hostname;
+	if (typeof ctx.language !== "undefined") payload.language = ctx.language;
+	if (typeof ctx.screen !== "undefined") payload.screen = ctx.screen;
+	if (typeof ctx.title !== "undefined") payload.title = ctx.title;
+	if (typeof ctx.url !== "undefined") payload.url = ctx.url;
+	if (typeof ctx.referrer !== "undefined") payload.referrer = ctx.referrer;
+}
+function networkError(message, details) {
+	return details === void 0 ? {
+		kind: "network",
+		message
+	} : {
+		kind: "network",
+		message,
+		details
+	};
+}
+function bakeState(websiteId, baseUrl) {
+	return {
+		endpoint: `${(baseUrl ?? "https://a.studio-vaai.com").replace(/\/$/, "")}/api/send`,
+		websiteId
+	};
+}
+function defaultSendBeacon() {
+	return (url, data) => {
+		if (typeof navigator === "undefined" || typeof navigator.sendBeacon !== "function") return false;
+		return navigator.sendBeacon.bind(navigator)(url, data);
+	};
+}
+/**
+* Umami `/api/send` transport for {@link TrackingClient}. Dispatches via the
+* Beacon API so events survive page unload and navigation; the return value
+* reports whether the browser accepted the beacon, not whether the server
+* acknowledged it. Errors are never thrown — analytics cannot break the host app.
+*
+* Supports two configuration modes:
+* - **Static**: pass `websiteId` (and optionally `baseUrl`) at construction.
+*   Events fire immediately.
+* - **Lazy**: pass `resolveConfig` for per-shop Umami config that's only known
+*   asynchronously (e.g. fetched via `client.tracking.getTracking()`). Events
+*   fired before the resolver settles are buffered in order and flushed once
+*   the config is available.
+*/
+function createFetchUmamiTrackingClient(config) {
+	const sendBeacon = config.sendBeacon ?? defaultSendBeacon();
+	let resolved = null;
+	let resolverError = null;
+	const pending = [];
+	const staticWebsiteId = config.websiteId;
+	const resolverFn = config.resolveConfig;
+	if (staticWebsiteId === void 0 && resolverFn === void 0) throw new Error("createFetchUmamiTrackingClient: provide either `websiteId` or `resolveConfig`");
+	if (staticWebsiteId !== void 0 && resolverFn !== void 0) throw new Error("createFetchUmamiTrackingClient: pass either `websiteId` or `resolveConfig`, not both");
+	if (staticWebsiteId !== void 0) resolved = bakeState(staticWebsiteId, config.baseUrl);
+	else if (resolverFn !== void 0) {
+		if (config.baseUrl !== void 0) throw new Error("createFetchUmamiTrackingClient: `baseUrl` is set by the resolver in lazy mode — drop the static `baseUrl`");
+		(async () => {
+			try {
+				const r = await resolverFn();
+				resolved = bakeState(r.websiteId, r.baseUrl);
+			} catch (error) {
+				resolverError = {
+					kind: "unknown",
+					message: "Failed to resolve Umami tracking config",
+					details: error
+				};
+			}
+			while (pending.length > 0) {
+				const item = pending.shift();
+				if (item === void 0) break;
+				if (resolved === null) continue;
+				sendNow(resolved, item.event, item.options);
+			}
+		})();
+	}
+	function dispatchBeacon(state, body) {
+		let blob;
+		try {
+			blob = new Blob([JSON.stringify(body)], { type: "application/json" });
+		} catch (error) {
+			return {
+				ok: false,
+				error: networkError("Failed to serialise event", error)
+			};
+		}
+		if (!sendBeacon(state.endpoint, blob)) return {
+			ok: false,
+			error: networkError("navigator.sendBeacon refused the event (quota exceeded, payload too large, or unavailable)")
+		};
+		return { ok: true };
+	}
+	function track(state, name, data, contextOverrides) {
+		const payload = { website: state.websiteId };
+		applyContext(payload, mergeContext(deriveBrowserContext(), config.defaultContext, contextOverrides));
+		if (typeof name !== "undefined") payload.name = name;
+		if (typeof data !== "undefined") payload.data = { ...data };
+		return dispatchBeacon(state, {
+			type: "event",
+			payload
+		});
+	}
+	function sendNow(state, event, options) {
+		const data = {
+			...event.data ?? {},
+			"sdk-version": config.sdkVersion
+		};
+		return track(state, event.name, data, options?.context);
+	}
+	return { trackEvent: (event, options) => {
+		if (resolved !== null) return sendNow(resolved, event, options);
+		if (resolverError !== null) return {
+			ok: false,
+			error: resolverError
+		};
+		pending.push({
+			event,
+			options
+		});
+		return { ok: true };
+	} };
+}
+//#endregion
+export { DEFAULT_UMAMI_BASE_URL, createFetchUmamiTrackingClient };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { EventContext, TrackError, TrackErrorKind, TrackFailure, TrackOptions, TrackResult, TrackSuccess, } from "./base.js";
+export type { TrackingClient, TrackingClientConfig } from "./client.js";
+export { createTrackingClient, SDK_PACKAGE_ID } from "./client.js";
+export { TrackingClientNotImplementedError } from "./errors.js";
+export type { TrackingEvent, TrackingEventBase } from "./events.js";
+export type { Step } from "./steps.js";
+export type { FetchUmamiTrackingClientConfig, ResolvedUmamiConfig, } from "./impl/fetch-umami-tracking-client.js";
+export { createFetchUmamiTrackingClient, DEFAULT_UMAMI_BASE_URL, } from "./impl/fetch-umami-tracking-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EACV,8BAA8B,EAC9B,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,uCAAuC,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+import { TrackingClientNotImplementedError } from "./errors.js";
+import { SDK_PACKAGE_ID, createTrackingClient } from "./client.js";
+import { DEFAULT_UMAMI_BASE_URL, createFetchUmamiTrackingClient } from "./impl/fetch-umami-tracking-client.js";
+export { DEFAULT_UMAMI_BASE_URL, SDK_PACKAGE_ID, TrackingClientNotImplementedError, createFetchUmamiTrackingClient, createTrackingClient };

package/dist/steps.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Every distinct step in the studio vaai try-on flow state machine. Used as
+ * the `source` and `current-step` value type on tracking events.
+ *
+ * This union is the analytics view of the flow — it doesn't have to match the
+ * exact XState state IDs in `@studio-vaai/js-machine` 1:1. Callers translate
+ * from machine state to {@link Step} at the event-emit site. Extend the union
+ * here when a new flow step needs to appear in analytics.
+ */
+export type Step = "entry" | "intro" | "consent" | "image-record" | "image-upload" | "image-rejection" | "height" | "variant-selection" | "try-on" | "cart" | "order";
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GACZ,OAAO,GACP,OAAO,GACP,SAAS,GACT,cAAc,GACd,cAAc,GACd,iBAAiB,GACjB,QAAQ,GACR,mBAAmB,GACnB,QAAQ,GACR,MAAM,GACN,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@studio-vaai/js-tracking",
+  "version": "0.1.3",
+  "description": "Typed analytics events for studio vaai, plus a fetch-based Umami transport.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && rm -f tsconfig.tsbuildinfo && tsgo --emitDeclarationOnly",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:watch": "vitest --config ../../vitest.config.ts"
+  },
+  "devDependencies": {
+    "vite": "8.0.5"
+  }
+}