@neurodyn/react-ai-try-on 0.0.4 → 0.1.0

package/dist/index.d.ts

@@ -2,34 +2,179 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
 import { JSX } from 'react/jsx-runtime';
 import * as React_2 from 'react';
 
-export declare function AiTryOnDialog({ defaultOpen, language, onOpenChange, open, productImageSrc, productName, productPrice, productType, productUrl, apiKey, ...props }: AiTryOnDialogProps): JSX.Element;
+export declare type AiTryOnActivationState = {
+    status: 'loading';
+} | ({
+    status: 'ready';
+} & Partial<AiTryOnExternalActivation>) | {
+    status: 'unavailable';
+    temporary?: boolean;
+} | {
+    status: 'error';
+};
+
+export declare function AiTryOnDialog({ defaultOpen, language, onOpenChange, open, productImageSrc, productName, productPrice, productType, productUrl, apiKey, externalGeneration, externalActivation, externalAddToCart, externalClient, ...props }: AiTryOnDialogProps): JSX.Element;
 
 declare interface AiTryOnDialogOwnProps extends Omit<DialogProps, 'children' | 'modal'> {
     /** UI language override. */
     language?: AiTryOnLanguage;
-    /** Product image displayed in AI try-on dialog UI and sent to AI try-on generation. */
+    /** Display image; only the ordinary transport sends it to generation. External mode uses it as a preview. */
     productImageSrc: string;
     /** Product name for product preview alt text and product page CTA. */
     productName: string;
     /** Optional already-formatted product price shown in Add-to-Cart CTAs. */
     productPrice?: string;
-    /** Canonical product category sent unchanged to AI try-on generation. */
-    productType: ProductType;
     /** Product page URL opened from the result product CTA. */
     productUrl?: string;
-    /** Optional merchant API key. A non-empty key selects Public Use; its absence selects Internal Use. */
+}
+
+export declare type AiTryOnDialogProps = AiTryOnDialogOwnProps & ({
+    productType: ProductType;
     apiKey?: string;
+    externalGeneration?: never;
+    externalActivation?: never;
+    externalClient?: never;
+    externalAddToCart?: never;
+} | AiTryOnExternalProps);
+
+/** What an external integration resolves before the shopper may upload a photo. */
+export declare interface AiTryOnExternalActivation {
+    /** The integration's backend is the only authority on availability. */
+    enabled: boolean;
+    /** Set when the block should lift on its own, so the shopper is told to return. */
+    temporarilyUnavailable?: boolean;
+    /** Drives the existing photo guidance; absent means generic guidance. */
+    productType?: ProductType;
+    /** Replaces the storefront preview with the photo generation actually uses. */
+    productImageSrc?: string;
 }
 
-export declare interface AiTryOnDialogProps extends AiTryOnDialogOwnProps {
+/** External integrations may resolve product data before the shopper may act. */
+declare interface AiTryOnExternalProps {
+    externalGeneration: AiTryOnProcessPhoto;
+    /** Runs on every opening; until it resolves the dialog shows a loading screen. */
+    externalActivation?: () => Promise<AiTryOnExternalActivation>;
+    /** Transport for the open event. Without it external mode stays analytics-free. */
+    externalClient?: AiTryOnTransportClient;
+    /**
+     * Really adds the tried-on item to the host's cart. Supplying it brings the cart
+     * button back for external hosts, which otherwise only have a button that reports
+     * the intent and adds nothing.
+     */
+    externalAddToCart?: () => Promise<void> | void;
+    /** Optional fallback category; activation overrides it. */
+    productType?: ProductType;
+    apiKey?: never;
 }
 
+export declare class AiTryOnGenerationError extends Error {
+    readonly code: AiTryOnGenerationErrorCode;
+    constructor(code: AiTryOnGenerationErrorCode);
+}
+
+/** Safe, transport-independent failures that may be presented to the shopper. */
+export declare type AiTryOnGenerationErrorCode = 'tokens' | 'product' | 'service' | 'timeout' | 'photo-required';
+
 declare type AiTryOnLanguage = keyof typeof resources;
 
+export declare interface AiTryOnPhoto {
+    blob?: Blob;
+    file?: File;
+    id: string;
+    lastModified?: number;
+    name?: string;
+    size?: number;
+    src: string;
+    type?: string;
+}
+
+declare interface AiTryOnProcessingContext {
+    reportProgress: (progress: number) => void;
+}
+
+export declare type AiTryOnProcessPhoto = (photo: AiTryOnPhoto, context?: AiTryOnProcessingContext) => Promise<AiTryOnResult>;
+
+export declare interface AiTryOnResult {
+    after: AiTryOnPhoto;
+    before: AiTryOnPhoto;
+    createdAt?: number;
+    id?: string;
+    productImageSrc?: string;
+    productName?: string;
+    productPrice?: string;
+    productUrl?: string;
+}
+
+/**
+ * Transport-agnostic AI try-on client.
+ *
+ * Public Use and Internal Use each provide one implementation. The transport is
+ * selected once, before the first request, from the normalized API key
+ * (see {@link normalizeApiKey}); individual operations never choose their own
+ * endpoint. Per ADR-0002, a Public Use failure never falls back to Internal Use,
+ * and Internal Use never activates a Public Widget Session or emits Public
+ * Widget Analytics.
+ */
+declare interface AiTryOnTransportClient {
+    /** Request presigned upload URLs for the shopper and product images. */
+    requestUploadUrls: (count: number) => Promise<unknown>;
+    /** Call the unified synchronous try-on generation operation. */
+    generateTryOn: (data: TryOnGenerationRequest, options?: TryOnGenerationOptions) => Promise<unknown>;
+    /** Fire-and-forget Public Widget Analytics; a no-op in Internal Use. */
+    sendWidgetEvent: (event: AiTryOnWidgetEventName) => void;
+}
+
+declare interface AiTryOnUploadOptions {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    /** Omitted by the ordinary processor, which has never bounded its uploads. */
+    timeoutMs?: number;
+}
+
+declare type AiTryOnWidgetEventName = 'widget_opened' | 'add_to_cart_from_widget';
+
+/**
+ * Production operations for a storefront, or none without a mount.
+ *
+ * `basePath` is the App Proxy mount — `/apps/<subpath>` — and is supplied by the
+ * browser bundle rather than read from `import.meta.env` here: this package's
+ * build does not substitute `PUBLIC_*` vars, so a read at this level compiles to
+ * an empty string. Kept root-relative so it resolves against the shop's own
+ * domain from any product URL, including localised ones.
+ */
+export declare function createAppProxyOperations(basePath: string): ShopifyTryOnOperations | undefined;
+
+export declare function createShopifyTryOnClient(options: ShopifyTryOnClientOptions): ShopifyTryOnClient;
+
 declare type DialogProps = React_2.ComponentProps<typeof DialogPrimitive.Root>
 
 export declare function isProductType(value: unknown): value is ProductType;
 
+declare type IssueWidgetToken = (data: {
+    token?: string;
+}, config?: WidgetSessionApiConfig) => Promise<IssueWidgetTokenResponseDtoOutput>;
+
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+declare type IssueWidgetTokenResponseDtoOutput = {
+    /**
+     * @type string
+     */
+    token: string;
+    /**
+     * @type string
+     */
+    sid: string;
+    /**
+     * @minLength -9007199254740991
+     * @maxLength 9007199254740991
+     * @type integer
+     */
+    expiresIn: number;
+};
+
 export declare const PRODUCT_TYPES: readonly ["full-body", "upper-body", "lower-body", "footwear", "headwear", "eyewear", "neck", "wrist", "bag", "waist"];
 
 export declare type ProductType = typeof PRODUCT_TYPES[number];
@@ -37,6 +182,16 @@ export declare type ProductType = typeof PRODUCT_TYPES[number];
 declare const resources: {
     readonly en: {
         readonly ns1: {
+            readonly activationLoading: "Checking this product…";
+            readonly activationLoadingSubtitle: "One moment while the store confirms try-on for this item.";
+            readonly activationTemporarilyUnavailable: "Try-on is paused for this store right now. Please check back later.";
+            readonly activationUnavailableTitle: "Try-on is unavailable";
+            readonly externalPhotoRequired: "Please upload your photo again.";
+            readonly externalNoTokens: "The store has no tokens remaining.";
+            readonly externalProductUnavailable: "Try-on is unavailable for this product.";
+            readonly externalServiceUnavailable: "Try-on is unavailable. Please try again later.";
+            readonly externalTimeout: "The request timed out. Please try again.";
+            readonly externalPhotoHint: "Upload a clear photo of yourself. The store chooses the item used for your try-on.";
             readonly back: "Back";
             readonly badge: "Try it on";
             readonly confirmBadge: "Almost there";
@@ -126,7 +281,7 @@ declare const resources: {
             readonly startUpload: "Choose your photo";
             readonly termsJoiner: "&";
             readonly termsLink: "Terms";
-            readonly termsPrefix: "By using this service, your agree to";
+            readonly termsPrefix: "By using this service, you agree to";
             readonly privacyLink: "privacy Policy";
             readonly upperBodyIntroBadArmsCrossed: "Arms crossed hide the fit";
             readonly upperBodyIntroBadObjectBlockingTorso: "Object blocks the torso";
@@ -150,6 +305,16 @@ declare const resources: {
     };
     readonly ru: {
         readonly ns1: {
+            readonly activationLoading: "Проверяем товар…";
+            readonly activationLoadingSubtitle: "Магазин подтверждает примерку для этого товара.";
+            readonly activationTemporarilyUnavailable: "Примерка в этом магазине сейчас приостановлена. Загляните позже.";
+            readonly activationUnavailableTitle: "Примерка недоступна";
+            readonly externalPhotoRequired: "Загрузите фото заново.";
+            readonly externalNoTokens: "У магазина закончились токены.";
+            readonly externalProductUnavailable: "Примерка для этого товара недоступна.";
+            readonly externalServiceUnavailable: "Примерка недоступна. Попробуйте позже.";
+            readonly externalTimeout: "Время ожидания истекло. Попробуйте снова.";
+            readonly externalPhotoHint: "Загрузите чёткое фото себя. Изображение товара для примерки определяется настройками магазина.";
             readonly back: "Назад";
             readonly badge: "Примерить";
             readonly confirmBadge: "Почти готово";
@@ -206,7 +371,7 @@ declare const resources: {
             readonly headwearIntroTitle: "Загрузите фото головы и плеч";
             readonly introCta: "Продолжить";
             readonly introBadge: "Совет";
-            readonly myFits: "My fits";
+            readonly myFits: "Мои образы";
             readonly lowerBodyIntroBadCoveredWaist: "Свободная одежда скрывает линию талии";
             readonly lowerBodyIntroBadSitting: "В сидячей позе ноги согнуты";
             readonly lowerBodyIntroGoodFullBody: "Фото в полный рост";
@@ -231,8 +396,8 @@ declare const resources: {
             readonly resultReset: "Сохранить";
             readonly resultShare: "Поделиться";
             readonly resultTitle: "Вот как это выглядит на вас";
-            readonly resultTryAnother: "Add To Cart";
-            readonly resultTryAnotherWithPrice: "Add To Cart – {{price}}";
+            readonly resultTryAnother: "Добавить в корзину";
+            readonly resultTryAnotherWithPrice: "Добавить в корзину – {{price}}";
             readonly share: "Поделиться";
             readonly startHistory: "Смотреть прошлые результаты";
             readonly startTitle: "Хотите увидеть это на себе?";
@@ -263,4 +428,109 @@ declare const resources: {
     };
 };
 
+/** The isolated client does not inherit the shared client's default, so it is set here. */
+export declare const SHOPIFY_REQUEST_TIMEOUT_MS = 30000;
+
+export declare interface ShopifyActivation {
+    /** The backend decides availability; the frontend only refuses a malformed answer. */
+    available: boolean;
+    reason?: ShopifyUnavailableReason;
+    /** Canonical zone slug, when the backend resolved one. Drives the photo guidance. */
+    zoneType?: ProductType;
+    /** The photo the backend generates from, replacing the storefront preview. */
+    photoUrl?: string;
+}
+
+/**
+ * One instance per dialog opening: it activates the product, holds the Widget
+ * Session, runs generation and emits the open event. Uploads and generation are
+ * reached through {@link createProcessPhoto}, never through the transport
+ * surface — the widget must not drive Shopify requests with the ordinary shapes.
+ */
+declare class ShopifyTryOnClient implements AiTryOnTransportClient {
+    private readonly createObjectUrl;
+    private readonly operations;
+    private readonly signal;
+    private session;
+    constructor({ createObjectUrl, operations, signal }: ShopifyTryOnClientOptions);
+    activate(target: ShopifyTryOnTarget): Promise<ShopifyActivation>;
+    createProcessPhoto(target: ShopifyTryOnTarget): AiTryOnProcessPhoto;
+    /**
+     * Every Shopify request funnels through here so a rejected HTTP status reaches
+     * the shopper as a stable code instead of a generic service failure.
+     */
+    private run;
+    sendWidgetEvent(event: AiTryOnWidgetEventName): void;
+    /** Shopify uploads and generation go through {@link createProcessPhoto}. */
+    requestUploadUrls(): Promise<never>;
+    generateTryOn(): Promise<never>;
+    private baseConfig;
+    private requestConfig;
+}
+
+declare interface ShopifyTryOnClientOptions {
+    createObjectUrl?: (blob: Blob) => string;
+    operations: ShopifyTryOnOperations;
+    signal?: AbortSignal;
+}
+
+/**
+ * HTTP seam. Stage 1 supplies test operations; stage 2 supplies the generated
+ * `@vizbl/api` methods bound to an isolated client on the App Proxy path.
+ */
+export declare interface ShopifyTryOnOperations {
+    activate: (target: ShopifyTryOnTarget, config: WidgetSessionApiConfig) => Promise<unknown>;
+    requestUploadUrls: (count: number, config: WidgetSessionApiConfig) => Promise<unknown>;
+    generate: (data: ShopifyTryOnTarget & {
+        personImageKey: string;
+    }, config: WidgetSessionApiConfig) => Promise<unknown>;
+    /**
+     * Refreshes the Widget Session. Required: without it the session client falls
+     * back to the shared cabinet API instance and the refresh leaves the proxy.
+     */
+    issueWidgetToken: IssueWidgetToken;
+    /** Overrides the direct PUT to storage; the demo uses it to keep photos local. */
+    uploadPhoto?: (uploadUrl: string, photo: Blob, options: {
+        signal?: AbortSignal;
+        timeoutMs: number;
+    }) => Promise<void>;
+    sendWidgetEvent?: (data: {
+        event: AiTryOnWidgetEventName;
+        timestamp: string;
+    }, config: WidgetSessionApiConfig) => Promise<unknown>;
+}
+
+/**
+ * What the shopper is trying on. The variant is optional: a product page without
+ * a variant picker has none, and the backend then resolves the product's photo.
+ */
+export declare interface ShopifyTryOnTarget {
+    productId: string;
+    variantId?: string;
+}
+
+/** Why the backend refused, so the storefront can tell "come back later" from "not set up". */
+declare type ShopifyUnavailableReason = 'not_enabled' | 'zone_not_configured' | 'no_product_photo' | 'tokens_exhausted';
+
+declare interface TryOnGenerationOptions {
+    timeout?: number;
+}
+
+declare interface TryOnGenerationRequest {
+    /** Validated canonical Product Type, sent unchanged to the unified generation operation. */
+    category: ProductType;
+    personImage: string;
+    productImages: string[];
+}
+
+export declare function uploadImageToPresignedUrl(uploadUrl: string, imageBlob: Blob, options?: AiTryOnUploadOptions): Promise<void>;
+
+declare interface WidgetSessionApiConfig {
+    baseURL?: string;
+    headers?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    timeout?: number;
+    responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream';
+}
+
 export { }