@genlook/storefront 0.1.0

package/dist/generation.js

@@ -0,0 +1,382 @@
+export function classifyErrorKind(code, message) {
+    switch (code) {
+        case "QUOTA_EXCEEDED":
+        case "BILLING_NOT_ALLOWED":
+            return "quota";
+        case "FITTING_ROOM_WEEKLY_LIMIT_EXCEEDED":
+            return "weekly_limit";
+        case "RATE_LIMIT_EXCEEDED":
+            return "rate_limited";
+        case "CREATION_FAILED":
+            return "creation_failed";
+        case "UPLOAD_FAILED":
+            return "upload_failed";
+    }
+    const quotaRelated = message.includes("quota exceeded") || message.includes("exceeded your current quota");
+    if (!quotaRelated &&
+        (message.includes("out of capacity") ||
+            (message.includes("RESOURCE_EXHAUSTED") && message.includes("429")))) {
+        return "overloaded";
+    }
+    return "failed";
+}
+export class GenerationFailedError extends Error {
+    code;
+    kind;
+    constructor(code, message, kind) {
+        super(message);
+        this.name = "GenerationFailedError";
+        this.code = code;
+        this.kind = kind ?? classifyErrorKind(code, message);
+    }
+}
+export async function createFittingRoomJob(transport, request) {
+    try {
+        const endpoint = "/try-ons";
+        console.log("Creating generation job at:", endpoint);
+        const response = await transport.fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(request),
+            includeFingerprint: true,
+        });
+        if (!response.ok) {
+            if (response.status === 429) {
+                let errorCode = "RATE_LIMIT_EXCEEDED";
+                try {
+                    const body = (await response.json());
+                    if (body?.code === "FITTING_ROOM_WEEKLY_LIMIT_EXCEEDED") {
+                        errorCode = "FITTING_ROOM_WEEKLY_LIMIT_EXCEEDED";
+                    }
+                }
+                catch {
+                }
+                throw new GenerationFailedError(errorCode, "Too many requests");
+            }
+            const errorText = await response.text();
+            throw new Error(`API request failed: ${response.status} ${response.statusText}. ${errorText}`);
+        }
+        const result = (await response.json());
+        console.log("Generation job created:", result.jobId);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error(`Unexpected error: ${error}`);
+    }
+}
+export async function getGenerationStatus(transport, jobId) {
+    try {
+        const endpoint = `/try-ons/${encodeURIComponent(jobId)}`;
+        console.log("Checking generation status at:", endpoint);
+        const response = await transport.fetch(endpoint, { method: "GET" });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Status check failed: ${response.status} ${response.statusText}. ${errorText}`);
+        }
+        const result = (await response.json());
+        console.log("Generation status:", result.status);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error(`Unexpected error: ${error}`);
+    }
+}
+export async function pollGenerationStatus(transport, jobId, onStatusChange, pollInterval = 1000, maxAttempts = 60) {
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+        const status = await getGenerationStatus(transport, jobId);
+        if (onStatusChange)
+            onStatusChange(status);
+        if (status.status === "COMPLETED")
+            return status;
+        if (status.status === "FAILED") {
+            throw new GenerationFailedError(status.errorCode || "GENERATION_FAILED", status.errorMessage || "Generation failed");
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        attempts++;
+    }
+    throw new GenerationFailedError("GENERATION_FAILED", "Generation timeout - please try again");
+}
+export async function getCurrentPlan(transport) {
+    try {
+        const endpoint = "/plan";
+        console.log("Fetching current plan at:", endpoint);
+        const response = await transport.fetch(endpoint, { method: "GET" });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Failed to get current plan: ${response.status} ${response.statusText}. ${errorText}`);
+        }
+        const result = (await response.json());
+        console.log("Current plan:", result.plan);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error(`Unexpected error: ${error}`);
+    }
+}
+export async function checkCredits(transport) {
+    const endpoint = "/availability";
+    console.log("Checking credits at:", endpoint);
+    const response = await transport.fetch(endpoint, { method: "GET" });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to check credits: ${response.status} ${response.statusText}. ${errorText}`);
+    }
+    const result = (await response.json());
+    console.log("Credits check result:", result.allowed ? "allowed" : "not allowed");
+    return result;
+}
+export async function rateGeneration(transport, generationId, rating, reason) {
+    const response = await transport.fetch(`/try-ons/${encodeURIComponent(generationId)}/rating`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ rating, reason: reason ?? null }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to rate generation: ${response.status} ${response.statusText}. ${errorText}`);
+    }
+    return (await response.json());
+}
+function patchHistoryEntry(store, id, patch) {
+    store.setState((s) => ({
+        ...s,
+        history: s.history.map((r) => (r.id === id ? { ...r, ...patch } : r)),
+    }));
+}
+export async function rateResult(deps, entryId, rating, reason) {
+    const entry = deps.store.getState().history.find((r) => r.id === entryId);
+    if (!entry)
+        return;
+    const generationId = entry.generationId || entry.id;
+    if (!generationId)
+        return;
+    if (reason != null) {
+        patchHistoryEntry(deps.store, entryId, { feedbackReason: reason });
+        deps.emitResultRatingReason(generationId, reason);
+        try {
+            await rateGeneration(deps.transport, generationId, rating, reason);
+        }
+        catch (error) {
+            console.error("Failed to save feedback reason:", error);
+        }
+        return;
+    }
+    const previousRating = entry.rating ?? null;
+    patchHistoryEntry(deps.store, entryId, { rating, feedbackReason: undefined });
+    deps.emitResultRated(generationId, rating);
+    try {
+        await rateGeneration(deps.transport, generationId, rating);
+    }
+    catch (error) {
+        console.error("Failed to rate generation:", error);
+        patchHistoryEntry(deps.store, entryId, { rating: previousRating });
+    }
+}
+function failureKindCode(err) {
+    const typed = err instanceof Error && err.name === "GenerationFailedError"
+        ? err
+        : null;
+    return { kind: typed?.kind ?? "failed", code: typed?.code ?? "GENERATION_FAILED" };
+}
+function limitsWithUsageRefunded(limits, usageAt) {
+    if (usageAt === undefined)
+        return limits;
+    const idx = limits.tryOns.indexOf(usageAt);
+    const tryOns = idx >= 0
+        ? [...limits.tryOns.slice(0, idx), ...limits.tryOns.slice(idx + 1)]
+        : limits.tryOns;
+    const refunded = limits.refunded.includes(usageAt) ? limits.refunded : [...limits.refunded, usageAt];
+    return { ...limits, tryOns, refunded, totalTryOns: Math.max(0, limits.totalTryOns - 1) };
+}
+function refundPreEntityUsage(deps, usageAt) {
+    if (usageAt === undefined)
+        return;
+    deps.store.setState((s) => ({ ...s, limits: limitsWithUsageRefunded(s.limits, usageAt) }));
+}
+function refundJobUsage(deps, generationId) {
+    deps.store.setState((s) => {
+        const job = s.generations[generationId];
+        if (!job || job.usageAt === undefined || job.usageRefunded)
+            return s;
+        return {
+            ...s,
+            limits: limitsWithUsageRefunded(s.limits, job.usageAt),
+            generations: { ...s.generations, [generationId]: { ...job, usageRefunded: true } },
+        };
+    });
+}
+function upsertGeneration(store, job) {
+    store.setState((s) => ({ ...s, generations: { ...s.generations, [job.id]: job } }));
+}
+function patchGeneration(store, id, next) {
+    store.setState((s) => {
+        const current = s.generations[id];
+        if (!current)
+            return s;
+        return { ...s, generations: { ...s.generations, [id]: next(current) } };
+    });
+}
+function ensureReported(deps, id) {
+    const job = deps.store.getState().generations[id];
+    if (job && !job.reported) {
+        deps.emitGenerationStart(id);
+        patchGeneration(deps.store, id, (j) => ({ ...j, reported: true }));
+    }
+}
+export function classifyGenerationError(err) {
+    const typed = err instanceof Error && err.name === "GenerationFailedError"
+        ? err
+        : null;
+    const kind = typed?.kind ?? "failed";
+    const backendCode = typed?.code ?? "GENERATION_FAILED";
+    switch (kind) {
+        case "quota":
+            return { code: "credits-expired", retryable: false, backendCode };
+        case "weekly_limit":
+        case "rate_limited":
+            return { code: "rate-limited", retryable: true, backendCode };
+        case "upload_failed":
+            return { code: "upload-failed", retryable: true, backendCode };
+        default:
+            return { code: "server-overloaded", retryable: true, backendCode };
+    }
+}
+function blockedReasonFor(err) {
+    if (!(err instanceof Error) || err.name !== "GenerationFailedError")
+        return null;
+    const { kind, code } = err;
+    return kind === "quota" || kind === "weekly_limit" || kind === "rate_limited" ? code : null;
+}
+export async function runGeneration(deps, input) {
+    let jobResponse;
+    try {
+        jobResponse = await createFittingRoomJob(deps.transport, {
+            userImageId: input.userImageId,
+            productId: input.productId,
+            variantId: input.variantId,
+        });
+    }
+    catch (err) {
+        refundPreEntityUsage(deps, input.usageAt);
+        const blocked = blockedReasonFor(err);
+        if (blocked)
+            deps.emitGenerationBlocked(blocked);
+        throw err;
+    }
+    if (jobResponse.code) {
+        refundPreEntityUsage(deps, input.usageAt);
+        const err = new GenerationFailedError(jobResponse.code, jobResponse.message || "Job creation failed");
+        const blocked = blockedReasonFor(err);
+        if (blocked)
+            deps.emitGenerationBlocked(blocked);
+        throw err;
+    }
+    const generationId = jobResponse.jobId;
+    upsertGeneration(deps.store, {
+        id: generationId,
+        photoId: input.userImageId,
+        productId: input.productId,
+        variantId: input.variantId,
+        createdAt: deps.now(),
+        seen: false,
+        reported: false,
+        usageAt: input.usageAt,
+        usageRefunded: false,
+        status: "requested",
+    });
+    ensureReported(deps, generationId);
+    patchGeneration(deps.store, generationId, (j) => ({ ...j, status: "generating" }));
+    try {
+        const status = await pollGenerationStatus(deps.transport, generationId, undefined, deps.pollInterval, deps.maxAttempts);
+        if (!status.resultImageUrl)
+            throw new Error("No image URL returned from generation");
+        patchGeneration(deps.store, generationId, (j) => ({
+            id: j.id, photoId: j.photoId, productId: j.productId, variantId: j.variantId,
+            createdAt: j.createdAt, seen: false, reported: j.reported,
+            usageAt: j.usageAt, usageRefunded: j.usageRefunded,
+            status: "done", resultImageUrl: status.resultImageUrl, resultImageKey: status.resultImageKey,
+        }));
+        emitSucceeded(deps, generationId);
+        return { imageUrl: status.resultImageUrl, generationId };
+    }
+    catch (err) {
+        const error = classifyGenerationError(err);
+        patchGeneration(deps.store, generationId, (j) => ({
+            id: j.id, photoId: j.photoId, productId: j.productId, variantId: j.variantId,
+            createdAt: j.createdAt, seen: j.seen, reported: j.reported,
+            usageAt: j.usageAt, usageRefunded: j.usageRefunded, status: "error", error,
+        }));
+        deps.emitGenerationFailed({ generationId, ...failureKindCode(err) });
+        refundJobUsage(deps, generationId);
+        throw err;
+    }
+}
+function emitSucceeded(deps, generationId) {
+    const job = deps.store.getState().generations[generationId];
+    if (!job)
+        return;
+    deps.emitGenerationSucceeded({
+        generationId,
+        durationMs: deps.now() - job.createdAt,
+        productId: job.productId,
+        variantId: job.variantId,
+    });
+}
+export async function resumeGeneration(deps, generationId) {
+    const existing = deps.store.getState().generations[generationId];
+    if (!existing)
+        return;
+    ensureReported(deps, generationId);
+    patchGeneration(deps.store, generationId, (j) => j.status === "requested" ? { ...j, status: "generating" } : j);
+    try {
+        const status = await pollGenerationStatus(deps.transport, generationId, undefined, deps.pollInterval, deps.maxAttempts);
+        if (status.resultImageUrl) {
+            patchGeneration(deps.store, generationId, (j) => ({
+                id: j.id, photoId: j.photoId, productId: j.productId, variantId: j.variantId,
+                createdAt: j.createdAt, seen: false, reported: j.reported,
+                usageAt: j.usageAt, usageRefunded: j.usageRefunded,
+                status: "done", resultImageUrl: status.resultImageUrl, resultImageKey: status.resultImageKey,
+            }));
+            emitSucceeded(deps, generationId);
+        }
+        else {
+            patchGeneration(deps.store, generationId, (j) => ({
+                id: j.id, photoId: j.photoId, productId: j.productId, variantId: j.variantId,
+                createdAt: j.createdAt, seen: j.seen, reported: j.reported,
+                usageAt: j.usageAt, usageRefunded: j.usageRefunded,
+                status: "error", error: { code: "server-overloaded", retryable: true, backendCode: "GENERATION_FAILED" },
+            }));
+            deps.emitGenerationFailed({ generationId, kind: "failed", code: "GENERATION_FAILED" });
+            refundJobUsage(deps, generationId);
+        }
+    }
+    catch (err) {
+        patchGeneration(deps.store, generationId, (j) => ({
+            id: j.id, photoId: j.photoId, productId: j.productId, variantId: j.variantId,
+            createdAt: j.createdAt, seen: j.seen, reported: j.reported,
+            usageAt: j.usageAt, usageRefunded: j.usageRefunded,
+            status: "error", error: classifyGenerationError(err),
+        }));
+        deps.emitGenerationFailed({ generationId, ...failureKindCode(err) });
+        refundJobUsage(deps, generationId);
+    }
+}
+export function acknowledgeGeneration(store, generationId) {
+    patchGeneration(store, generationId, (j) => ({ ...j, seen: true }));
+}
+export function scheduleInFlightResumes(deps, jobs) {
+    void Promise.resolve().then(() => {
+        for (const job of jobs) {
+            if (job.status === "requested" || job.status === "generating") {
+                void resumeGeneration(deps, job.id);
+            }
+        }
+    });
+}

package/dist/history.d.ts

@@ -0,0 +1,76 @@
+import type { KVStorage } from "./ports";
+/** A history entry as rendered by the widget's history page. */
+export interface TryOnResult {
+    id: string;
+    generationId: string;
+    shareUrl?: string;
+    productId: string;
+    productName?: string | null;
+    variantId?: string | null;
+    featured_image: string;
+    resultImage: string;
+    timestamp: number;
+    location: string;
+    /** 1 = thumbs up, -1 = thumbs down, 0 or null = no rating */
+    rating?: 1 | -1 | 0 | null;
+    feedbackReason?: string;
+    /**
+     * True when this result came from a scripted/sample showcase path (no backend
+     * generation record exists). Such results hide share + rating (nothing to
+     * share or rate on the backend) but keep add-to-cart. Real generations leave
+     * this unset.
+     */
+    scripted?: boolean;
+    /**
+     * Structured product context, ADDITIVE over the legacy flat fields
+     * (`productName` / `featured_image` / `location`, which are still written
+     * verbatim — see buildTryOnResult). New readers prefer this object; classic +
+     * legacy readers ignore these extra keys and keep reading the flat fields, so
+     * the shared `tryOnHistory` byte format stays backward-compatible. Absent on
+     * entries written before this field existed.
+     */
+    product?: {
+        title?: string | null;
+        image?: string;
+        url?: string;
+        price?: string | null;
+        currency?: string | null;
+    };
+}
+/** Display-side product context the host passes into generate() so the core can
+ *  assemble the full TryOnResult on success. Distinct from the API product id
+ *  (`productId` here is the raw storefront id the history page renders). */
+export interface GenerationContext {
+    productId: string;
+    productName?: string | null;
+    variantId?: string | null;
+    featuredImage: string;
+    location: string;
+    /** Display-ready, already-formatted price string (e.g. "$48.00"); null/absent
+     *  when the host couldn't resolve a price it's confident is correct. */
+    price?: string | null;
+    /** ISO currency code that `price` was formatted in, when known. */
+    currency?: string | null;
+}
+export declare const HISTORY_KEY = "tryOnHistory";
+export declare const DEFAULT_RETENTION_DAYS = 7;
+export declare function loadHistory(storage: KVStorage): TryOnResult[];
+export declare function saveHistory(storage: KVStorage, history: TryOnResult[]): void;
+/**
+ * Read-side retention window: entries younger than (retention - 1) days, so the
+ * UI doesn't show results about to be deleted server-side. Stored history is
+ * NEVER pruned — this is a derived view only.
+ */
+export declare function selectRecentResults(history: TryOnResult[], retentionDays: number | null | undefined, now: number): TryOnResult[];
+/** Assemble a full TryOnResult (id minting included) from a completed — or
+ *  scripted — generation plus the host-provided display context. */
+export declare function buildTryOnResult(input: {
+    generationId: string;
+    resultImage: string;
+    context: GenerationContext;
+    now: number;
+    shareUrl?: string;
+    scripted?: boolean;
+}): TryOnResult;
+export declare function appendEntry(history: TryOnResult[], entry: TryOnResult): TryOnResult[];
+export declare function updateEntry(history: TryOnResult[], id: string, patch: Partial<TryOnResult>): TryOnResult[];

package/dist/history.js

@@ -0,0 +1,68 @@
+export const HISTORY_KEY = "tryOnHistory";
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export const DEFAULT_RETENTION_DAYS = 7;
+export function loadHistory(storage) {
+    let raw;
+    try {
+        raw = storage.getItem(HISTORY_KEY);
+    }
+    catch {
+        return [];
+    }
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    return Array.isArray(parsed) ? parsed : [];
+}
+export function saveHistory(storage, history) {
+    try {
+        storage.setItem(HISTORY_KEY, JSON.stringify(history));
+    }
+    catch {
+    }
+}
+export function selectRecentResults(history, retentionDays, now) {
+    const days = retentionDays ?? DEFAULT_RETENTION_DAYS;
+    const thresholdMs = Math.max(1, days - 1) * MS_PER_DAY;
+    return history.filter((r) => now - r.timestamp < thresholdMs);
+}
+export function buildTryOnResult(input) {
+    const result = {
+        id: `${input.now}-${Math.random()}`,
+        generationId: input.generationId,
+        productId: input.context.productId,
+        productName: input.context.productName,
+        variantId: input.context.variantId,
+        featured_image: input.context.featuredImage,
+        resultImage: input.resultImage,
+        timestamp: input.now,
+        location: input.context.location,
+    };
+    if (input.shareUrl !== undefined)
+        result.shareUrl = input.shareUrl;
+    if (input.scripted)
+        result.scripted = true;
+    const product = {
+        title: input.context.productName,
+        image: input.context.featuredImage,
+        url: input.context.location,
+    };
+    if (input.context.price !== undefined)
+        product.price = input.context.price;
+    if (input.context.currency !== undefined)
+        product.currency = input.context.currency;
+    result.product = product;
+    return result;
+}
+export function appendEntry(history, entry) {
+    return [entry, ...history];
+}
+export function updateEntry(history, id, patch) {
+    return history.map((r) => (r.id === id ? { ...r, ...patch } : r));
+}

package/dist/memory-storage.d.ts

@@ -0,0 +1,10 @@
+import type { KVStorage } from "./ports";
+/**
+ * In-memory {@link KVStorage} (Map-backed). A legitimate port helper: a host
+ * that wants ephemeral, isolated core persistence — the design-settings preview
+ * composition root, unit tests — injects this instead of a device-backed store.
+ * The core reads/writes its usage / jobs / history keys against a per-instance
+ * map that never touches `localStorage`, so nothing leaks across preview sessions
+ * and no merchant-browser state is polluted.
+ */
+export declare function memoryStorage(): KVStorage;

package/dist/memory-storage.js

@@ -0,0 +1,12 @@
+export function memoryStorage() {
+    const map = new Map();
+    return {
+        getItem: (key) => (map.has(key) ? map.get(key) : null),
+        setItem: (key, value) => {
+            map.set(key, String(value));
+        },
+        removeItem: (key) => {
+            map.delete(key);
+        },
+    };
+}

package/dist/pending-upload.d.ts

@@ -0,0 +1,32 @@
+import type { UploadResult } from "./types";
+/**
+ * The client's LATEST pending upload. Each `uploadPhoto` registers its promise;
+ * a newer registration supersedes the older. A superseded upload's promise STILL
+ * settles for its own awaiter (and its terminal funnel events still fire — the
+ * upload happened), it is just no longer "current":
+ *
+ *  - it never overwrites the pointer — only `register` writes it, in call order,
+ *    so the newest-registered upload wins and an older upload settling later never
+ *    clobbers the newer one;
+ *  - `generate({ userImage: "latest" })` awaits `current()` — the newest upload AT
+ *    THE TIME generate is called.
+ *
+ * This is the promise counterpart to `selectCurrentUpload` (store state): both
+ * point at the same "latest" upload, one for awaiting, one for rendering.
+ *
+ * NO cancellation: a superseded upload runs to completion and its result is simply
+ * ignored. Aborting it would require threading an AbortSignal through the Transport
+ * port (a port change) — a possible future refinement, out of scope here.
+ */
+export declare class PendingUpload {
+    private latest;
+    /** Register a freshly started upload as the current pending upload (supersedes
+     *  any previous one). Attaches a no-op catch so a superseded/failed upload never
+     *  surfaces as an unhandled rejection — the real awaiter still receives the
+     *  rejection from the promise it was handed. */
+    register(promise: Promise<UploadResult>): void;
+    /** The newest registered upload, or null when none is pending / it was cleared. */
+    current(): Promise<UploadResult> | null;
+    /** Drop the current pointer (the host discarded the selected photo). */
+    clear(): void;
+}

package/dist/pending-upload.js

@@ -0,0 +1,13 @@
+export class PendingUpload {
+    latest = null;
+    register(promise) {
+        this.latest = promise;
+        promise.catch(() => { });
+    }
+    current() {
+        return this.latest;
+    }
+    clear() {
+        this.latest = null;
+    }
+}

package/dist/persistence.d.ts

@@ -0,0 +1,12 @@
+import type { KVStorage } from "./ports";
+import type { GenerationJob } from "./entities";
+export declare const GENERATION_TIMEOUT_MS: number;
+export declare const STALE_TTL_MS: number;
+export declare const RETENTION_MS: number;
+export declare function saveJobs(storage: KVStorage, storeId: string, jobs: GenerationJob[]): void;
+/**
+ * Load persisted jobs. Prunes expired terminal jobs, converts stale non-terminal
+ * jobs to `error`, and returns the surviving live entities. Fresh non-terminal
+ * jobs come back with their status intact so the client can resume polling.
+ */
+export declare function loadJobs(storage: KVStorage, storeId: string, now: number): GenerationJob[];