@genlook/storefront 0.1.0

package/dist/persistence.js

@@ -0,0 +1,101 @@
+export const GENERATION_TIMEOUT_MS = 60 * 1000;
+export const STALE_TTL_MS = GENERATION_TIMEOUT_MS + 30 * 1000;
+export const RETENTION_MS = 24 * 60 * 60 * 1000;
+const STALE_ERROR = { code: "network", retryable: true, backendCode: "STALE" };
+function storageKey(storeId) {
+    return `tryon-jobs:${storeId || "default"}`;
+}
+function toPersisted(job) {
+    const base = {
+        id: job.id,
+        status: job.status,
+        photoId: job.photoId,
+        productId: job.productId,
+        variantId: job.variantId,
+        createdAt: job.createdAt,
+        seen: job.seen,
+        reported: job.reported,
+        usageAt: job.usageAt,
+        usageRefunded: job.usageRefunded,
+    };
+    if (job.status === "done") {
+        base.resultImageUrl = job.resultImageUrl;
+        base.resultImageKey = job.resultImageKey;
+    }
+    else if (job.status === "error") {
+        base.error = job.error;
+    }
+    return base;
+}
+function fromPersisted(p, now) {
+    const terminal = p.status === "done" || p.status === "error";
+    if (terminal) {
+        if (now - p.createdAt > RETENTION_MS)
+            return null;
+        if (p.status === "done") {
+            return {
+                id: p.id, photoId: p.photoId, productId: p.productId, variantId: p.variantId,
+                createdAt: p.createdAt, seen: p.seen, reported: p.reported,
+                usageAt: p.usageAt, usageRefunded: p.usageRefunded,
+                status: "done", resultImageUrl: p.resultImageUrl ?? "", resultImageKey: p.resultImageKey,
+            };
+        }
+        return {
+            id: p.id, photoId: p.photoId, productId: p.productId, variantId: p.variantId,
+            createdAt: p.createdAt, seen: p.seen, reported: p.reported,
+            usageAt: p.usageAt, usageRefunded: p.usageRefunded,
+            status: "error", error: p.error ?? STALE_ERROR,
+        };
+    }
+    if (now - p.createdAt > STALE_TTL_MS) {
+        return {
+            id: p.id, photoId: p.photoId, productId: p.productId, variantId: p.variantId,
+            createdAt: p.createdAt, seen: p.seen, reported: p.reported,
+            usageAt: p.usageAt, usageRefunded: p.usageRefunded,
+            status: "error", error: STALE_ERROR,
+        };
+    }
+    return {
+        id: p.id, photoId: p.photoId, productId: p.productId, variantId: p.variantId,
+        createdAt: p.createdAt, seen: p.seen, reported: p.reported,
+        usageAt: p.usageAt, usageRefunded: p.usageRefunded,
+        status: p.status === "requested" ? "requested" : "generating",
+    };
+}
+export function saveJobs(storage, storeId, jobs) {
+    try {
+        const persisted = jobs.map(toPersisted);
+        storage.setItem(storageKey(storeId), JSON.stringify(persisted));
+    }
+    catch {
+    }
+}
+export function loadJobs(storage, storeId, now) {
+    let raw;
+    try {
+        raw = storage.getItem(storageKey(storeId));
+    }
+    catch {
+        return [];
+    }
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const item of parsed) {
+        if (!item || typeof item.id !== "string")
+            continue;
+        const job = fromPersisted(item, now);
+        if (job)
+            out.push(job);
+    }
+    return out;
+}

package/dist/policy.d.ts

@@ -0,0 +1,24 @@
+import type { CoreState } from "./entities";
+export type PolicyAction = "upload" | "generate";
+export type BlockedReason = "email-required" | "quota-exceeded" | "login-required" | "credits-expired" | "concurrency"
+/** Legal consent is required by the host and not yet on record. Opt-in per
+ *  host (`TryOnClientConfig.requireLegalConsent`); blocks upload AND generate. */
+ | "consent-required";
+export type PolicyResult = {
+    ok: true;
+} | {
+    ok: false;
+    blocked: BlockedReason;
+};
+/** Thrown by generate() when called while blocked; carries the same typed reason. */
+export declare class PolicyBlockedError extends Error {
+    readonly reason: BlockedReason;
+    constructor(reason: BlockedReason);
+}
+/**
+ * Evaluate whether an action is permitted. Precedence (first blocking reason wins):
+ * login-required → consent-required → quota-exceeded → email-required →
+ * credits-expired → concurrency.
+ * `email-required` is a soft gate the host satisfies by collecting an email, not an error.
+ */
+export declare function can(action: PolicyAction, state: CoreState, now: number): PolicyResult;

package/dist/policy.js

@@ -0,0 +1,45 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+function countInWindow(tryOns, period, now) {
+    const cutoff = now - (period === "daily" ? DAY_MS : 7 * DAY_MS);
+    return tryOns.filter((ts) => ts > cutoff).length;
+}
+function isInFlight(job) {
+    return job.status === "requested" || job.status === "generating";
+}
+export class PolicyBlockedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Blocked: ${reason}`);
+        this.name = "PolicyBlockedError";
+        this.reason = reason;
+    }
+}
+export function can(action, state, now) {
+    const { limits, identity } = state;
+    if (limits.loggedInCustomersOnly && !identity.loggedInCustomerId) {
+        return { ok: false, blocked: "login-required" };
+    }
+    if (limits.requireLegalConsent && !state.legalConsent) {
+        return { ok: false, blocked: "consent-required" };
+    }
+    if (action === "upload")
+        return { ok: true };
+    const used = countInWindow(limits.tryOns, limits.period, now);
+    if (used >= limits.maxGenerations) {
+        return { ok: false, blocked: "quota-exceeded" };
+    }
+    const hasEmail = !!identity.email;
+    if (limits.totalTryOns >= limits.emailCollectionStep && !hasEmail) {
+        return { ok: false, blocked: "email-required" };
+    }
+    if (limits.creditsAllowed === false) {
+        return { ok: false, blocked: "credits-expired" };
+    }
+    if (typeof limits.maxConcurrent === "number" && Number.isFinite(limits.maxConcurrent)) {
+        const inFlight = Object.values(state.generations).filter(isInFlight).length;
+        if (inFlight >= limits.maxConcurrent) {
+            return { ok: false, blocked: "concurrency" };
+        }
+    }
+    return { ok: true };
+}

package/dist/ports.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Ports for the headless try-on core. Everything the domain layer needs from the
+ * host runtime is an interface here, so @genlook/storefront references no browser
+ * or Node global (tsconfig `lib: ["ES2022"]`, no "dom" — the headlessness guard).
+ */
+import type { ConsentSnapshot } from "./types";
+/** Response the core reads back. The browser `Response` structurally satisfies it. */
+export interface TransportResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** Per-request options handed to the transport. A structural subset of the
+ *  per-request options a typical HTTP client already takes, so an existing
+ *  client satisfies Transport as-is. */
+export interface TransportRequestInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Attach the device-fingerprint header — set ONLY on the generation and
+     *  upload-completion calls (backend ingests it there). */
+    includeFingerprint?: boolean;
+    /** Send with unload semantics (keepalive / navigator.sendBeacon) for the
+     *  page-hide flush. The web transport maps it to sendBeacon with a plain-fetch
+     *  keepalive fallback; other transports may treat it as a no-op hint. */
+    beacon?: boolean;
+}
+/** Opaque shopper-supplied media forwarded verbatim to Transport.putRaw (a
+ *  browser File/Blob today). The core never inspects it. Real media abstraction
+ *  lands in a later phase. */
+export type MediaInput = unknown;
+/**
+ * The two network capabilities the core needs:
+ *  - fetch — Genlook proxy call by relative path; the impl injects the app-proxy
+ *    prefix + identity headers.
+ *  - putRaw — direct byte upload to a signed (absolute) storage URL, carrying NO
+ *    Genlook identity headers (preserves the GCS signed-URL contract).
+ */
+export interface Transport {
+    fetch(path: string, init?: TransportRequestInit): Promise<TransportResponse>;
+    putRaw(url: string, body: MediaInput, headers: Record<string, string>): Promise<TransportResponse>;
+}
+/** String key/value storage. A browser's `localStorage` satisfies it directly;
+ *  async native stores go through the hydrated storage adapter, since this port
+ *  is synchronous by design. */
+export interface KVStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Consent-state source for the tracker. The impl wraps the platform adapter's
+ * `getConsentSnapshot`/`onConsentChange` (Shopify's real CMP tracker; the
+ * base-adapter placeholder for the rest). The tracker's binary gate reads the
+ * snapshot's `analytics_allowed` and stamps the snapshot on each batch.
+ */
+export interface ConsentSource {
+    /** Current snapshot, or null when no adapter/CMP has answered. */
+    getSnapshot(): ConsentSnapshot | null;
+    /** Subscribe to snapshot changes (banner accept/decline). */
+    onChange(cb: (snapshot: ConsentSnapshot | null) => void): void;
+}
+/**
+ * The named surfaces that can produce try-on traffic. A closed vocabulary the
+ * backend validates against, so "which surface is this?" is answered by the
+ * sender rather than inferred from the shape of the row.
+ *
+ *  - `widget` — the storefront widget on a merchant's shop.
+ *  - `tryon_core` — this package, driving try-ons directly (native app,
+ *    headless or custom storefront).
+ *  - `sdk_node` — the server-side Try-On API SDK.
+ *  - `raw_http` — a caller hitting the API by hand.
+ *  - `mcp_client` — an MCP client.
+ */
+export type IntegrationName = "widget" | "tryon_core" | "sdk_node" | "raw_http" | "mcp_client";
+/** Common-tier tracking context — no shopper identity, no device-storage reads.
+ *  Assembled by the web PageContext impl from DOM/host + platform state.
+ *
+ *  The page/browser fields are nullable: a non-browser host (native app, server)
+ *  has no URL, no viewport and no user agent, and a null there is worth more than
+ *  an invented value that would pollute the warehouse. The backend accepts them
+ *  as optional-nullable; a browser host keeps filling all of them. */
+export interface TrackingBaseContext {
+    $current_url: string | null;
+    $pathname: string | null;
+    $host: string | null;
+    $screen_width: number;
+    $screen_height: number;
+    $viewport_width: number | null;
+    $viewport_height: number | null;
+    $raw_user_agent: string | null;
+    $browser_language: string | null;
+    $timezone: string;
+    widget_enabled: boolean;
+    platform: string;
+    store_id: string | null;
+    product_id: string | null;
+    variant_id: string | null;
+    widget_version: string;
+    /** Content hash of the APP sources the boot was built from. `widget_version`
+     *  hashes only the runtime shell and barely moves, so it cannot answer "did my
+     *  deploy reach this shopper?". Null for a host that bakes no define. */
+    app_version?: string | null;
+    page_type: string | null;
+    collection_id: string | null;
+    /** Which surface produced the batch. Every host names itself — null means
+     *  "unknown", never "widget", so a page-level query can exclude page-less
+     *  surfaces (which send null URL/viewport/user agent) explicitly. */
+    integration: IntegrationName | null;
+    /** Version of the thing named by {@link integration}: the `wv_` build id for
+     *  the storefront widget, this package's semver for `tryon_core`. Null when
+     *  the surface has no version to report. */
+    integration_version: string | null;
+}
+/**
+ * First-touch attribution record — captured ONCE at the first page the widget
+ * observes in a session and never overwritten afterwards. Persisted host-side
+ * (ePrivacy-gated storage) and read lazily only for a full-mode batch. The three
+ * `utm_*` fields are the same first-touch UTMs the wire has always carried;
+ * `landing_path` (pathname + search, so the query string survives), `referrer`,
+ * `referring_domain`, and `ts` (ISO-8601 capture time) extend the same record.
+ */
+export interface GenlookFirstTouch {
+    utm_source: string | null;
+    utm_medium: string | null;
+    utm_campaign: string | null;
+    landing_path: string | null;
+    referrer: string | null;
+    referring_domain: string | null;
+    ts: string;
+}
+/** Full-mode-only tracking context: shopper identity + attribution + referrer.
+ *  Read from device storage, so the tracker requests it ONLY in full mode.
+ *  `$referrer`/`$referring_domain` are the CURRENT page's referrer (re-read each
+ *  batch); `first_touch` is the immutable first-observed-page record. */
+export interface TrackingIdentityContext {
+    $referrer: string | null;
+    $referring_domain: string | null;
+    session_id: string;
+    anonymous_id: string;
+    first_touch: GenlookFirstTouch | null;
+}
+/**
+ * DOM/host inputs the tracker context needs. Implemented by the host; the core
+ * never touches the DOM. `getIdentityContext` is the only method that reads
+ * ePrivacy-gated storage, and the tracker calls it exclusively in full mode.
+ */
+export interface PageContext {
+    /** True for crawlers/headless agents — the tracker drops all events then. */
+    isBot(): boolean;
+    /** Current pathname; the tracker mints a fresh pageview id when it changes.
+     *  Null for a host with no pages — it must then match `$pathname` so the
+     *  pageview id stays stable instead of re-minting on every batch. */
+    getPathname(): string | null;
+    /** Common-tier context (no identity, no gated storage reads). */
+    getBaseContext(): TrackingBaseContext;
+    /** Full-mode-only context (identity + attribution + referrer). */
+    getIdentityContext(): TrackingIdentityContext;
+    /** Drop any cached session id so a later re-read reflects the new basis. */
+    resetSessionId(): void;
+    /** Remove the two tracking-owned storage keys (anonymous id + attribution). */
+    purgeTrackingStorage(): void;
+}
+/**
+ * Connectivity as the host sees it, sampled at the moment a failure is recorded.
+ *
+ * A port because `navigator` and `document` are browser APIs and the core is
+ * platform-agnostic — a native or server host implements this differently, or not
+ * at all (it is optional).
+ *
+ * Exists because upload failures currently arrive as `"Failed to fetch"` /
+ * `"Load failed"` — the browser's generic network errors, which say nothing about
+ * cause. These three fields separate the common explanations: the shopper lost
+ * signal, they were on a slow connection, or the page was backgrounded and the
+ * in-flight request was killed.
+ */
+export interface NetworkInfo {
+    /** `navigator.onLine`. False is conclusive; true only means "not obviously off". */
+    online: boolean;
+    /** Network Information API effective type ("4g", "3g", "slow-2g"). Chromium-only. */
+    effectiveType?: string;
+    /** `document.visibilityState`. A hidden page has its fetches killed on mobile,
+     *  which is a prime suspect for the generic errors. */
+    visibility?: "visible" | "hidden";
+}

package/dist/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/public-api.d.ts

@@ -0,0 +1,235 @@
+import type { CoreState } from "./entities";
+import type { UploadMeta } from "./entities";
+import type { Listener } from "./store";
+import type { CoreEvent, CoreEventListener, CoreEventType } from "./events";
+import type { PolicyAction, PolicyResult } from "./policy";
+import type { MediaInput } from "./ports";
+import type { TryOnResult } from "./history";
+import type { GetShareUrlOptions } from "./sharing";
+import type { GenerateInput, GenerateOutput } from "./client";
+import type { PrepareUploadRequest, UploadResult, RatingReasonCode, CurrentPlanResponse, CheckCreditsResponse, CollectEmailRequest, CollectEmailResponse } from "./types";
+/**
+ * The public headless try-on surface, reachable at `window.Genlook.tryon`.
+ *
+ * The concrete `TryOnClient` implements it; hosts should type against this
+ * interface rather than the class so they only depend on the supported surface.
+ * See the module header for the cross-bundle error-recognition contract shared
+ * by every rejecting method here.
+ */
+export interface GenlookTryOn {
+    /**
+     * Current snapshot of the core state tree (limits window, identity, in-flight
+     * generations, history). Pair with {@link subscribe} to render a reactive view;
+     * the returned object is the live snapshot — treat it as read-only.
+     */
+    getState(): CoreState;
+    /**
+     * Subscribe to state transitions (a new snapshot is available after any
+     * mutating op: upload, generate, email collection, history/rating change).
+     * The listener takes no args — read the fresh state via {@link getState}.
+     * Returns an unsubscribe function. Notifications fire only when state identity
+     * actually changes.
+     */
+    subscribe(listener: Listener): () => void;
+    /**
+     * Subscribe to a named lifecycle event. Returns an unsubscribe function.
+     *
+     * The edge-triggered counterpart to {@link subscribe}: use `on` to react to a
+     * transition ("the upload just got rejected") and `subscribe` + {@link getState}
+     * to render a value ("the upload is rejected"). Without this, every host has to
+     * keep a shadow copy of the previous state and diff it to spot the transition —
+     * the same edge detection re-implemented, and mis-implemented, per UI.
+     *
+     * Events are not replayed: a listener attached after the fact does not see it.
+     * A throwing listener is swallowed and does not stop the others.
+     */
+    on<T extends CoreEventType>(type: T, listener: CoreEventListener<T>): () => void;
+    /**
+     * Subscribe to EVERY core event, current and future. Returns an unsubscribe
+     * function.
+     *
+     * For consumers that are generic over the event set rather than reacting to one
+     * thing: logging, forwarding to a host bridge, dev tooling. Prefer it wherever
+     * the consumer would otherwise hardcode a list of event names — a new event then
+     * appears automatically instead of being silently omitted.
+     */
+    onAny(listener: (event: CoreEvent) => void): () => void;
+    /**
+     * Evaluate whether an action is currently permitted by the policy layer
+     * (login gate, legal-consent gate when the host opted in, quota window,
+     * email-collection step, credits, concurrency)
+     * WITHOUT performing it or mutating state. Returns `{ ok: true }` or
+     * `{ ok: false, blocked }` with a typed {@link PolicyResult} reason. `generate`
+     * runs this same check internally and throws `PolicyBlockedError` on a block,
+     * so calling `can("generate")` first lets a host gate its UI ahead of the call.
+     */
+    can(action: PolicyAction): PolicyResult;
+    /**
+     * Record shopper acceptance of the legal-consent gate at `version` (a
+     * host-owned wording version). Persists the `{ version, acceptedAt }` record
+     * (storage-compatible with the pre-headless mobile sheet, so an already-consented
+     * shopper is recognized at boot), reflects it into `state.legalConsent`
+     * (subscribers notified — read the gate via `getState().legalConsent`, `null`
+     * means never accepted), and emits `tryon:legal_consent_accepted`.
+     *
+     * Re-accepting a NEW version overwrites the record and emits again; re-accepting
+     * the SAME version is a no-op (no duplicate event).
+     *
+     * Coupling to the policy layer is the host's choice: with
+     * `requireLegalConsent: true` in the client config, `can("upload")` and
+     * `can("generate")` return `consent-required` until this runs (and `generate()`
+     * throws `PolicyBlockedError`) — the gate is then enforced by the core, not by
+     * the UI. Left off (the default), `can()` is unaffected and showing a consent
+     * screen stays a UI decision.
+     *
+     * Emits: `tryon:legal_consent_accepted { consent_version }` (except on a
+     * same-version no-op).
+     */
+    acceptLegalConsent(version: string): void;
+    /**
+     * Upload a shopper photo. `file` is opaque host media (a browser `File`/`Blob`)
+     * forwarded verbatim to storage; `meta` carries upload provenance + the
+     * host-read validation inputs (file name + DOM dimensions); `productContext`
+     * optionally scopes the /uploads call.
+     *
+     * Registers the returned promise as the client's LATEST in-flight upload
+     * (supersede-latest): a newer `uploadPhoto` supersedes an older one, so a later
+     * `generate({ userImage: "latest" })` awaits whichever upload was newest at the
+     * time generate is called. A superseded upload still settles for its own awaiter
+     * and still emits its terminal event, but is no longer "current".
+     *
+     * PROGRESS is observable from state, mirroring generation: the photo entity
+     * transitions uploading → ready | failed through the store, so
+     * `selectCurrentUpload(getState())` + {@link subscribe} render the current
+     * upload's status without a return-value round-trip.
+     *
+     * POLICY-GATED: rejects with `PolicyBlockedError` (`name`/`reason`) before any
+     * network call when `can("upload")` blocks — under
+     * `requireLegalConsent: true` that includes `consent-required`, so an
+     * integrator's own consent screen cannot be short-circuited by calling this
+     * directly. Prefer {@link stagePhoto} at pick time: it HOLDS the photo instead
+     * of refusing it.
+     *
+     * The core VALIDATES `meta` before any network call; on a verdict it rejects
+     * with `UploadRejectedError` (`name`/`reason`, recognised by name) and creates
+     * NO entity (rejection ≠ failure). Otherwise it rejects with a typed upload
+     * failure on network/prepare errors, and the entity transitions to `failed`.
+     *
+     * Emits: `widget:image_upload` (start) then `widget:image_upload_success` /
+     * `widget:image_upload_error`; a validation verdict OR a post-crop rejection
+     * emits `widget:image_upload_rejected` instead (never both).
+     */
+    uploadPhoto(file: MediaInput, meta: UploadMeta, productContext?: PrepareUploadRequest): Promise<UploadResult>;
+    /**
+     * Hand over a freshly picked photo and let the core decide when it may be sent:
+     * uploaded IMMEDIATELY if {@link acceptLegalConsent} has already been recorded,
+     * otherwise held in memory until it is. Nothing reaches the network while
+     * consent is outstanding.
+     *
+     * Prefer this over {@link uploadPhoto} at the moment of the pick. It lets a UI
+     * put the upload behind whatever screen follows the pick (a confirm step, a
+     * consent gate) without having to know whether sending yet is allowed — and it
+     * makes "no bytes before consent" a property of the core instead of a rule each
+     * UI re-implements.
+     *
+     * Returns nothing on purpose. Observe progress via
+     * `selectCurrentUpload(getState())` + {@link subscribe}, and let
+     * `generate({ userImage: "latest" })` await the result — it resolves against
+     * whatever this started, including an upload still in flight.
+     *
+     * Supersede-latest: staging again replaces the previous photo (in flight or
+     * held). {@link clearPendingUpload} discards a held photo as well as an
+     * in-flight one.
+     *
+     * Never rejects the photo: a pick made while consent is outstanding is HELD, not
+     * refused, even under `requireLegalConsent: true`. Quota is not pre-checked
+     * either — `can("generate")` is still evaluated by generate().
+     *
+     * Emits: nothing while held; the normal {@link uploadPhoto} event sequence once
+     * released.
+     */
+    stagePhoto(file: MediaInput, meta: UploadMeta, productContext?: PrepareUploadRequest): void;
+    /**
+     * Drop the tracked in-flight upload (the shopper discarded the selected photo):
+     * clears the pending-upload pointer, any photo still held by {@link stagePhoto},
+     * AND the current-upload state pointer, so the
+     * next `generate({ userImage: "latest" })` no longer awaits it and
+     * `selectCurrentUpload(getState())` reads null. Photo entities are left in the
+     * store. Pure client-side state; no network, no events.
+     */
+    clearPendingUpload(): void;
+    /**
+     * Create and drive a try-on generation to completion. Resolve the user image
+     * from `input.userImageId` or, with `userImage: "latest"`, by awaiting the
+     * in-flight {@link uploadPhoto}. Deduped within a short TTL, gated by the policy
+     * layer, and counted against the quota window on acceptance. When `input.context`
+     * is provided, the assembled `TryOnResult` is appended to history and returned
+     * as `result`.
+     *
+     * Rejects with `PolicyBlockedError` (`name`/`reason`) when blocked, or
+     * `GenerationFailedError` (`name`/`kind`/`code`) on upload-coordination or
+     * generation failure — recognise both by `name`, never `instanceof`.
+     *
+     * Emits: `widget:generation_start` on acceptance.
+     */
+    generate(input: GenerateInput): Promise<GenerateOutput>;
+    /** Full try-on history (newest-last), the same list {@link subscribe} tracks. */
+    getHistory(): TryOnResult[];
+    /**
+     * Read-side retention view of history filtered to the merchant's retention
+     * window (stored history is never pruned; this only filters the read). Pass the
+     * retention in days, or `null`/omit for the default window.
+     */
+    recentResults(retentionDays?: number | null): TryOnResult[];
+    /** Append one result to history (notifies subscribers, persists). */
+    appendResult(entry: TryOnResult): void;
+    /** Patch a history entry by id (notifies subscribers, persists). */
+    updateResult(id: string, patch: Partial<TryOnResult>): void;
+    /** Wholesale-replace the history slice (notifies subscribers, persists). */
+    replaceHistory(entries: TryOnResult[]): void;
+    /** Clear all history (notifies subscribers, persists). */
+    clearHistory(): void;
+    /**
+     * Shopper "delete my data": erase the shopper's data server-side, then clear
+     * the local history + tracked pending upload. On a confirmed backend erasure
+     * emits `tryon:data_erased`; on failure the local state is still cleared (the
+     * screen empties either way) and no event fires. Never rejects — a host can
+     * `await` it and navigate away unconditionally.
+     *
+     * Emits: `tryon:data_erased` (only on backend success).
+     */
+    deleteMyData(): Promise<void>;
+    /**
+     * Resolve a public share URL for a history entry: short-circuits on a
+     * cached/prebaked `entry.shareUrl` (zero network), otherwise creates a share
+     * link for its generation and writes the URL back into the entry (write-through
+     * cache). `opts` supplies DOM-derived context (effective domain, product URL).
+     * Rejects if the entry id is unknown or has no generation to share.
+     */
+    getShareUrl(entryId: string, opts?: GetShareUrlOptions): Promise<string>;
+    /**
+     * Rate a history entry: `1` (up), `-1` (down), `0` (clear). `reason` is an
+     * optional typed code paired with a thumbs-down. Writes the rating through to
+     * the entry and the backend. Never rejects (backend failures are swallowed).
+     *
+     * Emits: `widget:result_rated`, plus `widget:result_rating_reason` when a
+     * reason is supplied.
+     */
+    rateResult(entryId: string, rating: 1 | -1 | 0, reason?: RatingReasonCode | null): Promise<void>;
+    /** The merchant's current plan tier. */
+    getCurrentPlan(): Promise<CurrentPlanResponse>;
+    /**
+     * Whether the store may still spend generation credits. Cached for a short TTL
+     * and mirrored into `state.limits.creditsAllowed` (drives the `credits-expired`
+     * policy block).
+     */
+    checkCredits(): Promise<CheckCreditsResponse>;
+    /**
+     * Record a shopper email against the email-collection gate: sets identity
+     * (satisfying the `email-required` policy block) and sends the backend
+     * /shopper/email call.
+     *
+     * Emits: `widget:email_collected`.
+     */
+    collectEmail(request: CollectEmailRequest): Promise<CollectEmailResponse>;
+}

package/dist/public-api.js

@@ -0,0 +1 @@
+export {};

package/dist/public.d.ts

@@ -0,0 +1,33 @@
+export { SDK_VERSION } from "./version";
+export { TryOnClient, PolicyBlockedError } from "./client";
+export type { GenerateInput, GenerateOutput, TryOnClientConfig, TryOnClientDeps } from "./client";
+export { createTryOnClient } from "./create-client";
+export type { CreateTryOnClientOptions } from "./create-client";
+export type { StoreSettings } from "./settings";
+export { SETTINGS_CACHE_TTL_MS } from "./settings";
+export { GenerationFailedError } from "./generation";
+export type { GenerationErrorKind } from "./generation";
+export type { GenlookTryOn } from "./public-api";
+export type { PolicyAction, PolicyResult, BlockedReason } from "./policy";
+export type { Listener } from "./store";
+export type { NetworkInfo } from "./ports";
+export type { CoreEvent, CoreEventType, CoreEventOf, CoreEventListener } from "./events";
+export type { GetShareUrlOptions } from "./sharing";
+export type { CurrentPlanResponse, CheckCreditsResponse, CollectEmailRequest, CollectEmailResponse, } from "./types";
+export { DEFAULT_RETENTION_DAYS } from "./history";
+export type { TryOnResult, GenerationContext } from "./history";
+export type { Transport, TransportResponse, TransportRequestInit, MediaInput, KVStorage, ConsentSource, PageContext, TrackingBaseContext, TrackingIdentityContext, GenlookFirstTouch, IntegrationName, } from "./ports";
+export { memoryStorage } from "./memory-storage";
+export { createFetchTransport, GENLOOK_API_BASE_URL, GENLOOK_STORE_API_PATH, } from "./fetch-transport";
+export type { FetchTransportOptions, FetchLike, FetchLikeInit, } from "./fetch-transport";
+export { localStorageAdapter, isLocalStorageAvailable, createHydratedStorage, defaultStorage, } from "./storage-adapters";
+export type { WebStorageLike, AsyncKVStore, HydratedStorageOptions, } from "./storage-adapters";
+export { getAnonymousId, GENLOOK_ANONYMOUS_ID_STORAGE_KEY, GENLOOK_ANONYMOUS_ID_PREFIX, } from "./anonymous-id";
+export type { UploadResult, PrepareUploadRequest, RatingReasonCode, ConsentSnapshot, } from "./types";
+export type { TrackSink } from "./analytics";
+export { staticConsent, createDefaultPageContext } from "./default-tracking";
+export type { TrackingConsentMode, DefaultPageContextOptions, ScreenSize, } from "./default-tracking";
+export type { UploadMeta, UploadDimensions } from "./entities";
+export { MAX_UPLOAD_BYTES, ALLOWED_UPLOAD_MIME_TYPES, MIN_UPLOAD_WIDTH, MIN_UPLOAD_HEIGHT, isHeicLike, validateUpload, classifyUploadFailure, UploadRejectedError, } from "./upload";
+export type { UploadRejectionReason, UploadValidationInput, UploadVerdict } from "./upload";
+export type { CoreState, PhotoUpload, LegalConsent } from "./entities";

package/dist/public.js

@@ -0,0 +1,12 @@
+export { SDK_VERSION } from "./version";
+export { TryOnClient, PolicyBlockedError } from "./client";
+export { createTryOnClient } from "./create-client";
+export { SETTINGS_CACHE_TTL_MS } from "./settings";
+export { GenerationFailedError } from "./generation";
+export { DEFAULT_RETENTION_DAYS } from "./history";
+export { memoryStorage } from "./memory-storage";
+export { createFetchTransport, GENLOOK_API_BASE_URL, GENLOOK_STORE_API_PATH, } from "./fetch-transport";
+export { localStorageAdapter, isLocalStorageAvailable, createHydratedStorage, defaultStorage, } from "./storage-adapters";
+export { getAnonymousId, GENLOOK_ANONYMOUS_ID_STORAGE_KEY, GENLOOK_ANONYMOUS_ID_PREFIX, } from "./anonymous-id";
+export { staticConsent, createDefaultPageContext } from "./default-tracking";
+export { MAX_UPLOAD_BYTES, ALLOWED_UPLOAD_MIME_TYPES, MIN_UPLOAD_WIDTH, MIN_UPLOAD_HEIGHT, isHeicLike, validateUpload, classifyUploadFailure, UploadRejectedError, } from "./upload";