@studio-vaai/js-tracking

Typed analytics events for studio vaai, plus a Umami transport that posts to /api/send via keepalive fetch.

Public surface

interface TrackingClient {
  trackEvent(event: TrackingEvent, options?: TrackOptions): TrackResult;
}

Synchronous and fire-and-forget — the default transport dispatches via fetch with keepalive: true and credentials: "omit" so events survive page unload and work against cross-origin Umami hosts that return Access-Control-Allow-Origin: *. The returned TrackResult reflects whether the request was queued (or the event was buffered for later flush), not whether the server acknowledged it.

Event-specific by design: every event must appear in TrackingEvent (see 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; they are not part of the public API.

Usage

import { createFetchUmamiTrackingClient } from "@studio-vaai/js-tracking";

// Static config: websiteId known at construction.
const tracking = createFetchUmamiTrackingClient({
  sdkVersion: "@studio-vaai/[email protected]",
  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.

const tracking = createFetchUmamiTrackingClient({
  sdkVersion: "@studio-vaai/[email protected]",
  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 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