@genlook/storefront 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# @genlook/storefront
+
+Headless virtual try-on for your storefront. Upload a shopper's photo, run the try-on, get the image back. You own every pixel of the interface.
+
+This is the same engine that powers the [Genlook](https://genlook.app) try-on widget, live on 900+ stores. With it, a custom storefront, a native app, or a server runs the exact flow the widget runs, without the widget.
+
+```javascript
+import { createTryOnClient } from "@genlook/storefront";
+
+const genlook = createTryOnClient({
+  publishableKey: "pk_your_key_here",
+  storeId: "your-store.myshopify.com",
+});
+
+const { fileId } = await genlook.uploadPhoto(file, {
+  fileSize: file.size,
+  mimeType: file.type,
+  uploadSource: "gallery",
+  skipClientDimensionCheck: false,
+});
+
+const { imageUrl } = await genlook.generate({
+  userImageId: fileId,
+  productId: "gid://shopify/Product/1234567890",
+});
+```
+
+Most try-ons finish in 10 to 20 seconds. `generate` resolves when the image is ready; progress is observable through state if you want a richer loading screen.
+
+## What it does, and what it deliberately does not
+
+The client handles everything that has a wrong way to do it: the photo upload, the polling, the shopper's identity and quota, try-on history, sharing, ratings, and the analytics that feed the merchant dashboard.
+
+It renders nothing. No modal, no button, no styles. State in, actions out; the interface is yours.
+
+## Install
+
+```bash
+npm install @genlook/storefront
+```
+
+You need a **publishable key**. In your Shopify admin, open the Genlook Try-On app, go to Settings, and create one under **Publishable key**. It is safe to embed in your code: it can only do what a shopper on your storefront could already do.
+
+Works today for stores on Shopify and SHOPLINE. WooCommerce and PrestaShop stores route through their site's Genlook plugin instead; see the [integration docs](https://genlook.app/docs/virtual-tryon/direct-api-access).
+
+## React Native
+
+The client keeps state in a synchronous store. Hand it an async store once at startup and everything else is identical to the web:
+
+```javascript
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { createHydratedStorage, createTryOnClient } from "@genlook/storefront";
+
+const storage = await createHydratedStorage(AsyncStorage);
+const genlook = createTryOnClient({ publishableKey, storeId, storage });
+```
+
+Await the hydration once before the first try-on. On app background, call `genlook.flushEvents({ beacon: true })` so the last analytics batch ships.
+
+## State and events
+
+Two complementary ways to drive your UI:
+
+```javascript
+// Re-render from the current state after every change:
+const unsubscribe = genlook.subscribe(() => {
+  render(genlook.getState());
+});
+
+// React to the moment something happens:
+genlook.on("tryon:generation_succeeded", (e) => {
+  showResult(e);
+});
+genlook.on("tryon:photo_upload_failed", (e) => {
+  showRetry(e);
+});
+```
+
+`subscribe` is for rendering, `on` is for reacting. Events are not replayed: a listener attached after the fact does not see the past.
+
+## Ask before you act
+
+`can(action)` evaluates whether an action would be allowed right now, without performing it:
+
+```javascript
+const verdict = genlook.can("generate");
+if (!verdict.ok) {
+  // verdict.blocked is one of:
+  // "quota-exceeded" | "login-required" | "consent-required"
+  // | "email-required" | "credits-expired" | "concurrency"
+  showBlockedState(verdict.blocked);
+}
+```
+
+Use it to disable your button before the shopper taps it, rather than surfacing an error after.
+
+## Quotas and the email prompt
+
+The merchant sets a per-shopper try-on quota in their Genlook app settings. The server enforces it, and the client stays in sync with those settings automatically, so `can("generate")` reflects them without any work on your side. You never enforce the quota yourself.
+
+To override a setting for your integration, pass it in `limits`; anything you leave out follows the store:
+
+```javascript
+createTryOnClient({
+  publishableKey,
+  storeId,
+  limits: { emailCollectionStep: 99 }, // optional overrides
+});
+```
+
+About that email step: the widget asks shoppers for an email after a set number of try-ons, and the client mirrors this. When `can("generate")` returns `email-required`, show your own email form and call `collectEmail({ email })`, or override `emailCollectionStep` as above if your app collects emails elsewhere. The API itself never refuses a try-on for a missing email.
+
+## Consent, and the optimistic upload
+
+By default the client enforces no consent gate: you own your user experience, including any consent step your situation requires. If you show one, let the client enforce it so it cannot be bypassed:
+
+```javascript
+const genlook = createTryOnClient({
+  publishableKey,
+  storeId,
+  requireLegalConsent: true,
+});
+
+// The photo is HELD IN MEMORY. Not one byte leaves the device yet.
+genlook.stagePhoto(file, meta);
+
+// The moment consent is recorded, the held photo uploads on its own.
+genlook.acceptLegalConsent("2026-01");
+```
+
+`stagePhoto` is the pattern worth copying even without a gate: the photo is ready to go the instant the shopper confirms, instead of the upload starting after the tap, at the exact moment they are waiting.
+
+## Error handling
+
+Every rejecting method throws one of three errors. Match on `err.name`, which survives bundling; `instanceof` may not:
+
+```javascript
+try {
+  await genlook.generate({ userImage: "latest", productId });
+} catch (err) {
+  if (err.name === "PolicyBlockedError") {
+    // err.reason: the same values can("generate") returns
+  } else if (err.name === "GenerationFailedError") {
+    // err.code: the wire code (QUOTA_EXCEEDED, PRODUCT_BLOCKED, ...)
+    // err.kind: a routing category (quota, rate_limited, ...) for your UI
+  } else if (err.name === "UploadRejectedError") {
+    // err.reason: "invalid_image_type" | "file_too_large" | ...
+  }
+}
+```
+
+## Analytics and privacy
+
+The client reports the try-on funnel to the merchant dashboard. No personal data is collected: pseudonymous ids only, and outside a browser no URL, no user agent, no device details.
+
+```javascript
+// On by default. One option turns it off entirely:
+createTryOnClient({ publishableKey, storeId, tracking: "denied" });
+```
+
+Shoppers can erase their data: `deleteMyData()` clears the server side for this device and wipes local history.
+
+## API overview
+
+| | |
+| --- | --- |
+| Try-on | `uploadPhoto`, `stagePhoto`, `generate`, `can` |
+| State | `getState`, `subscribe`, `on`, `onAny` |
+| History | `getHistory`, `recentResults`, `rateResult`, `getShareUrl`, `clearHistory` |
+| Store status | `checkCredits`, `getCurrentPlan` |
+| Shopper | `collectEmail`, `acceptLegalConsent`, `deleteMyData` |
+| Lifecycle | `flushEvents`, `dispose` |
+
+Every default is replaceable: bring your own `Transport`, `KVStorage`, or `TrackSink` when the environment calls for it. `memoryStorage()` ships for tests.
+
+## Documentation
+
+Full guides, the HTTP API the client speaks, and platform specifics: [genlook.app/docs](https://genlook.app/docs/virtual-tryon/direct-api-access).
+
+Questions or a platform we should support next: [support@genlook.app](mailto:support@genlook.app).

package/dist/analytics.d.ts

@@ -0,0 +1,26 @@
+import type { CoreEvents } from "./events";
+/** Funnel-event sink. The boot passes the core Tracker directly (`sdk.tracking`),
+ *  whose `capture` method satisfies this shape — no host closure needed. */
+export interface TrackSink {
+    capture(event: string, props?: Record<string, unknown>): void;
+    /** Optional widget-scope consent grant (the core Tracker implements it; the
+     *  no-op test sink does not). Called when the shopper accepts the widget's
+     *  legal-consent gate so widget:/tryon:/sheet:/api: events keep flowing even
+     *  when site analytics consent is denied. */
+    grantWidgetScopeConsent?(): void;
+    /** Optional queue drain to `/events` (the core Tracker implements it; the
+     *  no-op test sink does not). `beacon` requests unload semantics. Surfaced on
+     *  the client as `flushEvents`, mirroring how a browser host drives the
+     *  tracker's flush from its own page-hide listeners. */
+    flush?(opts?: {
+        beacon?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Subscribe the analytics sink to the core event bus. Returns an unsubscribe
+ * function. Called once, by the client constructor.
+ *
+ * `CoreEvents.emit` guards listeners, so a tracking failure can never break a
+ * try-on.
+ */
+export declare function attachAnalytics(events: CoreEvents, sink: TrackSink): () => void;

package/dist/analytics.js

@@ -0,0 +1,7 @@
+export function attachAnalytics(events, sink) {
+    const capture = sink.capture.bind(sink);
+    return events.onAny((e) => {
+        const { type, ...props } = e;
+        capture(type, props);
+    });
+}

package/dist/anonymous-id.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The widget-issued anonymous device id, owned by the core.
+ *
+ * It lives behind the {@link KVStorage} port, so a browser host, a native host
+ * (AsyncStorage) and a test all get the same id semantics.
+ *
+ * WIRE + STORAGE CONTRACT — do not change: deployed widgets already hold ids
+ * under this exact key in this exact format. A different key or prefix silently
+ * re-anonymises every returning shopper (lost photo history, reset quota) and
+ * breaks the backend's `anon_` guard in `readAnonymousId`.
+ */
+import type { KVStorage } from "./ports";
+/** Storage key for the anonymous device id. NOT namespaced (`genlook-…`) — the
+ *  pre-core widget wrote it raw, and the key has to stay byte-identical. Also
+ *  exported so a host can purge exactly this key on a consent deny. */
+export declare const GENLOOK_ANONYMOUS_ID_STORAGE_KEY = "_genlook_anonymous_id";
+/** Id prefix. The backend rejects any anonymous id that lacks it. */
+export declare const GENLOOK_ANONYMOUS_ID_PREFIX = "anon_";
+/**
+ * RFC 4122 v4 UUID. Own implementation because the core carries zero
+ * dependencies. `crypto.randomUUID` first, `getRandomValues` second, never
+ * `Math.random()` — its weak entropy produced real collisions in the event
+ * stream (the same id across devices).
+ */
+export declare function uuid(): string;
+/**
+ * Read the persisted anonymous id, minting + persisting one on first call.
+ * Stable for the lifetime of the storage it is given.
+ */
+export declare function getAnonymousId(storage: KVStorage): string;

package/dist/anonymous-id.js

@@ -0,0 +1,33 @@
+export const GENLOOK_ANONYMOUS_ID_STORAGE_KEY = "_genlook_anonymous_id";
+export const GENLOOK_ANONYMOUS_ID_PREFIX = "anon_";
+function getCrypto() {
+    return globalThis.crypto;
+}
+export function uuid() {
+    const c = getCrypto();
+    if (c && typeof c.randomUUID === "function")
+        return c.randomUUID();
+    if (c && typeof c.getRandomValues === "function") {
+        const bytes = new Uint8Array(16);
+        c.getRandomValues(bytes);
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = [];
+        for (let i = 0; i < 16; i++)
+            hex.push((bytes[i] + 0x100).toString(16).slice(1));
+        return (hex[0] + hex[1] + hex[2] + hex[3] +
+            "-" + hex[4] + hex[5] +
+            "-" + hex[6] + hex[7] +
+            "-" + hex[8] + hex[9] +
+            "-" + hex[10] + hex[11] + hex[12] + hex[13] + hex[14] + hex[15]);
+    }
+    throw new Error("[Genlook] No crypto source available to mint an anonymous id.");
+}
+export function getAnonymousId(storage) {
+    let id = storage.getItem(GENLOOK_ANONYMOUS_ID_STORAGE_KEY);
+    if (!id) {
+        id = `${GENLOOK_ANONYMOUS_ID_PREFIX}${uuid()}`;
+        storage.setItem(GENLOOK_ANONYMOUS_ID_STORAGE_KEY, id);
+    }
+    return id;
+}

package/dist/client.d.ts

@@ -0,0 +1,289 @@
+import type { Transport, KVStorage, MediaInput, NetworkInfo } from "./ports";
+import type { CurrentPlanResponse, CheckCreditsResponse, CollectEmailRequest, CollectEmailResponse, ShareGenerationResponse, UploadResult, PrepareUploadRequest, RatingReasonCode } from "./types";
+import type { CoreState, GenerationJob, UploadMeta } from "./entities";
+import type { Listener } from "./store";
+import type { PolicyAction, PolicyResult } from "./policy";
+import { PolicyBlockedError } from "./policy";
+import type { TrackSink } from "./analytics";
+import type { CoreEvent, CoreEventListener, CoreEventType } from "./events";
+import type { GetShareUrlOptions } from "./sharing";
+import type { StoreSettings } from "./settings";
+import type { TryOnResult, GenerationContext } from "./history";
+import type { GenlookTryOn } from "./public-api";
+/** Parsed widget config surfaced to the core. Limits/identity feed the policy layer. */
+export interface TryOnClientConfig {
+    storeId?: string;
+    locale?: string;
+    loggedInCustomersOnly?: boolean;
+    loggedInCustomerId?: string | null;
+    /** Block upload + generate with `consent-required` until `acceptLegalConsent`
+     *  is recorded. Default false — only a host that presents a consent gate
+     *  should ask the core to enforce one. */
+    requireLegalConsent?: boolean;
+    limits?: {
+        maxGenerations?: number | null;
+        emailCollectionStep?: number | null;
+        period?: "daily" | "weekly" | null;
+        maxConcurrent?: number;
+    };
+}
+export interface TryOnClientDeps {
+    config: TryOnClientConfig;
+    transport: Transport;
+    storage: KVStorage;
+    /** Core tracker the funnel events fire through. Defaults to a no-op sink. */
+    tracker?: TrackSink;
+    /** Injectable clock (tests). Defaults to Date.now. */
+    now?: () => number;
+    /** Host connectivity probe, sampled when a failure is recorded. Optional — a
+     *  host that cannot answer simply omits the fields. */
+    netInfo?: () => NetworkInfo;
+    /** Teardown hook run by {@link TryOnClient.dispose}. The composition root
+     *  registers whatever it started (the periodic flush timer) so nothing keeps
+     *  ticking after the client is dropped — a leak in tests and in any host that
+     *  builds more than one client. */
+    onDispose?: () => void;
+}
+export interface GenerateInput {
+    /** Explicit uploaded-photo file id. */
+    userImageId?: string;
+    /** "latest": await the client's in-flight upload (if any) and use its fileId;
+     *  falls back to `userImageId` when no upload is pending. */
+    userImage?: "latest";
+    productId: string;
+    variantId?: string;
+    /** When provided, the core assembles the full TryOnResult on success and
+     *  appends it to history (returned as `result`). */
+    context?: GenerationContext;
+}
+export interface GenerateOutput {
+    imageUrl: string;
+    generationId: string;
+    /** Present when `context` was provided: the history entry the core appended. */
+    result?: TryOnResult;
+}
+/**
+ * Headless try-on domain client. Owns the entity stores (photos / generations /
+ * limits / identity), the policy layer, persistence, and funnel-event emission.
+ * Constructed on the boot side and reachable at window.Genlook.tryon; the UI
+ * bundle subscribes to the store and calls the ops.
+ */
+export declare class TryOnClient implements GenlookTryOn {
+    private readonly config;
+    private readonly transport;
+    private readonly storage;
+    private readonly track;
+    private readonly now;
+    private readonly netInfo?;
+    private readonly onDispose?;
+    private disposed;
+    private readonly store;
+    private creditsCheckCache;
+    private readonly inFlight;
+    /** The client's LATEST in-flight upload (supersede-latest). generate({ userImage:
+     *  "latest" }) awaits the newest registered upload; a superseded upload still
+     *  settles for its own awaiter but is no longer current. The store analog is
+     *  `latestPhotoId` / selectCurrentUpload. Kept after settle so a click racing
+     *  upload completion still resolves the freshest fileId; cleared when the host
+     *  discards the photo. */
+    private readonly pending;
+    /** A photo picked while legal consent was still owed. Held in memory ONLY — the
+     *  bytes never touch the network from here; `acceptLegalConsent` is the sole
+     *  release. See {@link stagePhoto}. */
+    private staged;
+    /** Lifecycle bus. Distinct from `subscribe()` (argless, level-triggered) and
+     *  from the analytics sink (whose event names are an analytics contract) —
+     *  see events.ts. */
+    private readonly events;
+    constructor(deps: TryOnClientDeps);
+    getState(): CoreState;
+    subscribe(listener: Listener): () => void;
+    /**
+     * Drain the tracker's queued events to `/events` now. The periodic timer does
+     * this on its own; call it when the host knows better — app backgrounded,
+     * screen closed, process about to exit — with `{ beacon: true }` for unload
+     * semantics. Same shape a browser host's page-hide listeners use.
+     *
+     * Never rejects; resolves immediately when the sink cannot flush (a host-owned
+     * tracker, or the no-op default).
+     */
+    flushEvents(opts?: {
+        beacon?: boolean;
+    }): Promise<void>;
+    /**
+     * Release what the composition root started for this client — today, the
+     * periodic flush timer. Idempotent. Queued events are flushed first (best
+     * effort) so a disposed client doesn't silently drop its last batch.
+     */
+    dispose(): void;
+    private buildInitialState;
+    /**
+     * Merge merchant-owned settings into live state. The SDK factory calls this
+     * when the store's `GET /settings` response lands, having already dropped the
+     * fields the integrator pinned. The client itself never fetches: the widget
+     * gets the same values inline in its config, and this is the only way in.
+     *
+     * Identity-stable when nothing moved, so a refresh that changes nothing
+     * notifies no subscriber. The policy layer is a pure function of state, so
+     * `can()` follows on its own.
+     */
+    applySettings(settings: Partial<StoreSettings>): void;
+    /** Set shopper identity. Private — the only remaining caller is collectEmail
+     *  (the UI no longer writes identity through; the core owns it). The email
+     *  transition is persisted by the usage store subscriber. */
+    private setIdentity;
+    can(action: PolicyAction): PolicyResult;
+    /** In-memory usage as the persisted shape. */
+    private usageSnapshot;
+    /**
+     * Pull in usage another core instance (second tab, bfcache-restored page) has
+     * persisted since this one last looked, merging it into state. Called right
+     * before the quota check in generate() — the enforcement point that must see
+     * everyone's consumption, not just this instance's.
+     */
+    private syncUsageFromStorage;
+    /** Record a generation against the rolling quota window + lifetime counter.
+     *  The usage store subscriber persists it. Push-then-prune matches the legacy
+     *  recordGeneration()+save() byte-for-byte. Returns the recorded window timestamp
+     *  so the caller can stamp it on the generation and refund exactly this entry on
+     *  a terminal error. The timestamp is bumped past any equal entry already in the
+     *  window OR the tombstones: it doubles as the refund identity, the merge dedupes
+     *  equal values, and an old tombstone must not kill a fresh entry. */
+    private recordUsage;
+    /** Record shopper acceptance of the legal-consent gate at `version`: persist the
+     *  storage-compatible `{ version, acceptedAt }` record, reflect it into
+     *  state.legalConsent (subscribers notified), and emit the V2-only
+     *  `tryon:legal_consent_accepted`. Re-accepting the SAME version is a no-op (no
+     *  duplicate event, no rewrite); a NEW version overwrites and emits again.
+     *  Under `config.requireLegalConsent` this is what unblocks the policy layer:
+     *  until it runs, `can("upload")` and `can("generate")` return
+     *  `consent-required`. Hosts that did not opt in are unaffected — for them
+     *  whether to show a consent screen stays a UI decision. */
+    acceptLegalConsent(version: string): void;
+    unseenResults(): GenerationJob[];
+    acknowledge(generationId: string): void;
+    /** Connectivity fields for a failure row, or nothing when the host supplies no
+     *  probe. Never throws — a broken host probe must not break the upload's own
+     *  error path. */
+    private netFields;
+    private uploadDeps;
+    private generationDeps;
+    /** Upload media (photo entity uploading→ready/failed + upload funnel events).
+     *  Registers the promise as the client's LATEST in-flight upload (supersede-
+     *  latest) so generate({ userImage: "latest" }) awaits the newest one. Upload
+     *  progress is observable from state (selectCurrentUpload) — the entity
+     *  transitions through the store, mirroring generation. PendingUpload.register
+     *  swallows the unhandled rejection of a superseded/failed upload; the caller
+     *  still receives the rejected promise.
+     *
+     *  Also the enforcement point for the upload side of the policy layer (the login
+     *  gate and, where the host opted in, the legal-consent gate): a blocked upload
+     *  is refused before any network call. Rejects instead of throwing synchronously
+     *  so a fire-and-forget caller can't blow up, and pre-catches so a voided call is
+     *  never an unhandled rejection — the awaiting caller still gets it from the
+     *  promise it was handed. */
+    uploadPhoto(file: MediaInput, meta: UploadMeta, productContext?: PrepareUploadRequest): Promise<UploadResult>;
+    /**
+     * Subscribe to a core lifecycle event. Returns an unsubscribe function.
+     *
+     * Use this instead of diffing `getState()` inside a `subscribe()` callback when
+     * what you care about is a transition ("the upload just failed") rather than a
+     * value ("the upload is failed"). Events are edges and are not replayed; state
+     * is the level and is always readable from `getState()`.
+     */
+    on<T extends CoreEventType>(type: T, listener: CoreEventListener<T>): () => void;
+    /** Subscribe to every core event, current and future. Returns an unsubscribe
+     *  function. For consumers generic over the event set (logging, bridging, dev
+     *  tooling) — see `CoreEvents.onAny`. */
+    onAny(listener: (event: CoreEvent) => void): () => void;
+    /**
+     * Stage a freshly picked photo: upload it now if legal consent is already on
+     * record, otherwise hold the bytes in memory until `acceptLegalConsent` releases
+     * them. That makes "nothing leaves the device before consent" an invariant of
+     * the core rather than a discipline each UI keeps.
+     *
+     * Uploading at pick time hides most of the wait: shoppers spend a median 2.5s on
+     * the confirm step against a median 4.5s upload, and a server-side rejection
+     * surfaces while the photo is still on screen.
+     *
+     * Returns nothing — read progress from `selectCurrentUpload(getState())`, and
+     * let `generate({ userImage: "latest" })` await the result. Supersede-latest
+     * applies to held photos too.
+     *
+     * Never throws, in either mode: while consent is outstanding the photo is held
+     * rather than refused, so the optimistic path stays available — the bytes are
+     * ready to leave the instant the shopper accepts instead of the upload starting
+     * only then. `flushStagedPhoto` is the single release and runs after the consent
+     * record exists, so the released upload passes `can("upload")`.
+     *
+     * Quota is NOT pre-checked: `can("generate")` is still evaluated by generate(),
+     * so a shopper who turns out to be over quota uploads for nothing. Cheap next to
+     * a generation, and pre-checking would skip the early upload for the
+     * `email-required` case — where it pays off most.
+     */
+    stagePhoto(file: MediaInput, meta: UploadMeta, productContext?: PrepareUploadRequest): void;
+    /** Start the upload for a photo staged before consent. No-op when nothing is
+     *  held. Called from `acceptLegalConsent` — the single release point. Stamps
+     *  `heldDurationMs` (→ held_duration_ms) so a consent-released upload is
+     *  distinguishable from an immediate one, and the gate's latency cost is a
+     *  field rather than a session join. */
+    private flushStagedPhoto;
+    /** Drop the tracked upload (host discarded the selected photo): clears the
+     *  pending-upload pointer AND the current-upload state pointer (latestPhotoId),
+     *  so selectCurrentUpload reads null. Photo entities are left in the store. */
+    clearPendingUpload(): void;
+    /** Resolve the user image for generate(): prefer the in-flight upload over the
+     *  (possibly stale) host-provided fileId. All failure paths are typed
+     *  upload_failed so the host routes back to preview. */
+    private resolveUserImageId;
+    /**
+     * Create + drive a generation to completion (generation entity + generation_start
+     * event). Awaits the in-flight upload when asked for the "latest" image, is
+     * deduped within a TTL and guarded by the policy layer. Rejects with
+     * GenerationFailedError (name+kind/code readable across the bundle boundary)
+     * or PolicyBlockedError when blocked. With `context`, appends the assembled
+     * TryOnResult to history on success.
+     */
+    generate(input: GenerateInput): Promise<GenerateOutput>;
+    getHistory(): TryOnResult[];
+    appendResult(entry: TryOnResult): void;
+    updateResult(id: string, patch: Partial<TryOnResult>): void;
+    /** Wholesale replace of the history slice (the store subscriber persists it,
+     *  subscribers are notified). Used by the staged preview's history seeding. */
+    replaceHistory(entries: TryOnResult[]): void;
+    clearHistory(): void;
+    /**
+     * Shopper "delete my data": erase the shopper's data server-side, then wipe the
+     * local shopper state (history + the tracked pending upload). Fires
+     * `tryon:data_erased` ONLY on a confirmed backend erasure; on failure the local
+     * state is still cleared (the screen empties either way) and no event fires.
+     * Never rejects — mirrors rateResult's best-effort contract, so the UI can
+     * `await` it and navigate away unconditionally.
+     */
+    deleteMyData(): Promise<void>;
+    /** Read-side retention view — stored history is never pruned. */
+    recentResults(retentionDays?: number | null): TryOnResult[];
+    /** Share URL for a history entry: short-circuits on `entry.shareUrl`, else
+     *  creates a link and writes it back into the entry (write-through cache).
+     *  DOM-derived inputs (effective domain, product URL) are passed in by the UI. */
+    getShareUrl(entryId: string, opts?: GetShareUrlOptions): Promise<string>;
+    /** Rate a history entry: rating/feedbackReason write-through, the
+     *  widget:result_rated / widget:result_rating_reason events (BQ contract),
+     *  and the backend call. Never rejects. */
+    rateResult(entryId: string, rating: 1 | -1 | 0, reason?: RatingReasonCode | null): Promise<void>;
+    getCurrentPlan(): Promise<CurrentPlanResponse>;
+    checkCredits(): Promise<CheckCreditsResponse>;
+    rateGeneration(generationId: string, rating: 1 | -1 | 0, reason?: RatingReasonCode | null): Promise<{
+        rating: number | null;
+        ratedAt: string | null;
+        ratingReason: string | null;
+    }>;
+    /**
+     * Collect email: fire the email_collected funnel event from the identity
+     * transition (unconditional), set identity, and send the backend
+     * shopper/email call.
+     */
+    collectEmail(request: CollectEmailRequest): Promise<CollectEmailResponse>;
+    createShareLink(generationId: string, effectiveDomain?: string, productUrl?: string): Promise<ShareGenerationResponse>;
+}
+export { PolicyBlockedError };