@genlook/storefront 0.1.0

package/dist/tracker.js

@@ -0,0 +1,229 @@
+export const FLUSH_INTERVAL_MS = 5000;
+function isFetchErrorResponse(v) {
+    return (!!v &&
+        typeof v.status === "number" &&
+        typeof v.text === "function");
+}
+export class Tracker {
+    queue = [];
+    pageviewId;
+    lastPathname;
+    isFlushing = false;
+    isBot;
+    consentSnapshot = null;
+    consentSubscribed = false;
+    uiVariant = null;
+    uiBuild = null;
+    widgetScopeConsent = false;
+    fallbackAnonymousId = null;
+    fallbackSessionId = null;
+    transport;
+    consent;
+    pageContext;
+    uuid;
+    now;
+    static MAX_QUEUE_SIZE = 100;
+    static EARLY_FLUSH_SIZE = 20;
+    constructor(deps) {
+        this.transport = deps.transport;
+        this.consent = deps.consent;
+        this.pageContext = deps.pageContext;
+        this.uuid = deps.uuid;
+        this.now = deps.now ?? Date.now;
+        this.pageviewId = this.uuid();
+        this.lastPathname = this.pageContext.getPathname();
+        this.isBot = this.pageContext.isBot();
+    }
+    setUiVariant(variant) {
+        this.uiVariant = variant;
+    }
+    setUiBuild(build) {
+        this.uiBuild = build;
+    }
+    static WIDGET_SCOPE_PREFIXES = ["widget:", "tryon:", "sheet:", "api:"];
+    isTrackingAllowed() {
+        this.ensureConsentSubscribed();
+        return this.consentSnapshot?.analytics_allowed !== false;
+    }
+    grantWidgetScopeConsent() {
+        this.widgetScopeConsent = true;
+    }
+    isEventAllowed(event) {
+        if (this.isTrackingAllowed())
+            return true;
+        if (!this.widgetScopeConsent)
+            return false;
+        return Tracker.WIDGET_SCOPE_PREFIXES.some((p) => event.startsWith(p));
+    }
+    capture(event, properties) {
+        if (this.isBot)
+            return;
+        if (!this.isEventAllowed(event))
+            return;
+        try {
+            this.enqueue({
+                event,
+                properties: properties || {},
+                timestamp: new Date(this.now()).toISOString(),
+                $insert_id: this.uuid(),
+            });
+        }
+        catch (error) {
+            console.error("[Genlook] Failed to capture event:", error);
+        }
+    }
+    async captureFetchError(url, method, error) {
+        try {
+            if (url.includes("/tracking/event"))
+                return;
+            const props = {
+                error_url: url,
+                error_method: method,
+            };
+            if (isFetchErrorResponse(error)) {
+                props.error_status = error.status;
+                props.error_message = `${method} ${url} failed with status ${error.status}`;
+                props.error_response_body = (await error.text()).slice(0, 10000);
+                const headers = {};
+                error.headers.forEach((v, k) => { headers[k] = v; });
+                props.error_response_headers = headers;
+            }
+            else if (error instanceof Error) {
+                props.error_message = error.message;
+            }
+            this.capture("api:error", props);
+        }
+        catch (err) {
+            console.error("[Genlook] Failed to capture fetch error:", err);
+        }
+    }
+    async flush(opts) {
+        if (this.isBot) {
+            this.queue = [];
+            return;
+        }
+        if (this.queue.length === 0)
+            return;
+        const beacon = opts?.beacon === true;
+        if (!beacon && this.isFlushing)
+            return;
+        if (!beacon)
+            this.isFlushing = true;
+        const context = this.buildContext();
+        const events = [...this.queue];
+        this.queue = [];
+        try {
+            const body = JSON.stringify({ events, context });
+            await this.transport.fetch("/events", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+                beacon,
+            });
+        }
+        catch (error) {
+            this.queue = events.concat(this.queue).slice(-Tracker.MAX_QUEUE_SIZE);
+            console.error("[Genlook] Flush failed:", error);
+        }
+        finally {
+            if (!beacon)
+                this.isFlushing = false;
+        }
+    }
+    enqueue(event) {
+        if (this.queue.length >= Tracker.MAX_QUEUE_SIZE)
+            this.queue.shift();
+        this.queue.push(event);
+        if (this.queue.length >= Tracker.EARLY_FLUSH_SIZE)
+            this.flush().catch(() => { });
+    }
+    ensureConsentSubscribed() {
+        if (this.consentSubscribed)
+            return;
+        this.consentSubscribed = true;
+        try {
+            this.consentSnapshot = this.consent.getSnapshot();
+            this.consent.onChange((snapshot) => {
+                this.consentSnapshot = snapshot;
+                this.handleConsentChange(snapshot);
+            });
+        }
+        catch { }
+    }
+    handleConsentChange(snapshot) {
+        if (snapshot?.analytics !== "no")
+            return;
+        this.pageContext.purgeTrackingStorage();
+        this.pageContext.resetSessionId();
+    }
+    buildContext() {
+        const base = this.pageContext.getBaseContext();
+        if (base.$pathname !== this.lastPathname) {
+            this.pageviewId = this.uuid();
+            this.lastPathname = base.$pathname;
+        }
+        const context = {
+            $current_url: base.$current_url,
+            $pathname: base.$pathname,
+            $host: base.$host,
+            $screen_width: base.$screen_width,
+            $screen_height: base.$screen_height,
+            $viewport_width: base.$viewport_width,
+            $viewport_height: base.$viewport_height,
+            $raw_user_agent: base.$raw_user_agent,
+            $browser_language: base.$browser_language,
+            $timezone: base.$timezone,
+            $pageview_id: this.pageviewId,
+            widget_enabled: base.widget_enabled,
+            platform: base.platform,
+            store_id: base.store_id,
+            product_id: base.product_id,
+            variant_id: base.variant_id,
+            widget_version: base.widget_version,
+            app_version: base.app_version ?? null,
+            page_type: base.page_type,
+            collection_id: base.collection_id,
+            integration: base.integration ?? null,
+            integration_version: base.integration_version ?? null,
+            consent: this.consentSnapshot,
+            ui_variant: this.uiVariant,
+            ui_version: this.uiBuild,
+        };
+        const id = this.readIdentityContext();
+        context.$referrer = id.$referrer;
+        context.$referring_domain = id.$referring_domain;
+        context.session_id = id.session_id;
+        context.anonymous_id = id.anonymous_id;
+        context.first_touch = id.first_touch;
+        return context;
+    }
+    readIdentityContext() {
+        try {
+            const id = this.pageContext.getIdentityContext();
+            return {
+                ...id,
+                anonymous_id: id.anonymous_id || this.getFallbackAnonymousId(),
+                session_id: id.session_id || this.getFallbackSessionId(),
+            };
+        }
+        catch {
+            return {
+                $referrer: null,
+                $referring_domain: null,
+                session_id: this.getFallbackSessionId(),
+                anonymous_id: this.getFallbackAnonymousId(),
+                first_touch: null,
+            };
+        }
+    }
+    getFallbackAnonymousId() {
+        if (this.fallbackAnonymousId === null)
+            this.fallbackAnonymousId = `anon_${this.uuid()}`;
+        return this.fallbackAnonymousId;
+    }
+    getFallbackSessionId() {
+        if (this.fallbackSessionId === null)
+            this.fallbackSessionId = `sess_${this.uuid()}`;
+        return this.fallbackSessionId;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+export interface FittingRoomRequest {
+    userImageId: string;
+    /** Shopify Admin GraphQL product GID (normalised from storefront numeric id at send time). */
+    productId: string;
+    /** Shopify Admin GraphQL variant GID (optional; normalised at send time). */
+    variantId?: string;
+}
+export interface FittingRoomResponse {
+    jobId: string;
+    message: string;
+    code?: "BILLING_NOT_ALLOWED" | "QUOTA_EXCEEDED" | "RATE_LIMIT_EXCEEDED" | "CREATION_FAILED";
+}
+export interface GenerationStatusResponse {
+    generationId: string;
+    status: "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+    resultImageKey?: string;
+    resultImageUrl?: string;
+    errorMessage?: string;
+    errorCode?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CurrentPlanResponse {
+    plan: "free" | "starter" | "growth" | "pro" | "enterprise";
+}
+export interface CheckCreditsResponse {
+    allowed: boolean;
+}
+export interface CollectEmailRequest {
+    email: string;
+    emailCollectionStep: number;
+    marketingConsent?: boolean;
+    checkboxDisplayed?: boolean;
+    /** Version tag of the consent copy the shopper agreed to (GDPR evidence). */
+    marketingConsentWording?: string;
+}
+export interface CollectEmailResponse {
+    success: boolean;
+    message: string;
+}
+export interface ShareGenerationResponse {
+    shareToken: string;
+    shareUrl: string;
+    expiresAt: string;
+}
+export interface UploadResult {
+    fileId: string;
+    fileUrl: string;
+    imageWidth?: number;
+    imageHeight?: number;
+}
+export interface PrepareUploadRequest {
+    productId?: string;
+    variantId?: string;
+}
+export interface PrepareUploadResponse {
+    uploadUrl: string;
+    uploadKey: string;
+}
+export interface UploadCompleteResponse {
+    fileId: string;
+    fileUrl: string;
+    message: string;
+}
+/** Closed set of reason codes paired with a thumbs-down rating. Mirrors the
+ *  backend's reason-code enum so downstream analytics stay clean. */
+export type RatingReasonCode = "distorted_body" | "wrong_fit" | "face_changed" | "wrong_colors" | "something_else";
+/**
+ * Standardized consent-state snapshot attached to every tracking batch, and the
+ * source of the tracker's binary consent gate. Platform-neutral by design: `source`
+ * names the origin ("platform-default", "shopify", ...), `available` says
+ * whether a real CMP answered, the raw `analytics`/`marketing`/`preferences`/
+ * `sale_of_data` strings carry the CMP's own vocabulary ('yes'/'no'/''), and the
+ * `_allowed` booleans carry a resolved verdict. Any field a platform can't
+ * resolve is null. Canonical home is here (headless core); a host runtime may
+ * re-export it so platform adapters can import it from there.
+ */
+export interface ConsentSnapshot {
+    source: string;
+    available: boolean;
+    analytics: string | null;
+    marketing: string | null;
+    preferences: string | null;
+    sale_of_data: string | null;
+    analytics_allowed: boolean | null;
+    marketing_allowed: boolean | null;
+    preferences_allowed: boolean | null;
+    sale_of_data_allowed: boolean | null;
+    should_show_banner: boolean | null;
+    region: string | null;
+}

package/dist/types.js

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

package/dist/upload.d.ts

@@ -0,0 +1,123 @@
+import type { Transport, MediaInput } from "./ports";
+import type { PrepareUploadRequest, UploadResult } from "./types";
+import type { Store } from "./store";
+import type { CoreState, UploadMeta, UploadDimensions } from "./entities";
+/** Max accepted upload size (bytes). */
+export declare const MAX_UPLOAD_BYTES: number;
+/** Accepted image MIME types (HEIC-by-extension is accepted separately). */
+export declare const ALLOWED_UPLOAD_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/webp", "image/heic", "image/heif"];
+/** Minimum accepted client-read dimensions (below → invalid_dimensions). */
+export declare const MIN_UPLOAD_WIDTH = 500;
+export declare const MIN_UPLOAD_HEIGHT = 625;
+/** True for a HEIC/HEIF file: recognised MIME set OR a .heic/.heif extension.
+ *  Call it with `mimeType ← file.type` and `fileName ← file.name`; fileName is
+ *  optional, and when absent only the MIME set is consulted. */
+export declare function isHeicLike(mimeType: string, fileName?: string): boolean;
+/** Closed set of rejection reasons. Pre-upload verdicts + the post-crop verdict
+ *  classified from the backend's structured code. The UI switches on this to pick
+ *  its localized copy; the rejection event carries it as `rejectionReason`. */
+export type UploadRejectionReason = "invalid_image_type" | "file_too_large" | "invalid_dimensions" | "invalid_dimensions_post_crop";
+/** Pure-validation input. `fileName`/`dimensions` are optional — an older host
+ *  that predates core-side validation omits them and the core skips the checks it
+ *  cannot perform (backward tolerant) rather than throwing. */
+export interface UploadValidationInput {
+    fileSize: number;
+    mimeType: string;
+    fileName?: string;
+    dimensions?: UploadDimensions;
+}
+/** Pre-upload verdict. `extra` carries the per-reason event metadata the host used
+ *  to attach inline (allowedTypes / maxFileSize / dimension fields), preserved
+ *  byte-for-byte so the rejection event payload is unchanged. */
+export type UploadVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: UploadRejectionReason;
+    extra: Record<string, unknown>;
+};
+/**
+ * Pre-upload validation. Decision order and reasons:
+ *   1. invalid_image_type — non-allowed MIME AND not HEIC-like.
+ *   2. file_too_large     — over MAX_UPLOAD_BYTES.
+ *   3. invalid_dimensions — "unreadable", or width/height below the minimums.
+ * The dimension check is skipped when `dimensions` is "skipped" (HEIC-like) or
+ * absent (older host). Pure — never throws; the caller emits + throws.
+ */
+export declare function validateUpload(input: UploadValidationInput): UploadVerdict;
+/**
+ * CROSS-BUNDLE CONTRACT: recognised by `error.name === "UploadRejectedError"` +
+ * the `reason` field read off the object — never `instanceof` (which would not
+ * match a separately bundled copy of this class), same pattern as
+ * GenerationFailedError. Carries the per-reason event `extra` so the host never
+ * recomputes it. Colocated here (the module that throws it) so this file keeps NO
+ * runtime sibling value import and loads under the strip-only `node --test`.
+ */
+export declare class UploadRejectedError extends Error {
+    readonly reason: UploadRejectionReason;
+    readonly extra: Record<string, unknown>;
+    constructor(reason: UploadRejectionReason, message: string, extra?: Record<string, unknown>);
+}
+/**
+ * Transport-level HTTP failure from a backend endpoint (/uploads,
+ * /uploads/:key/complete) that answers with the structured `{ code, message, status }`
+ * ApiErrorBody. Carries the parsed `code` next to the flattened `message`.
+ * CROSS-BUNDLE CONTRACT: consumers (classifyUploadFailure via runUpload) MUST
+ * recognise the structured code by the DUCK-TYPED `code` field read off the
+ * object — never `instanceof` (a separately bundled transport may throw its own
+ * object carrying a `code` field, which would not match this class). `code` is
+ * undefined when the error body did not JSON-parse to an object with a string
+ * `code`. NOT exported from src/index.ts — the duck-typed field is the contract.
+ */
+export declare class UploadHttpError extends Error {
+    readonly code?: string;
+    readonly status: number;
+    constructor(message: string, status: number, code?: string);
+}
+/**
+ * Post-crop rejection classifier. The backend rejects a low-resolution-after-crop
+ * upload from /uploads/:key/complete with a structured `code: "INVALID_IMAGE"` in the
+ * response body (ApiException → HttpException, whose object body is passed through
+ * unchanged by the global BaseExceptionFilter). `uploadPhoto` parses that JSON
+ * body and surfaces the `code` on the thrown UploadHttpError, so the structured
+ * `code` is now the PRIMARY signal: `code === "INVALID_IMAGE"` → post-crop
+ * rejection. A non-matching (foreign) code falls THROUGH to the message check
+ * rather than returning null — an older host may pass garbage in `code`. The
+ * message-token match ("INVALID_IMAGE" token OR the legacy `resolution is too
+ * low` prose) survives ONLY as a fallback for errors produced by older bundled
+ * transports / cached boot bundles that still flatten the structured body into
+ * the message without surfacing `code`.
+ */
+export declare function classifyUploadFailure(message: string, code?: string): UploadRejectionReason | null;
+/**
+ * Upload user media via the 3-step signed-URL flow:
+ * 1. POST /uploads                  → GCS signed write URL + uploadKey
+ * 2. PUT  raw bytes to GCS          → direct upload, NO Genlook identity headers
+ * 3. POST /uploads/:key/complete    → backend crops and returns the final fileId + fileUrl
+ *
+ * The chain is synchronous and step 3 returns the cropped image — the widget
+ * chains generation immediately, so this must NOT be offloaded to a queue.
+ */
+export declare function uploadPhoto(transport: Transport, file: MediaInput, productContext?: PrepareUploadRequest): Promise<UploadResult>;
+export interface UploadEngineDeps {
+    transport: Transport;
+    store: Store<CoreState>;
+    now: () => number;
+    emitImageUpload: (meta: UploadMeta) => void;
+    emitImageUploadSuccess: (meta: UploadMeta, fileId: string, uploadDurationMs: number) => void;
+    emitImageUploadError: (meta: UploadMeta, error: string) => void;
+    /** Emits the image_upload_rejected pair (bound to analytics by the client). One
+     *  emission point for pre-upload verdicts and the post-crop classification. */
+    emitImageUploadRejected: (meta: UploadMeta, reason: UploadRejectionReason, extra: Record<string, unknown>) => void;
+}
+/**
+ * Drive a photo through uploading→ready/failed while firing the upload funnel
+ * events from the transitions. Runs pre-upload validation from the meta BEFORE any
+ * network call: on a verdict it emits the image_upload_rejected pair and throws a
+ * typed UploadRejectedError (no photo entity, no upload_started event). The
+ * prepare→PUT→complete chain stays synchronous and `ready` carries the cropped
+ * result. On failure it classifies a post-crop rejection (structured
+ * INVALID_IMAGE) → image_upload_rejected + typed error; any other failure fires
+ * image_upload_error and rethrows, so the host's error routing is unchanged.
+ */
+export declare function runUpload(deps: UploadEngineDeps, file: MediaInput, meta: UploadMeta, productContext?: PrepareUploadRequest): Promise<UploadResult>;

package/dist/upload.js

@@ -0,0 +1,176 @@
+export const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+export const ALLOWED_UPLOAD_MIME_TYPES = [
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/heic",
+    "image/heif",
+];
+export const MIN_UPLOAD_WIDTH = 500;
+export const MIN_UPLOAD_HEIGHT = 625;
+const HEIC_MIME_TYPES = new Set(["image/heic", "image/heif"]);
+const HEIC_EXTENSION_RE = /\.(heic|heif)$/i;
+export function isHeicLike(mimeType, fileName) {
+    if (HEIC_MIME_TYPES.has(mimeType))
+        return true;
+    return fileName ? HEIC_EXTENSION_RE.test(fileName) : false;
+}
+export function validateUpload(input) {
+    const { fileSize, mimeType, fileName, dimensions } = input;
+    const allowed = ALLOWED_UPLOAD_MIME_TYPES.includes(mimeType);
+    if (!allowed && !isHeicLike(mimeType, fileName)) {
+        return {
+            ok: false,
+            reason: "invalid_image_type",
+            extra: { allowedTypes: [...ALLOWED_UPLOAD_MIME_TYPES] },
+        };
+    }
+    if (fileSize > MAX_UPLOAD_BYTES) {
+        return { ok: false, reason: "file_too_large", extra: { maxFileSize: MAX_UPLOAD_BYTES } };
+    }
+    if (dimensions && dimensions !== "skipped") {
+        if (dimensions === "unreadable") {
+            return {
+                ok: false,
+                reason: "invalid_dimensions",
+                extra: {
+                    reason: "dimension_read_failed",
+                    minWidth: MIN_UPLOAD_WIDTH,
+                    minHeight: MIN_UPLOAD_HEIGHT,
+                },
+            };
+        }
+        if (dimensions.width < MIN_UPLOAD_WIDTH || dimensions.height < MIN_UPLOAD_HEIGHT) {
+            return {
+                ok: false,
+                reason: "invalid_dimensions",
+                extra: {
+                    width: dimensions.width,
+                    height: dimensions.height,
+                    minWidth: MIN_UPLOAD_WIDTH,
+                    minHeight: MIN_UPLOAD_HEIGHT,
+                },
+            };
+        }
+    }
+    return { ok: true };
+}
+export class UploadRejectedError extends Error {
+    reason;
+    extra;
+    constructor(reason, message, extra = {}) {
+        super(message);
+        this.name = "UploadRejectedError";
+        this.reason = reason;
+        this.extra = extra;
+    }
+}
+export class UploadHttpError extends Error {
+    code;
+    status;
+    constructor(message, status, code) {
+        super(message);
+        this.name = "UploadHttpError";
+        this.status = status;
+        this.code = code;
+    }
+}
+function uploadHttpError(label, status, statusText, text) {
+    let code;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && typeof parsed.code === "string") {
+            code = parsed.code;
+        }
+    }
+    catch {
+    }
+    return new UploadHttpError(`${label}: ${status} ${statusText}. ${text}`, status, code);
+}
+export function classifyUploadFailure(message, code) {
+    if (code === "INVALID_IMAGE") {
+        return "invalid_dimensions_post_crop";
+    }
+    if (message.includes("INVALID_IMAGE") || message.includes("resolution is too low")) {
+        return "invalid_dimensions_post_crop";
+    }
+    return null;
+}
+export async function uploadPhoto(transport, file, productContext) {
+    const prepareRes = await transport.fetch("/uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(productContext ?? {}),
+    });
+    if (!prepareRes.ok) {
+        const text = await prepareRes.text();
+        throw uploadHttpError("Prepare upload failed", prepareRes.status, prepareRes.statusText, text);
+    }
+    const { uploadUrl, uploadKey } = (await prepareRes.json());
+    console.log("Prepared upload, key:", uploadKey);
+    const putRes = await transport.putRaw(uploadUrl, file, { "Content-Type": "application/octet-stream" });
+    if (!putRes.ok) {
+        const text = await putRes.text();
+        throw new Error(`Direct upload to storage failed: ${putRes.status} ${putRes.statusText}. ${text}`);
+    }
+    console.log("Direct upload complete for key:", uploadKey);
+    const completeRes = await transport.fetch(`/uploads/${encodeURIComponent(uploadKey)}/complete`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+        includeFingerprint: true,
+    });
+    if (!completeRes.ok) {
+        const text = await completeRes.text();
+        throw uploadHttpError("Upload complete failed", completeRes.status, completeRes.statusText, text);
+    }
+    const result = (await completeRes.json());
+    console.log("Upload processed:", result);
+    return { fileId: result.fileId, fileUrl: result.fileUrl };
+}
+function setPhoto(store, photo) {
+    store.setState((s) => ({ ...s, photos: { ...s.photos, [photo.id]: photo } }));
+}
+function beginUpload(store, photo) {
+    store.setState((s) => ({
+        ...s,
+        photos: { ...s.photos, [photo.id]: photo },
+        latestPhotoId: photo.id,
+    }));
+}
+export async function runUpload(deps, file, meta, productContext) {
+    const verdict = validateUpload({
+        fileSize: meta.fileSize,
+        mimeType: meta.mimeType,
+        fileName: meta.fileName,
+        dimensions: meta.dimensions,
+    });
+    if (!verdict.ok) {
+        deps.emitImageUploadRejected(meta, verdict.reason, verdict.extra);
+        throw new UploadRejectedError(verdict.reason, `Upload rejected: ${verdict.reason}`, verdict.extra);
+    }
+    const id = `p${deps.now()}-${Math.floor(Math.random() * 1e9)}`;
+    const createdAt = deps.now();
+    beginUpload(deps.store, { id, status: "uploading", progress: 0, createdAt });
+    deps.emitImageUpload(meta);
+    const start = deps.now();
+    try {
+        const result = await uploadPhoto(deps.transport, file, productContext);
+        setPhoto(deps.store, { id, status: "ready", result, createdAt });
+        deps.emitImageUploadSuccess(meta, result.fileId, deps.now() - start);
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        setPhoto(deps.store, { id, status: "failed", error: message, createdAt });
+        const code = err && typeof err.code === "string" ? err.code : undefined;
+        const postCropReason = classifyUploadFailure(message, code);
+        if (postCropReason) {
+            const extra = { error: message.substring(0, 500) };
+            deps.emitImageUploadRejected(meta, postCropReason, extra);
+            throw new UploadRejectedError(postCropReason, message, extra);
+        }
+        deps.emitImageUploadError(meta, message);
+        throw err;
+    }
+}

package/dist/usage.d.ts

@@ -0,0 +1,45 @@
+import type { KVStorage } from "./ports";
+/** Persisted usage snapshot. `tryOns` are recent try-on timestamps (rolling-
+ *  window rate limit); `refunded` are tombstones for entries rolled back on a
+ *  terminal generation failure; `totalTryOns` is the lifetime counter (email-
+ *  collection step); `email` is the collected shopper email (or null). */
+export interface StoredUsage {
+    tryOns: number[];
+    refunded: number[];
+    totalTryOns: number;
+    email: string | null;
+}
+/**
+ * Legacy StoredLimits key earlier widget versions wrote through
+ * `window.Genlook.storage` (getJSON/setJSON). The KVStorage port applies the
+ * same `genlook-` prefix getJSON did, so passing this logical key to the port
+ * reaches the exact same localStorage slot those versions used.
+ */
+export declare const LEGACY_LIMITS_KEY = "genlook-widget-user-limits";
+/** Drop try-on timestamps older than the 7-day retention (strict `>`), matching
+ *  the legacy prune. */
+export declare function pruneTryOns(tryOns: number[], now: number): number[];
+export declare function saveUsage(storage: KVStorage, storeId: string, usage: StoredUsage, now: number): void;
+/**
+ * Merge a persisted usage blob with the in-memory snapshot of a live core
+ * instance. Two instances of the core (a second tab, a bfcache-restored page)
+ * each hold their own snapshot; a blind write from the stale one rolls the
+ * counter back and hands the shopper free try-ons. The merge is monotonic:
+ * counted timestamps union, refund tombstones union and win over `tryOns` (so a
+ * stale copy that still holds a refunded entry can't resurrect it), and the
+ * lifetime counter takes the max of the two GROSS counts (stored total + own
+ * tombstones), minus the merged tombstones — a plain max on the stored total
+ * would make a refund's decrement unmergeable, the pre-refund copy always
+ * winning and the failed generation still counting toward the email step.
+ * `persisted === null` = nothing to merge.
+ */
+export declare function mergeUsage(persisted: StoredUsage | null, current: StoredUsage, now: number): StoredUsage;
+/** Load persisted usage from the new key. null when absent/malformed. */
+export declare function loadUsage(storage: KVStorage, storeId: string, now: number): StoredUsage | null;
+/**
+ * One-time migration source: read the legacy StoredLimits blob and normalize it
+ * to StoredUsage. Handles the array format and the old generationCount format,
+ * exactly as the legacy normalizeStored did. Returns null only when the legacy
+ * key is absent/malformed. Never deletes the legacy key.
+ */
+export declare function migrateLegacyUsage(storage: KVStorage, now: number): StoredUsage | null;