@genlook/storefront 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,226 @@
+import type { UploadRejectionReason } from "./upload";
+/**
+ * The per-reason detail a rejection carries, spread FLAT alongside the base
+ * fields. Deliberately a CLOSED set of optional keys rather than
+ * `Record<string, unknown>`: an open index signature widens `keyof` across the
+ * whole union to `string`, which silently defeats the no-PII assertion in
+ * analytics.ts and would let any field — an address included — ride along.
+ */
+interface UploadRejectionExtra {
+    /** invalid_image_type */
+    allowedTypes?: readonly string[];
+    /** file_too_large */
+    maxFileSize?: number;
+    /** invalid_dimensions */
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    /** "dimension_read_failed" when the browser could not read the image at all.
+     *  Distinct from the verdict's own `rejectionReason`. */
+    reason?: string;
+    /** invalid_dimensions_post_crop — the truncated backend message. */
+    error?: string;
+}
+/** The flat, BQ-ready projection of UploadMeta shared by `photo_submitted` and
+ *  `photo_upload_started` — one shape so the two events can't drift. A closed
+ *  interface (never an index signature): an open one would widen `keyof` and
+ *  defeat the PII check in analytics.ts. */
+export interface PhotoMetaFields {
+    fileSize: number;
+    mimeType: string;
+    uploadSource: string;
+    skipClientDimensionCheck: boolean;
+    /** The picked photo's own dimensions, when the host could read them. Carried
+     *  because shape is the question behind "does this suit me": a full-length
+     *  portrait and a square selfie are different inputs. Absent when unreadable
+     *  or not checked. */
+    width?: number;
+    height?: number;
+    /** Seconds since the file was created (`File.lastModified`) at pick time —
+     *  ~0 = taken in the chooser, large = an old roll photo. */
+    photo_age_s?: number;
+    /** `lastModified` fell inside the chooser's open→resolve window: the shopper
+     *  took the photo via the chooser's camera path rather than picking from the
+     *  roll. Host-observed (UploadMeta); absent when the host can't tell. */
+    captured_in_picker?: boolean;
+    /** Chooser open → file returned, in ms. Host-observed; absent when unknown. */
+    picker_duration_ms?: number;
+    /** The page was backgrounded while the chooser was open (Android camera path,
+     *  app switches). Host-observed; absent when unknown. */
+    picker_backgrounded?: boolean;
+    /** How long the photo waited at the consent gate before release, in ms.
+     *  Core-stamped on `flushStagedPhoto`; PRESENCE means this upload was held —
+     *  an immediate (already-consented) upload omits it. */
+    held_duration_ms?: number;
+}
+/**
+ * Everything the core announces about its own lifecycle.
+ *
+ * Discriminated on `type` so a host can switch exhaustively and the compiler
+ * catches a new member. Names are `<subject>:<past-tense>` — an event is a fact
+ * about something that already happened, never a request.
+ */
+export type CoreEvent = 
+/** A picked photo was handed to `stagePhoto` — the pipeline's entry edge,
+ *  carrying everything known about the photo and how it was acquired. `held` is
+ *  true when legal consent is still outstanding, so nothing has been sent and
+ *  nothing will be until consent is accepted. Local pick-time rejections never
+ *  reach the core, so the complete "chooser returned a file" edge is this event
+ *  ∪ the host's local-rejection event. */
+({
+    type: "tryon:photo_submitted";
+    held: boolean;
+} & PhotoMetaFields)
+/** The tracked photo was dropped (`clearPendingUpload`), in flight or still held
+ *  pre-consent. */
+ | {
+    type: "tryon:photo_discarded";
+}
+/** Bytes are now in flight (an immediate stage, or a held photo released by
+ *  consent). Always preceded by `tryon:photo_submitted`. */
+ | ({
+    type: "tryon:photo_upload_started";
+} & PhotoMetaFields)
+/** The upload chain completed. Read the cropped URL from
+ *  `selectCurrentUpload(getState())`. */
+ | {
+    type: "tryon:photo_upload_succeeded";
+    fileId: string;
+    fileSize: number;
+    mimeType: string;
+    uploadSource: string;
+    skipClientDimensionCheck: boolean;
+    duration_ms: number;
+}
+/** The upload failed for a non-verdict reason (network, prepare, storage).
+ *  Retryable with the same photo, unlike a rejection. */
+ | {
+    type: "tryon:photo_upload_failed";
+    fileSize: number;
+    mimeType: string;
+    uploadSource: string;
+    error: string;
+    kind: "upload_failed";
+    code: "UPLOAD_FAILED";
+    /** Connectivity when the failure was recorded. ~90% of these arrive as the
+     *  browser's generic "Failed to fetch" / "Load failed", which name no cause;
+     *  these separate lost signal from a backgrounded page. Absent when the host
+     *  supplies no NetworkInfo port. */
+    net_online?: boolean;
+    net_effective_type?: string;
+    net_visibility?: "visible" | "hidden";
+}
+/** The photo was refused — pre-upload validation or the server's post-crop
+ *  verdict. Terminal for this photo: the shopper must pick another. `extra` is
+ *  the per-reason detail (allowedTypes / maxFileSize / width+height+min* /
+ *  dimension_read_failed / truncated error), spread flat. */
+ | ({
+    type: "tryon:photo_upload_rejected";
+    fileSize: number;
+    mimeType: string;
+    uploadSource: string;
+    rejectionReason: UploadRejectionReason;
+    kind: "upload_rejected";
+} & UploadRejectionExtra)
+/** Legal consent was recorded. Any photo held by `stagePhoto` is released in the
+ *  same tick, so `tryon:upload_started` normally follows immediately. */
+ | {
+    type: "tryon:legal_consent_accepted";
+    consent_version: string;
+}
+/** Accepted and started (past the policy check and the dedup window, quota
+ *  counted). A repeat inside the dedup TTL does NOT re-emit. */
+ | {
+    type: "tryon:generation_started";
+    generationId: string;
+}
+/** Produced an image. The history entry (when the caller passed a `context`) is
+ *  appended before this fires. */
+ | {
+    type: "tryon:generation_succeeded";
+    generationId: string;
+    duration_ms: number;
+    productId: string;
+    variantId?: string;
+}
+/** Terminal error. `kind` is the GenerationErrorKind a host switches on; `code`
+ *  is the backend wire code. */
+ | {
+    type: "tryon:generation_failed";
+    generationId: string;
+    kind: string;
+    code: string;
+}
+/** The generate was refused before anything was spent — by the CLIENT policy
+ *  layer (reasons like "quota-exceeded" / "credits-expired" / "login-required")
+ *  or by the SERVER pre-entity, where reason is the raw wire code
+ *  (QUOTA_EXCEEDED / BILLING_NOT_ALLOWED / RATE_LIMIT_EXCEEDED /
+ *  FITTING_ROOM_WEEKLY_LIMIT_EXCEEDED). Either way nothing ran and nothing was
+ *  charged (the server path refunds the counted use). */
+ | {
+    type: "tryon:generation_blocked";
+    reason: string;
+}
+/** A result was rated. `rating` is 1 / -1, or 0 when withdrawn. */
+ | {
+    type: "tryon:result_rated";
+    generationId: string;
+    rating: number;
+    source: string;
+}
+/** A structured reason was given for a rating. */
+ | {
+    type: "tryon:result_feedback_given";
+    generationId: string;
+    reason: string;
+    source: string;
+}
+/** A share link was minted for a result. */
+ | {
+    type: "tryon:share_link_created";
+    generationId: string;
+    entryId: string;
+}
+/** An email was collected at the gate. NO ADDRESS — it reaches the backend
+ *  through `POST /shopper/email`, and a copy here would only be a second system
+ *  to secure and to honour erasure in. */
+ | {
+    type: "tryon:email_collected";
+    emailCollectionStep: number;
+    checkboxDisplayed: boolean;
+    marketingConsent?: boolean;
+}
+/** A shopper-initiated erasure completed; local state is cleared either way. */
+ | {
+    type: "tryon:data_erased";
+};
+export type CoreEventType = CoreEvent["type"];
+/** Narrow a CoreEvent to one member by its `type`, so `on("tryon:photo_upload_succeeded", e => …)`
+ *  hands the listener a payload that already knows it has `fileId`. */
+export type CoreEventOf<T extends CoreEventType> = Extract<CoreEvent, {
+    type: T;
+}>;
+export type CoreEventListener<T extends CoreEventType> = (event: CoreEventOf<T>) => void;
+/**
+ * Minimal typed emitter. No replay — events are edges, state is level, so read
+ * `getState()` for current state. A throwing listener is swallowed and does not
+ * stop the others: a host render bug must never break a try-on.
+ */
+export declare class CoreEvents {
+    private readonly listeners;
+    private readonly anyListeners;
+    /** Subscribe to one event type. Returns an unsubscribe function. */
+    on<T extends CoreEventType>(type: T, listener: CoreEventListener<T>): () => void;
+    /**
+     * Subscribe to every event, current and future — for consumers generic over the
+     * event set (logging, host bridges, dev tooling). A new member of
+     * {@link CoreEvent} then needs no change here or in them.
+     *
+     * Runs after the type-specific listeners; same no-replay guarantee as {@link on}.
+     */
+    onAny(listener: (event: CoreEvent) => void): () => void;
+    /** Announce an event to its subscribers (type-specific first, then wildcard). */
+    emit(event: CoreEvent): void;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,41 @@
+export class CoreEvents {
+    listeners = new Map();
+    anyListeners = new Set();
+    on(type, listener) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        const entry = listener;
+        set.add(entry);
+        return () => {
+            set.delete(entry);
+        };
+    }
+    onAny(listener) {
+        this.anyListeners.add(listener);
+        return () => {
+            this.anyListeners.delete(listener);
+        };
+    }
+    emit(event) {
+        const set = this.listeners.get(event.type);
+        if (set) {
+            for (const listener of [...set]) {
+                try {
+                    listener(event);
+                }
+                catch {
+                }
+            }
+        }
+        for (const listener of [...this.anyListeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+            }
+        }
+    }
+}

package/dist/fetch-transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The core's default {@link Transport}: a plain `fetch` client for callers that
+ * reach `api.genlook.app` directly with a publishable key (native apps, headless
+ * or custom storefronts). `fetch` exists natively in browsers AND React Native,
+ * so one transport covers both.
+ *
+ * Storefront plugins keep their own transport (app-proxy prefix, signed params,
+ * redirect-prefix recovery); this one is the zero-wiring path for an integrator
+ * who only holds a key.
+ */
+import type { Transport, TransportResponse } from "./ports";
+/** Default Genlook API origin. */
+export declare const GENLOOK_API_BASE_URL = "https://api.genlook.app";
+/** Default path segment the storefront endpoints are mounted under. The older
+ *  `store/v1/public` prefix is still served by the backend until 2027-03-01 and
+ *  can be passed as `apiPath` by an integration pinned to it. */
+export declare const GENLOOK_STORE_API_PATH = "storefront/v1";
+/** Init the transport hands to the host `fetch`. Structural subset of RequestInit. */
+export interface FetchLikeInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    keepalive?: boolean;
+}
+/** The host `fetch`. The browser/React Native `fetch` satisfies it structurally
+ *  (`Response` satisfies {@link TransportResponse}). */
+export type FetchLike = (url: string, init?: FetchLikeInit) => Promise<TransportResponse>;
+/** A value that may be supplied directly or resolved lazily per request. */
+type Resolvable<T> = T | (() => T);
+export interface FetchTransportOptions {
+    /** Publishable key (`pk_…`), sent as `Authorization: Bearer …`. */
+    publishableKey: string;
+    /** API origin. Default {@link GENLOOK_API_BASE_URL}. */
+    baseUrl?: string;
+    /** Path the public endpoints live under. Default {@link GENLOOK_STORE_API_PATH}. */
+    apiPath?: string;
+    /** Anonymous device id → `x-genlook-anonymous-id`. Lazy form supported so the
+     *  transport can be built before storage hydration resolves. */
+    anonymousId?: Resolvable<string | null | undefined>;
+    /** Known shopper → `x-genlook-customer-id`. */
+    customerId?: Resolvable<string | null | undefined>;
+    /** Known shopper email → `x-genlook-customer-email`. */
+    customerEmail?: Resolvable<string | null | undefined>;
+    /** Client build id → `x-genlook-widget-version`. */
+    widgetVersion?: string;
+    /** Extra headers on every proxied request (never on `putRaw`). Also the way
+     *  to relabel the channel: a host that embeds this transport under its own
+     *  name overrides `x-genlook-integration` / `x-genlook-integration-version`
+     *  here. */
+    headers?: Record<string, string>;
+    /** Device fingerprint, read only when a request sets `includeFingerprint`. */
+    getFingerprint?: () => string | null | undefined;
+    /** Override the host `fetch` (tests, custom agents). Default `globalThis.fetch`. */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Build the default fetch transport.
+ *
+ * `fetch(path, init)` hits `{baseUrl}/{apiPath}/{path}` with the publishable key
+ * and the identity headers. `putRaw(url, body, headers)` PUTs bytes to an
+ * absolute signed storage URL and deliberately carries NO Genlook headers — the
+ * GCS signed-URL contract breaks if extra headers are signed in.
+ */
+export declare function createFetchTransport(options: FetchTransportOptions): Transport;
+export {};

package/dist/fetch-transport.js

@@ -0,0 +1,112 @@
+import { SDK_VERSION } from "./version";
+export const GENLOOK_API_BASE_URL = "https://api.genlook.app";
+export const GENLOOK_STORE_API_PATH = "storefront/v1";
+function syntheticResponse(statusText) {
+    return {
+        ok: true,
+        status: 0,
+        statusText,
+        json: async () => ({}),
+        text: async () => "",
+    };
+}
+function resolve(value) {
+    return typeof value === "function" ? value() : value;
+}
+function joinUrl(base, path) {
+    if (!path)
+        return base;
+    const left = base.endsWith("/") ? base.slice(0, -1) : base;
+    const right = path.startsWith("/") ? path.slice(1) : path;
+    return `${left}/${right}`;
+}
+function getFetch(override) {
+    if (override)
+        return override;
+    const f = globalThis.fetch;
+    return typeof f === "function" ? f.bind(globalThis) : undefined;
+}
+function getSendBeacon() {
+    const nav = globalThis.navigator;
+    return nav && typeof nav.sendBeacon === "function"
+        ? nav.sendBeacon.bind(nav)
+        : undefined;
+}
+function beaconPayload(body, contentType) {
+    const BlobCtor = globalThis.Blob;
+    return BlobCtor ? new BlobCtor([body], { type: contentType }) : body;
+}
+export function createFetchTransport(options) {
+    const base = joinUrl(options.baseUrl ?? GENLOOK_API_BASE_URL, options.apiPath ?? GENLOOK_STORE_API_PATH);
+    const doFetch = (url, init) => {
+        const impl = getFetch(options.fetchImpl);
+        if (!impl) {
+            return Promise.reject(new Error("[Genlook] No fetch implementation available in this runtime."));
+        }
+        return impl(url, init);
+    };
+    const buildHeaders = (init) => {
+        const headers = {
+            "x-genlook-integration": "tryon_core",
+            "x-genlook-integration-version": SDK_VERSION,
+            ...options.headers,
+            ...init?.headers,
+            Authorization: `Bearer ${options.publishableKey}`,
+        };
+        const anonymousId = resolve(options.anonymousId);
+        if (anonymousId)
+            headers["x-genlook-anonymous-id"] = anonymousId;
+        const customerId = resolve(options.customerId);
+        if (customerId)
+            headers["x-genlook-customer-id"] = customerId;
+        const customerEmail = resolve(options.customerEmail);
+        if (customerEmail)
+            headers["x-genlook-customer-email"] = customerEmail;
+        if (options.widgetVersion) {
+            headers["x-genlook-widget-version"] = options.widgetVersion;
+        }
+        if (init?.includeFingerprint) {
+            const fingerprint = options.getFingerprint?.();
+            if (fingerprint)
+                headers["x-genlook-fingerprint"] = fingerprint;
+        }
+        return headers;
+    };
+    return {
+        fetch(path, init) {
+            const url = joinUrl(base, path);
+            const headers = buildHeaders(init);
+            if (init?.beacon) {
+                const body = init.body ?? "";
+                const send = getSendBeacon();
+                if (send) {
+                    const contentType = headers["Content-Type"] ?? "application/json";
+                    try {
+                        if (send(url, beaconPayload(body, contentType))) {
+                            return Promise.resolve(syntheticResponse("beacon"));
+                        }
+                    }
+                    catch {
+                    }
+                }
+                if (!getFetch(options.fetchImpl)) {
+                    return Promise.resolve(syntheticResponse("beacon-unsupported"));
+                }
+                return doFetch(url, {
+                    method: init.method ?? "POST",
+                    headers,
+                    body: init.body,
+                    keepalive: true,
+                });
+            }
+            return doFetch(url, {
+                method: init?.method,
+                headers,
+                body: init?.body,
+            });
+        },
+        putRaw(url, body, headers) {
+            return doFetch(url, { method: "PUT", headers, body });
+        },
+    };
+}

package/dist/generation.d.ts

@@ -0,0 +1,132 @@
+import type { Transport } from "./ports";
+import type { FittingRoomRequest, FittingRoomResponse, GenerationStatusResponse, CurrentPlanResponse, CheckCreditsResponse, RatingReasonCode } from "./types";
+import type { Store } from "./store";
+import type { CoreState, GenerationJob, GenError } from "./entities";
+/** Failure category the host UI routes on. Derived from the backend's
+ *  structured codes, never from message text (see classifyErrorKind). */
+export type GenerationErrorKind = "quota" | "weekly_limit" | "rate_limited" | "overloaded" | "creation_failed" | "upload_failed" | "failed";
+/**
+ * Derive the error kind from the backend's structured code. The message-text
+ * sniff at the bottom is the ONLY message-based classification left in the
+ * codebase: it handles Vertex capacity errors predating structured codes
+ * (`out of capacity` / RESOURCE_EXHAUSTED+429 with no errorCode). Everything
+ * else switches on codes.
+ */
+export declare function classifyErrorKind(code: string, message: string): GenerationErrorKind;
+/**
+ * Thrown for every generation failure: backend failure codes on job creation,
+ * a FAILED poll status, polling timeouts, and upload coordination failures.
+ * `code` is the backend's stable wire code (e.g. GENERATION_FAILED,
+ * MISSING_REQUIRED_CLASSIFICATION); `kind` is the routing category derived from
+ * it; `message` is backend text for logs only and must never be rendered.
+ *
+ * CROSS-BUNDLE CONTRACT: the error crosses the boot/UI bundle boundary, so
+ * hosts recognise it by `error.name === "GenerationFailedError"` and read
+ * `kind`/`code` off the object — never `instanceof` (which would not match a
+ * separately bundled copy of this class).
+ *
+ * Defined here (the module that throws it, matching the pre-split layout) rather
+ * than a sibling module, so this file carries NO runtime value import — the
+ * repo's strip-only `node --test` cannot resolve extensionless sibling imports,
+ * and `.ts` extensions in source break the `tsc` build (TS5097).
+ */
+export declare class GenerationFailedError extends Error {
+    readonly code: string;
+    readonly kind: GenerationErrorKind;
+    constructor(code: string, message: string, kind?: GenerationErrorKind);
+}
+export declare function createFittingRoomJob(transport: Transport, request: FittingRoomRequest): Promise<FittingRoomResponse>;
+export declare function getGenerationStatus(transport: Transport, jobId: string): Promise<GenerationStatusResponse>;
+export declare function pollGenerationStatus(transport: Transport, jobId: string, onStatusChange?: (status: GenerationStatusResponse) => void, pollInterval?: number, maxAttempts?: number): Promise<GenerationStatusResponse>;
+export declare function getCurrentPlan(transport: Transport): Promise<CurrentPlanResponse>;
+export declare function checkCredits(transport: Transport): Promise<CheckCreditsResponse>;
+export declare function rateGeneration(transport: Transport, generationId: string, rating: 1 | -1 | 0, reason?: RatingReasonCode | null): Promise<{
+    rating: number | null;
+    ratedAt: string | null;
+    ratingReason: string | null;
+}>;
+export interface RateEngineDeps {
+    transport: Transport;
+    store: Store<CoreState>;
+    /** Emits widget:result_rated (bound to analytics by the client). */
+    emitResultRated: (generationId: string, rating: 1 | -1 | 0) => void;
+    /** Emits widget:result_rating_reason (bound to analytics by the client). */
+    emitResultRatingReason: (generationId: string, reason: RatingReasonCode) => void;
+}
+/**
+ * Rate a history entry. Without a reason: optimistic rating write-through
+ * (clearing any previous reason), emit, send — and revert the rating if the
+ * backend rejects. With a reason (thumbs-down follow-up): write the reason
+ * through, emit, send. Never throws — backend failures are logged.
+ */
+export declare function rateResult(deps: RateEngineDeps, entryId: string, rating: 1 | -1 | 0, reason?: RatingReasonCode | null): Promise<void>;
+export interface GenerationEngineDeps {
+    transport: Transport;
+    store: Store<CoreState>;
+    now: () => number;
+    /** Emits the generation_start pair (bound to analytics by the client; spied in tests). */
+    emitGenerationStart: (generationId: string) => void;
+    /** Emits tryon:generation_succeeded on the done transition. */
+    emitGenerationSucceeded: (input: {
+        generationId: string;
+        durationMs: number;
+        productId: string;
+        variantId?: string;
+    }) => void;
+    /** Emits tryon:generation_failed on the error transition. */
+    emitGenerationFailed: (input: {
+        generationId: string;
+        kind: string;
+        code: string;
+    }) => void;
+    /** Pre-entity server policy denial (see blockedReasonFor) — the server-side
+     *  twin of the client policy layer's tryon:generation_blocked. */
+    emitGenerationBlocked: (reason: string) => void;
+    pollInterval?: number;
+    maxAttempts?: number;
+}
+export interface GenerationInput {
+    userImageId: string;
+    productId: string;
+    variantId?: string;
+    /** The quota-window timestamp the client counted for this generation on
+     *  acceptance (client.recordUsage()'s return value). Stamped onto the job entity
+     *  so a terminal-error refund removes exactly this entry; also used for the
+     *  bare pre-entity refund when the backend rejects job creation. */
+    usageAt?: number;
+}
+/** Entity-level error classification. Navigation is owned by the host's switch
+ *  on the rethrown error's `kind`; this only tags the store entity. Switches on
+ *  the typed error's kind/code — never on message text. */
+export declare function classifyGenerationError(err: unknown): GenError;
+/**
+ * Create a generation job and drive it to a terminal state, updating the store
+ * on every transition. Fires widget:generation_start on the requested→generating
+ * boundary. Throws the typed generation errors a host's error→navigation switch
+ * branches on; the store also records a typed error entity.
+ */
+export declare function runGeneration(deps: GenerationEngineDeps, input: GenerationInput): Promise<{
+    imageUrl: string;
+    generationId: string;
+}>;
+/**
+ * Resume a rehydrated non-terminal job: fire the start event if it was never
+ * reported (crash-before-flush), poll to a terminal state, update the store.
+ * Never throws — resumption is a background continuation.
+ */
+export declare function resumeGeneration(deps: GenerationEngineDeps, generationId: string): Promise<void>;
+/** Mark a completed result as seen (host called acknowledge). */
+export declare function acknowledgeGeneration(store: Store<CoreState>, generationId: string): void;
+/**
+ * Schedule resumption of rehydrated in-flight jobs on the NEXT microtask rather
+ * than synchronously in the client constructor.
+ *
+ * Contract: a composition root (boot.ts — and the Woo/Presta boots, where NO
+ * pre-boot stub exists at all) finishes publishing the global runtime SYNCHRONOUSLY
+ * AFTER `new TryOnClient(...)` returns. The resume fetch derefs that global's
+ * transport (cabinFetch → window.Genlook.cabin.http.fetch), so resuming inline in
+ * the ctor would deref a not-yet-published global and mark every
+ * refresh-mid-generation job errored. One microtask hop guarantees the transport
+ * deps are live before the first status poll fires.
+ */
+export declare function scheduleInFlightResumes(deps: GenerationEngineDeps, jobs: GenerationJob[]): void;