@genlook/storefront 0.1.0

package/dist/settings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Merchant-owned widget settings, as `GET /settings` returns them.
+ *
+ * The storefront widget reads these off its inline theme config; an SDK
+ * integrator has no such config, so the factory pulls them from the store. Pure
+ * functions over the KVStorage + Transport ports (type-only imports), so the
+ * module stays value-self-contained and directly testable.
+ */
+import type { KVStorage, Transport } from "./ports";
+export interface StoreSettings {
+    maxGenerations: number;
+    period: "daily" | "weekly";
+    emailCollectionStep: number;
+    loggedInCustomersOnly: boolean;
+}
+/** Cache window. Fresher than this and the factory issues no request at all. */
+export declare const SETTINGS_CACHE_TTL_MS: number;
+export declare const SETTINGS_ENDPOINT = "/settings";
+/**
+ * Read a settings payload field by field. Per-field rather than all-or-nothing:
+ * the cascade is itself per-field, so a response missing a key means "no server
+ * opinion here", not "discard the whole thing". Returns null when nothing usable
+ * was found.
+ */
+export declare function parseSettings(raw: unknown): Partial<StoreSettings> | null;
+/**
+ * Cached settings for this store, with whether they are still inside the TTL.
+ * A stale entry is still returned — it seeds the state immediately while the
+ * background refresh runs, so an offline app keeps the last known settings.
+ */
+export declare function loadSettings(storage: KVStorage, storeId: string, now: number): {
+    settings: Partial<StoreSettings>;
+    fresh: boolean;
+} | null;
+export declare function saveSettings(storage: KVStorage, storeId: string, settings: Partial<StoreSettings>, now: number): void;
+/** `GET /settings`. Never rejects — a failure returns null and the cascade keeps
+ *  whatever it already resolved. */
+export declare function fetchSettings(transport: Transport): Promise<Partial<StoreSettings> | null>;

package/dist/settings.js

@@ -0,0 +1,70 @@
+export const SETTINGS_CACHE_TTL_MS = 5 * 60 * 1000;
+export const SETTINGS_ENDPOINT = "/settings";
+function storageKey(storeId) {
+    return `tryon-settings:${storeId || "default"}`;
+}
+export function parseSettings(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const out = {};
+    if (typeof r.maxGenerations === "number" && Number.isFinite(r.maxGenerations)) {
+        out.maxGenerations = r.maxGenerations;
+    }
+    if (typeof r.emailCollectionStep === "number" && Number.isFinite(r.emailCollectionStep)) {
+        out.emailCollectionStep = r.emailCollectionStep;
+    }
+    if (r.period === "daily" || r.period === "weekly")
+        out.period = r.period;
+    if (typeof r.loggedInCustomersOnly === "boolean") {
+        out.loggedInCustomersOnly = r.loggedInCustomersOnly;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
+export function loadSettings(storage, storeId, now) {
+    let raw;
+    try {
+        raw = storage.getItem(storageKey(storeId));
+    }
+    catch {
+        return null;
+    }
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const record = parsed;
+    if (typeof record.ts !== "number" || !Number.isFinite(record.ts))
+        return null;
+    const settings = parseSettings(record.settings);
+    if (!settings)
+        return null;
+    const age = now - record.ts;
+    return { settings, fresh: age >= 0 && age < SETTINGS_CACHE_TTL_MS };
+}
+export function saveSettings(storage, storeId, settings, now) {
+    try {
+        const record = { settings, ts: now };
+        storage.setItem(storageKey(storeId), JSON.stringify(record));
+    }
+    catch {
+    }
+}
+export async function fetchSettings(transport) {
+    try {
+        const response = await transport.fetch(SETTINGS_ENDPOINT, { method: "GET" });
+        if (!response.ok)
+            return null;
+        return parseSettings(await response.json());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sharing.d.ts

@@ -0,0 +1,26 @@
+import type { Transport } from "./ports";
+import type { ShareGenerationResponse } from "./types";
+import type { Store } from "./store";
+import type { CoreState } from "./entities";
+export declare function createShareLink(transport: Transport, generationId: string, effectiveDomain?: string, productUrl?: string): Promise<ShareGenerationResponse>;
+export interface ShareEngineDeps {
+    transport: Transport;
+    store: Store<CoreState>;
+    /** Emits tryon:share_link_created (bound to analytics by the client). Absent on
+     *  the short-circuit path — a cached hit creates no link, so nothing fires. */
+    emitShareLinkCreated?: (input: {
+        generationId: string;
+        entryId: string;
+    }) => void;
+}
+export interface GetShareUrlOptions {
+    effectiveDomain?: string;
+    productUrl?: string;
+}
+/**
+ * Resolve the share URL for a history entry: short-circuit on a cached/prebaked
+ * `entry.shareUrl` (zero network — scripted demo entries rely on this), else
+ * create a share link for its generation and write the URL back into the entry
+ * (write-through cache, so the next share is free).
+ */
+export declare function getShareUrl(deps: ShareEngineDeps, entryId: string, opts?: GetShareUrlOptions): Promise<string>;

package/dist/sharing.js

@@ -0,0 +1,42 @@
+export async function createShareLink(transport, generationId, effectiveDomain, productUrl) {
+    try {
+        const endpoint = `/try-ons/${encodeURIComponent(generationId)}/share`;
+        console.log("Creating share link at:", endpoint);
+        const response = await transport.fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                effectiveDomain: effectiveDomain || undefined,
+                productUrl: productUrl || undefined,
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to create share link: ${response.status} ${response.statusText}. ${errorText}`);
+        }
+        const result = (await response.json());
+        console.log("Share link created:", result.shareUrl);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error(`Unexpected error: ${error}`);
+    }
+}
+export async function getShareUrl(deps, entryId, opts = {}) {
+    const entry = deps.store.getState().history.find((r) => r.id === entryId);
+    if (!entry)
+        throw new Error(`Unknown history entry: ${entryId}`);
+    if (entry.shareUrl)
+        return entry.shareUrl;
+    if (!entry.generationId)
+        throw new Error("Generation ID is required to create share link");
+    const response = await createShareLink(deps.transport, entry.generationId, opts.effectiveDomain, opts.productUrl);
+    deps.store.setState((s) => ({
+        ...s,
+        history: s.history.map((r) => r.id === entryId ? { ...r, shareUrl: response.shareUrl } : r),
+    }));
+    deps.emitShareLinkCreated?.({ generationId: entry.generationId, entryId });
+    return response.shareUrl;
+}

package/dist/storage-adapters.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Concrete {@link KVStorage} adapters shipped with the core, so an integrator
+ * holding a publishable key does not have to write one.
+ *
+ * {@link KVStorage} is deliberately SYNCHRONOUS (`getItem` returns
+ * `string | null`, not a promise): the core reads usage, jobs, history and
+ * consent during construction, and making the port async would turn every
+ * domain call into a promise chain. Hosts whose only store is async (React
+ * Native AsyncStorage) get {@link createHydratedStorage} instead.
+ */
+import type { KVStorage } from "./ports";
+/** The `localStorage`/`sessionStorage` shape. Declared locally because the core
+ *  tsconfig keeps "dom" out of `lib` (the headlessness guard). */
+export interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** True when a usable `localStorage` is present (absent in RN, and access can
+ *  throw outright in a partitioned/blocked-cookies browser context). */
+export declare function isLocalStorageAvailable(): boolean;
+/**
+ * Browser adapter over `localStorage` (or any storage passed in — a namespaced
+ * wrapper, `sessionStorage`, a test double). Throws when no storage is
+ * reachable, so a misconfigured host fails loudly instead of silently losing
+ * every shopper's history on reload.
+ */
+export declare function localStorageAdapter(store?: WebStorageLike): KVStorage;
+/**
+ * Minimal async key/value store — the shape of React Native's AsyncStorage, so
+ * the core can be handed one without depending on any mobile package. Either
+ * `multiGet` or `getItem` is enough for hydration; `multiGet` is preferred (one
+ * bridge round-trip instead of N).
+ */
+export interface AsyncKVStore {
+    getAllKeys(): Promise<readonly string[]>;
+    multiGet?(keys: readonly string[]): Promise<readonly (readonly [string, string | null])[]>;
+    getItem?(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface HydratedStorageOptions {
+    /** Hydrate only keys starting with this prefix (skips the host app's own
+     *  keys). Omit to preload everything the store holds. */
+    keyPrefix?: string;
+    /** Called when a write-through fails. Default: `console.warn`. Never fatal —
+     *  the in-memory value already took effect. */
+    onWriteError?: (error: unknown, key: string) => void;
+}
+/**
+ * Async store → synchronous {@link KVStorage}, by preloading it into memory.
+ *
+ * Reads are served from the in-memory snapshot; writes go to memory
+ * synchronously AND are mirrored to the async store (write-through). A failed
+ * mirror is reported and swallowed: the session keeps working, only durability
+ * is lost for that key.
+ *
+ * IMPORTANT: the returned storage only reflects persisted state once this
+ * promise resolves. Await it before constructing the client — a client built on
+ * a not-yet-hydrated store starts from empty state and would mint a second
+ * anonymous id.
+ */
+export declare function createHydratedStorage(store: AsyncKVStore, options?: HydratedStorageOptions): Promise<KVStorage>;
+/**
+ * Best-effort default storage: `localStorage` when the runtime has one,
+ * otherwise an in-memory store (state lasts the session only). Used by
+ * {@link createTryOnClient} when no `storage` is supplied.
+ */
+export declare function defaultStorage(): KVStorage;

package/dist/storage-adapters.js

@@ -0,0 +1,82 @@
+import { memoryStorage } from "./memory-storage";
+function globalLocalStorage() {
+    return globalThis.localStorage;
+}
+export function isLocalStorageAvailable() {
+    try {
+        const store = globalLocalStorage();
+        if (!store)
+            return false;
+        const probe = "__genlook_probe__";
+        store.setItem(probe, "1");
+        store.removeItem(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function localStorageAdapter(store) {
+    const target = store ?? globalLocalStorage();
+    if (!target) {
+        throw new Error("[Genlook] localStorage is not available in this runtime. Pass a `storage` adapter (see createHydratedStorage for React Native).");
+    }
+    return {
+        getItem: (key) => target.getItem(key),
+        setItem: (key, value) => target.setItem(key, String(value)),
+        removeItem: (key) => target.removeItem(key),
+    };
+}
+export async function createHydratedStorage(store, options = {}) {
+    const memory = memoryStorage();
+    const onWriteError = options.onWriteError ??
+        ((error, key) => {
+            console.warn("[Genlook] Storage write failed:", key, error);
+        });
+    const allKeys = await store.getAllKeys();
+    const keys = options.keyPrefix
+        ? allKeys.filter((key) => key.startsWith(options.keyPrefix))
+        : allKeys;
+    if (keys.length > 0) {
+        if (typeof store.multiGet === "function") {
+            for (const [key, value] of await store.multiGet(keys)) {
+                if (value != null)
+                    memory.setItem(key, value);
+            }
+        }
+        else if (typeof store.getItem === "function") {
+            const getItem = store.getItem.bind(store);
+            const values = await Promise.all(keys.map((key) => getItem(key)));
+            keys.forEach((key, i) => {
+                const value = values[i];
+                if (value != null)
+                    memory.setItem(key, value);
+            });
+        }
+        else {
+            throw new Error("[Genlook] AsyncKVStore must implement multiGet or getItem to hydrate.");
+        }
+    }
+    return {
+        getItem: (key) => memory.getItem(key),
+        setItem: (key, value) => {
+            const str = String(value);
+            memory.setItem(key, str);
+            void Promise.resolve()
+                .then(() => store.setItem(key, str))
+                .catch((error) => onWriteError(error, key));
+        },
+        removeItem: (key) => {
+            memory.removeItem(key);
+            void Promise.resolve()
+                .then(() => store.removeItem(key))
+                .catch((error) => onWriteError(error, key));
+        },
+    };
+}
+export function defaultStorage() {
+    if (isLocalStorageAvailable())
+        return localStorageAdapter();
+    console.warn("[Genlook] No localStorage available — falling back to in-memory storage. Try-on history and quota will not survive a reload.");
+    return memoryStorage();
+}

package/dist/store.d.ts

@@ -0,0 +1,9 @@
+export type Listener = () => void;
+/** Minimal observable store. Zero dependencies. */
+export interface Store<S> {
+    getState(): S;
+    subscribe(listener: Listener): () => void;
+    /** Replace state with the updater's result; notifies listeners only on identity change. */
+    setState(updater: (prev: S) => S): void;
+}
+export declare function createStore<S>(initial: S): Store<S>;

package/dist/store.js

@@ -0,0 +1,23 @@
+export function createStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    return {
+        getState() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setState(updater) {
+            const next = updater(state);
+            if (next === state)
+                return;
+            state = next;
+            for (const listener of [...listeners])
+                listener();
+        },
+    };
+}

package/dist/tracker.d.ts

@@ -0,0 +1,124 @@
+import type { Transport, ConsentSource, PageContext } from "./ports";
+/** Periodic-flush cadence (ms). The batch queue is core-owned; the DOM timer that
+ *  ticks at this interval is registered by the host runtime. */
+export declare const FLUSH_INTERVAL_MS = 5000;
+/** Minimal failed-response shape captureFetchError reads. The browser `Response`
+ *  (passed by the HttpClient) structurally satisfies it — the core needs no dom. */
+interface FetchErrorResponse {
+    status: number;
+    text(): Promise<string>;
+    headers: {
+        forEach(cb: (value: string, key: string) => void): void;
+    };
+}
+export interface TrackerDeps {
+    transport: Transport;
+    consent: ConsentSource;
+    pageContext: PageContext;
+    /** Secure uuid factory (host-provided; the core takes no crypto dependency). */
+    uuid: () => string;
+    /** Injectable clock (tests). Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * The single tracking pipeline. `capture`/`captureFetchError` and the property
+ * name `tracking` are the frozen back-compat surface consumed by widget UI code,
+ * so both keep their exact signatures.
+ */
+export declare class Tracker {
+    private queue;
+    private pageviewId;
+    private lastPathname;
+    private isFlushing;
+    private readonly isBot;
+    private consentSnapshot;
+    private consentSubscribed;
+    private uiVariant;
+    private uiBuild;
+    /** Widget-scope consent override (see grantWidgetScopeConsent). */
+    private widgetScopeConsent;
+    /** In-memory identity fallbacks, minted on first need if the host can't supply
+     *  persisted ids. Ensures a batch is NEVER built without an anonymous_id +
+     *  session_id (the backend now requires both). Prefixed to match the ^anon_/
+     *  ^sess_ wire contract; stable for the tracker's lifetime once minted. */
+    private fallbackAnonymousId;
+    private fallbackSessionId;
+    private readonly transport;
+    private readonly consent;
+    private readonly pageContext;
+    private readonly uuid;
+    private readonly now;
+    private static readonly MAX_QUEUE_SIZE;
+    private static readonly EARLY_FLUSH_SIZE;
+    constructor(deps: TrackerDeps);
+    /** Stamp the active experiment variant onto every subsequent batch context
+     *  (`ui_variant`). Additive, BQ-safe; pass null to clear. */
+    setUiVariant(variant: string | null): void;
+    /** Stamp `ui_version` onto every subsequent batch context. Called by the UI
+     *  bundle once it loads, reporting its OWN content hash — the boot's
+     *  `app_version` cannot, because the UI bundle is lazy-loaded and hashed
+     *  separately, so a shopper can run a new boot against a cached older UI. */
+    setUiBuild(build: string | null): void;
+    /** Event-category prefixes that a widget-scope consent grant unlocks while SITE
+     *  analytics consent is denied. product_page:* is deliberately absent — it
+     *  stays dropped until site consent is (re)granted. */
+    private static readonly WIDGET_SCOPE_PREFIXES;
+    /** SITE-LEVEL analytics gate. Public so the experiment layer can tell whether
+     *  an exposure would be silently dropped before emitting it. Only an explicit
+     *  analytics=false snapshot blocks; true / null / undefined / no consent source
+     *  all allow (the Shopify Customer Privacy snapshot encodes regional rules). */
+    isTrackingAllowed(): boolean;
+    /**
+     * Grant the widget-scope consent override. After the shopper accepts the
+     * widget's own legal-consent gate, widget:/tryon:/sheet:/api: events ARE
+     * captured and sent (with full identity) even while SITE analytics consent is
+     * denied; product_page:* events stay dropped. Idempotent. The grant is
+     * re-derived on reload from the persisted legal-consent record (TryOnClient),
+     * so it survives a page refresh.
+     */
+    grantWidgetScopeConsent(): void;
+    /** Per-event gate: site consent allows everything; otherwise only widget-scope
+     *  events pass, and only once the widget-scope grant is set. */
+    private isEventAllowed;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    captureFetchError(url: string, method: string, error: Error | FetchErrorResponse): Promise<void>;
+    /**
+     * Drain the queue to /events. `beacon` requests unload semantics
+     * (sendBeacon / keepalive) from the transport. One path for both the periodic
+     * flush and the page-hide flush — the wire body is identical either way.
+     */
+    flush(opts?: {
+        beacon?: boolean;
+    }): Promise<void>;
+    private enqueue;
+    /**
+     * Read the consent snapshot once and subscribe to changes. Cheap: the snapshot
+     * is cached and refreshed via the change hook, so batches never trigger a
+     * per-event CMP call. Idempotent — safe to call every capture/flush.
+     */
+    private ensureConsentSubscribed;
+    /**
+     * On explicit consent deny (`analytics === "no"`), drop the two tracking-owned
+     * storage keys and the cached session id via the PageContext port. Functional
+     * `genlook-*` storage (quota counters, photo history) sits on a different legal
+     * basis and is deliberately left untouched (the port only removes those keys).
+     */
+    private handleConsentChange;
+    /**
+     * Assemble the batch context. Every sent batch is fully identified (the gate
+     * already dropped denied captures), so identity + attribution + referrer always
+     * ride. The pageview id is a plain in-memory value, re-minted when the
+     * pathname changes.
+     */
+    private buildContext;
+    /**
+     * Read the host identity context, guaranteeing a non-empty anonymous_id +
+     * session_id. Normally the host supplies persisted ids; if that read throws
+     * (storage unavailable) or returns empty ids, in-memory fallbacks fill in so a
+     * fully-identified batch is still built — a batch is never sent without ids.
+     */
+    private readIdentityContext;
+    private getFallbackAnonymousId;
+    private getFallbackSessionId;
+}
+export {};