@proveanything/smartlinks 1.13.14 → 1.13.16

package/dist/api/authKit.d.ts

@@ -29,7 +29,7 @@ export declare namespace authKit {
     function verifyPhoneCode(clientId: string, phoneNumber: string, code: string): Promise<PhoneVerifyResponse>;
     /** Send a WhatsApp verification deep-link (public). */
     function sendWhatsApp(clientId: string, body?: SendWhatsAppRequest): Promise<SendWhatsAppResponse>;
-    /** Manually verify WhatsApp token if inbound webhook path is unavailable (public). */
+    /** Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback). */
     function verifyWhatsApp(clientId: string, token: string, phoneNumber: string): Promise<VerifyWhatsAppResponse>;
     /** Poll WhatsApp verification status for a token (public). */
     function getWhatsAppStatus(clientId: string, token: string): Promise<WhatsAppStatusResponse>;

package/dist/api/authKit.js

@@ -51,7 +51,7 @@ export var authKit;
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/whatsapp/send`, body);
     }
     authKit.sendWhatsApp = sendWhatsApp;
-    /** Manually verify WhatsApp token if inbound webhook path is unavailable (public). */
+    /** Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback). */
     async function verifyWhatsApp(clientId, token, phoneNumber) {
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/whatsapp/verify`, { token, phoneNumber });
     }

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.14  |  Generated: 2026-05-15T11:37:00.944Z
+Version: 1.13.16  |  Generated: 2026-05-15T19:36:34.712Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3043,12 +3043,27 @@ interface WhatsAppReplyOptions {
 }
 ```
 
+**WhatsAppContactData** (interface)
+```typescript
+interface WhatsAppContactData {
+  name?: string
+  firstName?: string
+  lastName?: string
+  displayName?: string
+  email?: string
+  source?: string
+  customFields?: Record<string, unknown>
+  externalIds?: Record<string, unknown>
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
   redirectUrl?: string
   prefillMessage?: string
   reply?: WhatsAppReplyOptions
+  contactData?: WhatsAppContactData
 }
 ```
 
@@ -8229,7 +8244,7 @@ Verify phone verification code (public).
 Send a WhatsApp verification deep-link (public).
 
 **verifyWhatsApp**(clientId: string, token: string, phoneNumber: string) → `Promise<VerifyWhatsAppResponse>`
-Manually verify WhatsApp token if inbound webhook path is unavailable (public).
+Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback).
 
 **getWhatsAppStatus**(clientId: string, token: string) → `Promise<WhatsAppStatusResponse>`
 Poll WhatsApp verification status for a token (public).

package/dist/docs/auth-kit.md

@@ -82,6 +82,8 @@ const session = await authKit.verifyPhoneCode(clientId, '+61400000000', '123456'
 
 Use these flows when you want low-friction verification before or without full account sign-in.
 
+WhatsApp verification is token-first. The user does not type their phone number in your app for this flow; phone ownership is proven by the inbound WhatsApp sender number.
+
 ```ts
 import { authKit } from '@proveanything/smartlinks';
 
@@ -92,6 +94,12 @@ const wa = await authKit.sendWhatsApp(clientId);
 // const wa = await authKit.sendWhatsApp(clientId, {
 //   redirectUrl: 'https://app.example.com/checkout/continue',
 //   prefillMessage: 'Please let me bid in this auction. Code: {{token}}',
+//   contactData: {
+//     name: 'Jane Doe',
+//     email: 'jane@example.com',
+//     source: 'auction-checkout',
+//     customFields: { agreedToTerms: true },
+//   },
 //   reply: {
 //     cta: {
 //       body: "You're verified and ready to bid.",
@@ -112,7 +120,7 @@ if (status.status === 'verified' && wa.sessionKey) {
   // session.token can be used as the authenticated bearer token
 }
 
-// Optional fallback path if webhook confirmation is unavailable
+// Optional legacy fallback path if webhook confirmation is unavailable
 await authKit.verifyWhatsApp(clientId, wa.token, '+447911123456');
 
 // 2) Or send SMS click-to-verify link
@@ -126,6 +134,13 @@ await authKit.sendSmsVerify(clientId, {
 await authKit.verifySms(clientId, '<token>', '+447911123456');
 ```
 
+`contactData` is optional and is useful when you collect name/email before the customer switches to WhatsApp.
+
+- Auth Kit stores `contactData` on the verification token metadata first.
+- Contact details are written to durable contact storage only after WhatsApp verification succeeds.
+- If the user abandons before verification, no contact is created.
+- `contactData` must not include phone; the verified inbound WhatsApp sender number is always authoritative.
+
 ### Contact bootstrap / durable identity
 
 After verification, upsert contact identity and store `contactId` on downstream records (raffle ticket, bid, claim intent).
@@ -183,6 +198,8 @@ const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.ses
 `sessionKey` is returned by `sendWhatsApp` and is used to mitigate token replay from contexts that did not initiate the browser flow.
 
 > **Note:** `redirectUrl` is optional. WhatsApp tokens are short hex strings (16 chars) for better UX.
+>
+> **Legacy note:** `verifyWhatsApp` is for older phone-bound token flows. Prefer inbound WhatsApp token confirmation plus status polling for new implementations.
 
 ### Google OAuth
 

package/dist/docs/building-react-components.md

@@ -309,6 +309,7 @@ Now that you understand the core concepts, see the implementation guides:
 - **[mpa.md](./mpa.md)** — Multi-page app architecture (optional)
 - **[iframe-responder.md](./iframe-responder.md)** — Parent-side iframe integration
 - **[portal-back-button.md](./portal-back-button.md)** — Embedded-app "up" navigation and portal back-button behaviour
+- **[portal-auth-broadcast.md](./portal-auth-broadcast.md)** — Publishing custom auth flows to the portal
 
 ---
 
@@ -318,4 +319,5 @@ Now that you understand the core concepts, see the implementation guides:
 - [ai.md](./ai.md) — AI assistant integration
 - [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
 - [portal-back-button.md](./portal-back-button.md) — Portal shell back-button behavior for hierarchical embeds
+- [portal-auth-broadcast.md](./portal-auth-broadcast.md) — Custom authentication and session broadcast
 - [manifests.md](./manifests.md) — App manifest configuration

package/dist/docs/overview.md

@@ -74,6 +74,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 

package/dist/docs/portal-auth-broadcast.md

@@ -0,0 +1,160 @@
+# Publishing Auth State to the Portal
+
+> **For sub-app authors.** This guide explains how to broadcast authentication state changes to the portal so the header, account UI, and sibling apps stay in sync.
+
+A SmartLinks micro-app may need to run its own custom authentication flow —
+typical cases: an auction app that calls a bidder API, a competition app
+that exchanges a magic code for a session, a partner SSO. When that flow
+completes the app holds a `token` + `user` of its own, and the **portal**
+needs to know about it so the header, the account UI, and every sibling
+app pick up the new session.
+
+This doc describes the contract the portal framework already implements.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These run inside the portal's React context and share its `AuthProvider`.
+Call `useAuth()` directly:
+
+```tsx
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+
+function BidButton() {
+  const { login, logout, isAuthenticated, user } = useAuth();
+
+  async function placeBid() {
+    if (!isAuthenticated) {
+      // Run your own auth flow…
+      const { token, user, expiresAt } = await api.signInBidder(...);
+      // Publish to the portal — this is the *only* call you need:
+      await login(token, user, { source: 'auction' }, /* isNewUser */ false, expiresAt);
+    }
+    await api.placeBid(...);
+  }
+
+  return <button onClick={placeBid}>Bid</button>;
+}
+```
+
+`useAuth().login(token, user, accountData?, isNewUser?, expiresAt?)` will:
+
+- Persist the session (cookie/storage as configured).
+- Call `setBearerToken(token)` on the SDK so subsequent API calls are
+  authenticated.
+- Re-render every consumer of `useAuth()` / `useSafeAuth()` —
+  including the portal header.
+
+`useAuth().logout()` clears all of the above.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context. Use the SDK's `authKit` helper —
+it posts the framework-recognised messages on `window.parent`:
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// After your custom flow succeeds:
+await authKit.publishLogin({
+  token,                // string — your API's bearer token
+  user: {               // mirrors AuthUser
+    uid: 'usr_123',
+    email: 'bidder@example.com',
+    displayName: 'Jane Bidder',
+  },
+  accountData: { tier: 'gold' }, // optional, free-form
+});
+
+// On sign-out:
+await authKit.publishLogout();
+```
+
+### Raw postMessage (fallback)
+
+If you can't use the helper (e.g. you're outside the SDK), post the raw
+messages from the iframe to its parent. The portal's `IframeResponder`
+listens for these:
+
+```ts
+// LOGIN
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login',
+  payload: {
+    token: '<bearer>',
+    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
+    accountData: { /* optional */ },
+  },
+}, '*');
+
+// LOGOUT
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:logout',
+  payload: {},
+}, '*');
+```
+
+The portal-framework's `AppIframeRenderer` translates these into:
+
+```ts
+PortalAuthProvider.login(token, user, accountData);
+// or
+PortalAuthProvider.logout();
+```
+
+— the **same** call the built-in `AuthModal` makes when the user logs in
+through the standard portal UI.
+
+---
+
+## What the Portal Does on Receipt
+
+1. Updates the `IframeResponder` cache so future context syncs carry the
+   user.
+2. Calls `PortalAuthProvider`'s bridged `login` / `logout`.
+3. `setBearerToken` runs against the parent SDK instance — your API
+   calls are now authenticated.
+4. The portal header avatar swaps in (or out).
+5. Every other container/widget/iframe app observes the new session via
+   its own `useAuth()` / context-refresh.
+
+---
+
+## Anti-Patterns
+
+❌ Storing your own auth token in `localStorage` and ignoring the portal —
+   the user will see a logged-out header above your "logged in" app.
+
+❌ Posting `smartlinks-auth-login` (with a hyphen). The correct event
+   name is `smartlinks:authkit:login` (colon-separated, namespaced).
+
+❌ Calling `setBearerToken` directly without notifying the portal —
+   your token will work until the portal next refreshes auth, then be
+   wiped.
+
+❌ Implementing logout by just clearing your own state. Always call
+   `useAuth().logout()` (container/widget) or `authKit.publishLogout()`
+   (iframe) so the whole portal session ends cleanly.
+
+---
+
+## Reading the Current Portal Session
+
+You don't need to broadcast just to *read* the session — that comes for
+free:
+
+```tsx
+// Container / widget apps
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+const { user, token, isAuthenticated } = useAuth();
+```
+
+```ts
+// Iframe apps — the IframeResponder caches the parent's user under
+// `cache.user`. Read it via the SDK's standard hooks/helpers.
+```

package/dist/openapi.yaml

@@ -8589,7 +8589,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: Manually verify WhatsApp token if inbound webhook path is unavailable (public).
+      summary: Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback).
       operationId: authKit_verifyWhatsApp
       security: []
       parameters:
@@ -17915,6 +17915,27 @@ components:
           $ref: "#/components/schemas/WhatsAppReplyCta"
         text:
           type: string
+    WhatsAppContactData:
+      type: object
+      properties:
+        name:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        displayName:
+          type: string
+        email:
+          type: string
+        source:
+          type: string
+        customFields:
+          type: object
+          additionalProperties: true
+        externalIds:
+          type: object
+          additionalProperties: true
     SendWhatsAppRequest:
       type: object
       properties:
@@ -17924,6 +17945,8 @@ components:
           type: string
         reply:
           $ref: "#/components/schemas/WhatsAppReplyOptions"
+        contactData:
+          $ref: "#/components/schemas/WhatsAppContactData"
     SendWhatsAppResponse:
       type: object
       properties:

package/dist/types/authKit.d.ts

@@ -90,10 +90,21 @@ export interface WhatsAppReplyOptions {
     /** Option C: plain-text fallback */
     text?: string;
 }
+export interface WhatsAppContactData {
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    email?: string;
+    source?: string;
+    customFields?: Record<string, unknown>;
+    externalIds?: Record<string, unknown>;
+}
 export interface SendWhatsAppRequest {
     redirectUrl?: string;
     prefillMessage?: string;
     reply?: WhatsAppReplyOptions;
+    contactData?: WhatsAppContactData;
 }
 export interface SendWhatsAppResponse {
     waLink: string;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.14  |  Generated: 2026-05-15T11:37:00.944Z
+Version: 1.13.16  |  Generated: 2026-05-15T19:36:34.712Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3043,12 +3043,27 @@ interface WhatsAppReplyOptions {
 }
 ```
 
+**WhatsAppContactData** (interface)
+```typescript
+interface WhatsAppContactData {
+  name?: string
+  firstName?: string
+  lastName?: string
+  displayName?: string
+  email?: string
+  source?: string
+  customFields?: Record<string, unknown>
+  externalIds?: Record<string, unknown>
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
   redirectUrl?: string
   prefillMessage?: string
   reply?: WhatsAppReplyOptions
+  contactData?: WhatsAppContactData
 }
 ```
 
@@ -8229,7 +8244,7 @@ Verify phone verification code (public).
 Send a WhatsApp verification deep-link (public).
 
 **verifyWhatsApp**(clientId: string, token: string, phoneNumber: string) → `Promise<VerifyWhatsAppResponse>`
-Manually verify WhatsApp token if inbound webhook path is unavailable (public).
+Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback).
 
 **getWhatsAppStatus**(clientId: string, token: string) → `Promise<WhatsAppStatusResponse>`
 Poll WhatsApp verification status for a token (public).

package/docs/auth-kit.md

@@ -82,6 +82,8 @@ const session = await authKit.verifyPhoneCode(clientId, '+61400000000', '123456'
 
 Use these flows when you want low-friction verification before or without full account sign-in.
 
+WhatsApp verification is token-first. The user does not type their phone number in your app for this flow; phone ownership is proven by the inbound WhatsApp sender number.
+
 ```ts
 import { authKit } from '@proveanything/smartlinks';
 
@@ -92,6 +94,12 @@ const wa = await authKit.sendWhatsApp(clientId);
 // const wa = await authKit.sendWhatsApp(clientId, {
 //   redirectUrl: 'https://app.example.com/checkout/continue',
 //   prefillMessage: 'Please let me bid in this auction. Code: {{token}}',
+//   contactData: {
+//     name: 'Jane Doe',
+//     email: 'jane@example.com',
+//     source: 'auction-checkout',
+//     customFields: { agreedToTerms: true },
+//   },
 //   reply: {
 //     cta: {
 //       body: "You're verified and ready to bid.",
@@ -112,7 +120,7 @@ if (status.status === 'verified' && wa.sessionKey) {
   // session.token can be used as the authenticated bearer token
 }
 
-// Optional fallback path if webhook confirmation is unavailable
+// Optional legacy fallback path if webhook confirmation is unavailable
 await authKit.verifyWhatsApp(clientId, wa.token, '+447911123456');
 
 // 2) Or send SMS click-to-verify link
@@ -126,6 +134,13 @@ await authKit.sendSmsVerify(clientId, {
 await authKit.verifySms(clientId, '<token>', '+447911123456');
 ```
 
+`contactData` is optional and is useful when you collect name/email before the customer switches to WhatsApp.
+
+- Auth Kit stores `contactData` on the verification token metadata first.
+- Contact details are written to durable contact storage only after WhatsApp verification succeeds.
+- If the user abandons before verification, no contact is created.
+- `contactData` must not include phone; the verified inbound WhatsApp sender number is always authoritative.
+
 ### Contact bootstrap / durable identity
 
 After verification, upsert contact identity and store `contactId` on downstream records (raffle ticket, bid, claim intent).
@@ -183,6 +198,8 @@ const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.ses
 `sessionKey` is returned by `sendWhatsApp` and is used to mitigate token replay from contexts that did not initiate the browser flow.
 
 > **Note:** `redirectUrl` is optional. WhatsApp tokens are short hex strings (16 chars) for better UX.
+>
+> **Legacy note:** `verifyWhatsApp` is for older phone-bound token flows. Prefer inbound WhatsApp token confirmation plus status polling for new implementations.
 
 ### Google OAuth
 

package/docs/building-react-components.md

@@ -309,6 +309,7 @@ Now that you understand the core concepts, see the implementation guides:
 - **[mpa.md](./mpa.md)** — Multi-page app architecture (optional)
 - **[iframe-responder.md](./iframe-responder.md)** — Parent-side iframe integration
 - **[portal-back-button.md](./portal-back-button.md)** — Embedded-app "up" navigation and portal back-button behaviour
+- **[portal-auth-broadcast.md](./portal-auth-broadcast.md)** — Publishing custom auth flows to the portal
 
 ---
 
@@ -318,4 +319,5 @@ Now that you understand the core concepts, see the implementation guides:
 - [ai.md](./ai.md) — AI assistant integration
 - [deep-link-discovery.md](./deep-link-discovery.md) — Deep linking patterns
 - [portal-back-button.md](./portal-back-button.md) — Portal shell back-button behavior for hierarchical embeds
+- [portal-auth-broadcast.md](./portal-auth-broadcast.md) — Custom authentication and session broadcast
 - [manifests.md](./manifests.md) — App manifest configuration

package/docs/overview.md

@@ -74,6 +74,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
 | **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
 | **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 

package/docs/portal-auth-broadcast.md

@@ -0,0 +1,160 @@
+# Publishing Auth State to the Portal
+
+> **For sub-app authors.** This guide explains how to broadcast authentication state changes to the portal so the header, account UI, and sibling apps stay in sync.
+
+A SmartLinks micro-app may need to run its own custom authentication flow —
+typical cases: an auction app that calls a bidder API, a competition app
+that exchanges a magic code for a session, a partner SSO. When that flow
+completes the app holds a `token` + `user` of its own, and the **portal**
+needs to know about it so the header, the account UI, and every sibling
+app pick up the new session.
+
+This doc describes the contract the portal framework already implements.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These run inside the portal's React context and share its `AuthProvider`.
+Call `useAuth()` directly:
+
+```tsx
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+
+function BidButton() {
+  const { login, logout, isAuthenticated, user } = useAuth();
+
+  async function placeBid() {
+    if (!isAuthenticated) {
+      // Run your own auth flow…
+      const { token, user, expiresAt } = await api.signInBidder(...);
+      // Publish to the portal — this is the *only* call you need:
+      await login(token, user, { source: 'auction' }, /* isNewUser */ false, expiresAt);
+    }
+    await api.placeBid(...);
+  }
+
+  return <button onClick={placeBid}>Bid</button>;
+}
+```
+
+`useAuth().login(token, user, accountData?, isNewUser?, expiresAt?)` will:
+
+- Persist the session (cookie/storage as configured).
+- Call `setBearerToken(token)` on the SDK so subsequent API calls are
+  authenticated.
+- Re-render every consumer of `useAuth()` / `useSafeAuth()` —
+  including the portal header.
+
+`useAuth().logout()` clears all of the above.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context. Use the SDK's `authKit` helper —
+it posts the framework-recognised messages on `window.parent`:
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// After your custom flow succeeds:
+await authKit.publishLogin({
+  token,                // string — your API's bearer token
+  user: {               // mirrors AuthUser
+    uid: 'usr_123',
+    email: 'bidder@example.com',
+    displayName: 'Jane Bidder',
+  },
+  accountData: { tier: 'gold' }, // optional, free-form
+});
+
+// On sign-out:
+await authKit.publishLogout();
+```
+
+### Raw postMessage (fallback)
+
+If you can't use the helper (e.g. you're outside the SDK), post the raw
+messages from the iframe to its parent. The portal's `IframeResponder`
+listens for these:
+
+```ts
+// LOGIN
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login',
+  payload: {
+    token: '<bearer>',
+    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
+    accountData: { /* optional */ },
+  },
+}, '*');
+
+// LOGOUT
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:logout',
+  payload: {},
+}, '*');
+```
+
+The portal-framework's `AppIframeRenderer` translates these into:
+
+```ts
+PortalAuthProvider.login(token, user, accountData);
+// or
+PortalAuthProvider.logout();
+```
+
+— the **same** call the built-in `AuthModal` makes when the user logs in
+through the standard portal UI.
+
+---
+
+## What the Portal Does on Receipt
+
+1. Updates the `IframeResponder` cache so future context syncs carry the
+   user.
+2. Calls `PortalAuthProvider`'s bridged `login` / `logout`.
+3. `setBearerToken` runs against the parent SDK instance — your API
+   calls are now authenticated.
+4. The portal header avatar swaps in (or out).
+5. Every other container/widget/iframe app observes the new session via
+   its own `useAuth()` / context-refresh.
+
+---
+
+## Anti-Patterns
+
+❌ Storing your own auth token in `localStorage` and ignoring the portal —
+   the user will see a logged-out header above your "logged in" app.
+
+❌ Posting `smartlinks-auth-login` (with a hyphen). The correct event
+   name is `smartlinks:authkit:login` (colon-separated, namespaced).
+
+❌ Calling `setBearerToken` directly without notifying the portal —
+   your token will work until the portal next refreshes auth, then be
+   wiped.
+
+❌ Implementing logout by just clearing your own state. Always call
+   `useAuth().logout()` (container/widget) or `authKit.publishLogout()`
+   (iframe) so the whole portal session ends cleanly.
+
+---
+
+## Reading the Current Portal Session
+
+You don't need to broadcast just to *read* the session — that comes for
+free:
+
+```tsx
+// Container / widget apps
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+const { user, token, isAuthenticated } = useAuth();
+```
+
+```ts
+// Iframe apps — the IframeResponder caches the parent's user under
+// `cache.user`. Read it via the SDK's standard hooks/helpers.
+```

package/openapi.yaml

@@ -8589,7 +8589,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: Manually verify WhatsApp token if inbound webhook path is unavailable (public).
+      summary: Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback).
       operationId: authKit_verifyWhatsApp
       security: []
       parameters:
@@ -17915,6 +17915,27 @@ components:
           $ref: "#/components/schemas/WhatsAppReplyCta"
         text:
           type: string
+    WhatsAppContactData:
+      type: object
+      properties:
+        name:
+          type: string
+        firstName:
+          type: string
+        lastName:
+          type: string
+        displayName:
+          type: string
+        email:
+          type: string
+        source:
+          type: string
+        customFields:
+          type: object
+          additionalProperties: true
+        externalIds:
+          type: object
+          additionalProperties: true
     SendWhatsAppRequest:
       type: object
       properties:
@@ -17924,6 +17945,8 @@ components:
           type: string
         reply:
           $ref: "#/components/schemas/WhatsAppReplyOptions"
+        contactData:
+          $ref: "#/components/schemas/WhatsAppContactData"
     SendWhatsAppResponse:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.13.14",
+  "version": "1.13.16",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",