@souldi/try-on 0.1.93 → 0.2.0

package/README.md

@@ -86,10 +86,13 @@ Call once per page load to configure the widget.
 | `tenantApiKey` | `string` | Yes | Your publishable API key (from your Souldi dashboard) |
 | `theme` | `object` | No | Customize the widget appearance ([see Theming](#theming)) |
 | `onGenerationStart` | `function(info)` | No | Called when AI generation begins |
-| `onGenerationSuccess` | `function(resultUrl, info)` | No | Called with the result image URL on success |
+| `onGenerationSuccess` | `function(resultUrl, info)` | No | Called with the result image URL once generation *produces* a result — before the image has loaded or been seen |
+| `onResultShown` | `function(info)` | No | Called once the result image has actually **loaded and is visible** in the widget's dialog. Never fires if the image fails to load, and never fires twice for the same result ([details](#the-info-argument)) |
 | `onError` | `function(message, info)` | No | Called when something goes wrong |
 | `onLogout` | `function` | No | Called when the user's session ends — by logout, or by a token the backend no longer honours |
+| `onSignedIn` | `function(info)` | No | Called whenever a session begins for this tab — a code verified here, a session shared from another tab, or a stored session restored ([details](#the-info-argument)) |
 | `onAuthPrompt` | `function` | No | Called just before the widget takes the screen to ask the user to sign in |
+| `onPhotoReady` | `function(info)` | No | Called once a shopper's base photo clears preprocessing and is promoted — not fired for a rejected photo ([details](#the-info-argument)) |
 | `onAddToCart` | `async function(intent)` | No | Called when the customer asks to add their recommended size to your cart. Absent, no cart control is drawn anywhere ([details](#onaddtocart)) |
 
 #### The `info` argument
@@ -98,8 +101,12 @@ Callbacks about a specific try-on receive a trailing `info` object:
 
 | Field | Type | Present on | Description |
 |-------|------|-----------|-------------|
-| `buttonId` | `string` | all three | The `containerId` of the button this callback is about |
-| `operation` | `'generate' \| 'refine'` | `onError` | Which operation failed |
+| `buttonId` | `string` | most | The `containerId` of the button this callback is about |
+| `operation` | `'generate' \| 'refine'` | `onError`, `onResultShown` | Which operation this is about |
+| `view` | `string \| null` | `onGenerationSuccess`, `onResultShown` | The Render View this result is (e.g. `'front'`), when the garment offers more than one |
+| `how` | `'verified' \| 'shared' \| 'restored'` | `onSignedIn` | How this tab's session began. Only `'verified'` is a *new* sign-in — `'shared'` and `'restored'` are this tab catching up with a session that began elsewhere |
+| `resolution` | `string` | `onPhotoReady` | The preprocessing outcome, e.g. `'clean'` or `'soft-issue'` |
+| `isRetake` | `boolean` | `onPhotoReady` | Whether this photo replaced an existing one |
 
 `buttonId` matters as soon as a page has more than one try-on button: without it
 you cannot tell which button's job just finished, and a result can only be
@@ -114,15 +121,32 @@ request against an older one is reported here rather than silently dropped.
 Present it wherever you collected the instruction; the previous result is
 untouched either way.
 
+`onResultShown` receives the same `info` `onGenerationSuccess` did for that
+result, minus the image URL — it is about the same render, just reported once
+the pixels are actually on screen. If the image never loads, `onResultShown`
+simply never fires; nothing else changes for the shopper.
+
 `onLogout` deliberately carries no `buttonId` — a session ends for the whole
 page, and every result surface on it must be torn down. If you render results
 yourself, this is where you drop them: the result URL is signed, user-specific,
 and must not outlive the session.
 
+`onSignedIn` is the mirror of `onLogout`: a session BEGAN for this tab. Use
+`info.how` to tell a shopper's own sign-in (`'verified'`) apart from this tab
+merely adopting a session that already existed (`'shared'`, `'restored'`) —
+only the first is a new sign-in for funnel purposes.
+
 `onAuthPrompt` fires before the widget's own sign-in card opens. Use it to move
 anything of yours that would cover it (a modal, a lightbox) out of the way. It
 says nothing about whether the previous session ended — that is `onLogout`.
 
+`onPhotoReady` fires once per promoted photo — on first upload and on a
+retake, from both the desktop upload and the phone-QR upload paths — and never
+for a rejected photo, since nothing was promoted for it to report.
+
+None of the payloads above ever carry an image URL, an auth token, an email
+address, or body measurements.
+
 #### `onAddToCart`
 
 The widget knows a customer's size; only you know your cart. Supply