@akinon/pz-virtual-try-on 2.0.34-beta.0 → 2.0.34

package/CHANGELOG.md

@@ -1,11 +1,12 @@
 # @akinon/pz-virtual-try-on
 
-## 2.0.34-beta.0
+## 2.0.34
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd75]
-  - @akinon/next@2.0.34-beta.0
+- 4e2ea16b: ZERO-4582: enhance virtual try-on functionality with single and async mutations
+- Updated dependencies [4e2ea16b]
+  - @akinon/next@2.0.34
 
 ## 2.0.33
 

package/README.md

@@ -2109,11 +2109,20 @@ This allows partial customization - you can override only the images or texts yo
 
 `loadingSpinner`, `loadingOverlay`, `loadingText`, `modalEnter`, `modalExit`, `fadeIn`, `fadeOut`, `slideIn`, `slideOut`.
 
+### Usage Limit & Loader Targets
+
+`usageCheckOverlay`, `usageCheckSpinner` (full-screen loader shown while the try-on usage/limit pre-check runs on button click), `resultModalUsageInfo`, `multipleResultModalUsageInfo`, `basketAsyncModalUsageInfo` (the "used/limit" info line rendered in each result surface when the backend returns `tryon_limit`).
+
 ### Render Functions
 
-- **Button**: `renderButton`, `renderIcon`, `renderLoadingSpinner`, `renderButtonText`.
+- **Button**: `renderButton`, `renderIcon`, `renderLoadingSpinner`, `renderButtonText`, `renderUsageCheckLoader`.
 - **Upload Modal**: `renderModal`, `renderHeader`, `renderCloseButton`, `renderLegalConsent`, `renderLegalConsentTitle`, `renderLegalConsentText`, `renderLegalConsentButton`, `renderUploadSection`, `renderUploadTitle`, `renderUploadInstructions`, `renderUploadArea`, `renderUploadIcon`, `renderUploadPrompt`, `renderUploadRequirements`, `renderFileInput`, `renderImagePreview`, `renderImageContainer`, `renderCropContainer`, `renderCroppingImage`, `renderPreviewImage`, `renderBackButton`, `renderBackButtonIcon`, `renderCropButton`, `renderCropButtonIcon`, `renderCropTickButton`, `renderCropTickIcon`, `renderCropResetButton`, `renderCropResetIcon`, `renderTryOnButton`, `renderProcessingState`, `renderProcessingOverlay`, `renderProcessingSpinner`, `renderProcessingMessage`, `renderSuccessState`, `renderSuccessIcon`, `renderSuccessMessage`, `renderActionButtonsContainer`, `renderViewResultButton`, `renderViewResultIcon`, `renderTryAgainButton`, `renderTryAgainIcon`, `renderErrorMessage`, `renderErrorIcon`, `renderErrorText`.
-- **Result Modal**: `renderModal`, `renderHeader`, `renderCloseButton`, `renderBackButton`, `renderBackButtonIcon`, `renderResultImage`, `renderImageContainer`, `renderFeedbackSection`, `renderFeedbackPrompt`, `renderFeedbackButtonsContainer`, `renderFeedbackButtons`, `renderFeedbackButton`, `renderPositiveFeedbackButton`, `renderNegativeFeedbackButton`, `renderThumbsUpIcon`, `renderThumbsDownIcon`, `renderErrorState`, `renderResultErrorIcon`, `renderResultErrorMessage`, `renderRetryButton`, `renderEmptyState`, `renderEmptyIcon`, `renderEmptyMessage`, `renderGoBackButton`, `renderDebugSection`, `renderDebugStats`, `renderClearCacheButton`.
+- **Result Modal**: `renderModal`, `renderHeader`, `renderCloseButton`, `renderBackButton`, `renderBackButtonIcon`, `renderResultImage`, `renderImageContainer`, `renderFeedbackSection`, `renderFeedbackPrompt`, `renderFeedbackButtonsContainer`, `renderFeedbackButtons`, `renderFeedbackButton`, `renderPositiveFeedbackButton`, `renderNegativeFeedbackButton`, `renderThumbsUpIcon`, `renderThumbsDownIcon`, `renderErrorState`, `renderResultErrorIcon`, `renderResultErrorMessage`, `renderRetryButton`, `renderEmptyState`, `renderEmptyIcon`, `renderEmptyMessage`, `renderGoBackButton`, `renderDebugSection`, `renderDebugStats`, `renderClearCacheButton`, `renderUsageInfo`.
+- **Multiple Result Modal**: `renderModal`, `renderBackIcon`, `renderCloseIcon`, `renderErrorIcon`, `renderUsageInfo`.
+- **Basket Async Modal**: `renderModal`, `renderCloseIcon`, `renderProcessingSpinner`, `renderUsageInfo`.
+- **Basket Virtual Try-On**: `renderButton`, `renderIcon`, `renderButtonText`, `renderUsageCheckLoader`.
+
+`renderUsageCheckLoader()` replaces the full-screen loader shown during the usage/limit pre-check. `renderUsageInfo({ used, limit, text })` replaces the "used/limit" info line; `text` is the already-localized string, `used`/`limit` are the raw numbers.
 
 ## Workflow & Caching
 
@@ -2145,31 +2154,44 @@ Cache TTL defaults to five minutes (`5 / 60` hours) and auto-prunes expired keys
 
 ---
 
-## 🆕 Multiple Product API Documentation
+## 🆕 Async Try-On API Documentation (Single & Multiple)
 
 ### Async Workflow
 
-The new multiple product try-on uses an async workflow with polling:
+Try-on uses an async workflow with polling. All calls go through the Next.js proxy (`/api/virtual-try-on?endpoint=...`), which forwards to the try-on service and injects identity headers server-side (`X-Session-Id` from the `osessionid` cookie, `X-User-Id` from the NextAuth session `user.pk`):
 
 ```
-1. POST /api/v1/async/multiple_virtual_try_on
-   ├─ Request: { sku, images, category_ids, reference_image, ... }
-   └─ Response: { reference_url, status: "pending" }
-
-2. GET /api/v1/async/job_status?reference_url=...
-   ├─ Poll every 1+ second (max 60 attempts)
+0. POST ?endpoint=usage → /api/v1/try-on-usage        (limit pre-check)
+   ├─ Request: { skus: ["SKU-1", ...] }
+   ├─ Response: { tryon_limit, skus: [{ sku, used_count }] }
+   ├─ tryon_limit = 0 → unlimited, skip client-side checks
+   └─ Guest + limit active → 400 VALIDATION → redirect to login
+
+1. POST ?endpoint=single-try-on   → /api/v1/virtual-try-on           (PDP)
+   POST ?endpoint=multiple-try-on → /api/v1/multiple-virtual-try-on  (basket, 1-3 products)
+   ├─ Request: { reference_image, ... } (flat for single, { products: [...] } for multiple)
+   ├─ Response: { process_id, status: "pending" }
+   └─ 429 TRY_ON_LIMIT_EXCEEDED when the per-user+SKU limit is exhausted
+
+2. GET ?endpoint=job-status&process_id=... → /api/v1/process/{process_id}
+   ├─ Poll every 2 seconds (max 60 attempts single, 150 multiple)
    ├─ Status flow: pending → processing → completed | failed
-   └─ On completed: { status: "completed", multiple: [...] }
+   └─ On completed: { result: { job_type, single | multiple }, tryon_limit, used_count }
+
+3. POST ?endpoint=event → /api/v1/try-on-event        (conversion tracking, logged-in only)
+   └─ Request: { sku, event_name } — e.g. ADD_TO_CART, PURCHASE
 
-3. POST /api/v1/feedback
+4. PUT ?endpoint=feedback → /api/v1/feedback
    ├─ Request: { url: generated_image_url, feedback: boolean }
    └─ Submit per product independently
 ```
 
-### Hook Usage: `useVirtualTryOnMultiple`
+The limit is counted per **user + SKU** on the backend (only successful try-ons count, it never resets). The frontend never decrements anything — it only reads `used_count`/`tryon_limit` for UX (blocking toast on PDP, disabled products in the basket selector, info line in result modals).
+
+### Hook Usage: `useVirtualTryOnAsync`
 
 ```tsx
-import { useVirtualTryOnMultiple } from '@akinon/pz-virtual-try-on';
+import { useVirtualTryOnAsync } from '@akinon/pz-virtual-try-on';
 
 function MyMultipleTryOn({ products }) {
   const {
@@ -2189,7 +2211,7 @@ function MyMultipleTryOn({ products }) {
     submitFeedbackForResult,
     reset,
     retry
-  } = useVirtualTryOnMultiple(products);
+  } = useVirtualTryOnAsync(products);
 
   return (
     <div>
@@ -2210,7 +2232,7 @@ function MyMultipleTryOn({ products }) {
       {isProcessing && (
         <div>
           <p>Status: {jobStatus}</p>
-          <p>Attempt: {pollingAttempts} / 60</p>
+          <p>Attempt: {pollingAttempts} / 150</p>
         </div>
       )}
 
@@ -2267,31 +2289,45 @@ if (hasCompatibilityError(result)) {
 // - empty: No person detected
 ```
 
+The current API also returns a generic `INCOMPATIBLE` code whose `detail` carries a
+pipe-separated, already-localized message (`"FACE_NOT_VISIBLE|Lütfen yüzünüzün net
+göründüğü bir fotoğraf kullanın"`). Use `parseVirtualTryOnError` to extract the
+user-facing part after the pipe — all built-in views already do this.
+
+```tsx
+import { parseVirtualTryOnError } from '@akinon/pz-virtual-try-on';
+
+parseVirtualTryOnError('FACE_NOT_VISIBLE|Lütfen yüzünüzün net göründüğü bir fotoğraf kullanın');
+// → "Lütfen yüzünüzün net göründüğü bir fotoğraf kullanın"
+```
+
 ### Polling Control
 
 ```tsx
 import { VirtualTryOnPoller } from '@akinon/pz-virtual-try-on';
 
 const poller = new VirtualTryOnPoller({
-  referenceUrl: 'https://...',
-  maxAttempts: 60,
-  interval: 1000, // 1 second
+  referenceUrl: processId, // process_id returned by the start endpoint
+  maxAttempts: 150, // 60 for single, 150 for multiple (2s interval)
+  interval: 2000, // 2 seconds
   onStatusChange: (status, attempts) => {
     console.log(`Status: ${status}, Attempt: ${attempts}`);
   },
   onComplete: (result) => {
-    console.log('Completed!', result.multiple);
+    console.log('Completed!', result.result);
   },
   onError: (error) => {
     console.error('Failed:', error);
   },
   onTimeout: () => {
-    console.warn('Timeout after 60 attempts');
+    console.warn('Timeout after max attempts');
   }
 });
 
-await poller.start(async (url) => {
-  const response = await fetch(`/api/v1/async/job_status?reference_url=${url}`);
+await poller.start(async (processId) => {
+  const response = await fetch(
+    `/api/virtual-try-on?endpoint=job-status&process_id=${processId}`
+  );
   return response.json();
 });
 
@@ -2299,6 +2335,43 @@ await poller.start(async (url) => {
 poller.stop();
 ```
 
+### Usage Limits & Event Tracking
+
+The backend enforces a per-**user + SKU** try-on limit (`tryon_limit`; `0` means
+unlimited). Only successful try-ons increment `used_count` and the counter never
+resets. Built-in behavior:
+
+- **PDP button click**: usage is pre-checked for everyone. Guests get redirected
+  to `/users/auth` when the limit feature is active (400 `VALIDATION`); logged-in
+  users whose limit is exhausted see a toast (`product.virtual_try_on.limit_exceeded`
+  locale key) and the modal never opens.
+- **Basket selector**: SKUs with `used_count >= tryon_limit` render disabled
+  (`productSelectorProductItemDisabled` style target).
+- **Start endpoints**: a 429 `TRY_ON_LIMIT_EXCEEDED` from the backend is surfaced
+  through the normal error UI with the backend-localized message.
+
+```tsx
+import {
+  useGetTryOnUsageMutation,
+  useSubmitTryOnEventMutation
+} from '@akinon/pz-virtual-try-on';
+
+// Pre-check remaining rights for a set of SKUs
+const [getTryOnUsage] = useGetTryOnUsageMutation();
+const usage = await getTryOnUsage({ skus: ['SKU-1', 'SKU-2'] }).unwrap();
+// { tryon_limit: 2, skus: [{ sku: 'SKU-1', used_count: 1 }, ...] }
+
+// Track conversion events for previously tried-on products (logged-in users only)
+const [submitTryOnEvent] = useSubmitTryOnEventMutation();
+await submitTryOnEvent({ sku: 'SKU-1', event_name: 'ADD_TO_CART' }).unwrap();
+// Suggested event names: ADD_TO_CART, PURCHASE, VIEW_VARIANT, ADD_TO_WISHLIST,
+// SHARE, REMOVE_FROM_CART
+```
+
+Identity headers are injected by the Next.js proxy server-side — `X-Session-Id`
+from the `osessionid` cookie and `X-User-Id` from the NextAuth session `user.pk`.
+Client code never sends them manually.
+
 ### Limited Categories Caching
 
 ```tsx

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@akinon/pz-virtual-try-on",
-  "version": "2.0.34-beta.0",
+  "version": "2.0.34",
   "license": "MIT",
   "main": "src/index.ts",
   "peerDependencies": {
+    "next-auth": "^5.0.0-beta",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/next": "2.0.34-beta.0",
+    "@akinon/next": "2.0.34",
     "clsx": "^2.0.0",
     "tailwind-merge": "^2.0.0",
     "react-image-crop": "^11.0.5",

package/src/data/endpoints.ts

@@ -7,13 +7,27 @@ import type {
   VirtualTryOnAsyncRequest,
   VirtualTryOnAsyncProduct,
   VirtualTryOnAsyncResponse,
-  VirtualTryOnJobStatusResponse
+  VirtualTryOnJobStatusResponse,
+  TryOnUsageResponse,
+  TryOnEventResponse
 } from '../types';
 
 export const virtualTryOnApi = api.injectEndpoints({
   endpoints: (build) => ({
     // ==================== ASYNC API (SINGLE & MULTIPLE) ====================
 
+    // Start async virtual try-on process for a single product
+    virtualTryOnSingle: build.mutation<
+      VirtualTryOnAsyncResponse,
+      VirtualTryOnRequest
+    >({
+      query: (requestData) => ({
+        url: '/api/virtual-try-on?endpoint=single-try-on',
+        method: 'POST',
+        body: requestData
+      })
+    }),
+
     // Start async virtual try-on process
     // Supports 1-3 products (always uses multiple endpoint)
     virtualTryOnAsync: build.mutation<
@@ -21,7 +35,7 @@ export const virtualTryOnApi = api.injectEndpoints({
       VirtualTryOnAsyncRequest
     >({
       query: (requestData) => ({
-        url: '/api/virtual-try-on?endpoint=async-multiple-try-on',
+        url: '/api/virtual-try-on?endpoint=multiple-try-on',
         method: 'POST',
         body: requestData
       })
@@ -30,16 +44,41 @@ export const virtualTryOnApi = api.injectEndpoints({
     // Get job status for async process (polling endpoint)
     getVirtualTryOnJobStatus: build.query<
       VirtualTryOnJobStatusResponse,
-      string // reference_url
+      string // process_id
     >({
-      query: (referenceUrl) => ({
-        url: `/api/virtual-try-on?endpoint=job-status&reference_url=${encodeURIComponent(referenceUrl)}`,
+      query: (processId) => ({
+        url: `/api/virtual-try-on?endpoint=job-status&process_id=${encodeURIComponent(
+          processId
+        )}`,
         method: 'GET'
       }),
       // Don't cache - used for polling
       keepUnusedDataFor: 0
     }),
 
+    // ==================== USAGE & EVENTS ====================
+
+    // Get try-on usage counts for given SKUs
+    getTryOnUsage: build.mutation<TryOnUsageResponse, { skus: string[] }>({
+      query: (body) => ({
+        url: '/api/virtual-try-on?endpoint=usage',
+        method: 'POST',
+        body
+      })
+    }),
+
+    // Track try-on related events (add to cart, purchase, etc.)
+    submitTryOnEvent: build.mutation<
+      TryOnEventResponse,
+      { sku: string; event_name: string }
+    >({
+      query: (body) => ({
+        url: '/api/virtual-try-on?endpoint=event',
+        method: 'POST',
+        body
+      })
+    }),
+
     // ==================== FEEDBACK & CATEGORIES ====================
 
     // Submit feedback for try-on result
@@ -76,12 +115,18 @@ export const virtualTryOnApi = api.injectEndpoints({
 });
 
 export const {
+  // Async API (single product)
+  useVirtualTryOnSingleMutation,
   // Async API (single & multiple products, 1-3 products)
   useVirtualTryOnAsyncMutation,
   // Job status polling
   useGetVirtualTryOnJobStatusQuery,
   useLazyGetVirtualTryOnJobStatusQuery,
 
+  // Usage & events
+  useGetTryOnUsageMutation,
+  useSubmitTryOnEventMutation,
+
   // Common endpoints
   useGetVirtualTryOnLimitedCategoriesQuery,
   useSubmitVirtualTryOnFeedbackMutation