@proveanything/smartlinks 1.13.12 → 1.13.14

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse } from "../types/authKit";
+import type { AuthLoginResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse } from "../types/authKit";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -33,6 +33,8 @@ export declare namespace authKit {
     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>;
+    /** Exchange a verified WhatsApp token for an Auth Kit session (public). */
+    function exchangeWhatsAppSession(clientId: string, token: string, sessionKey: string): Promise<ExchangeWhatsAppSessionResponse>;
     /** Send an SMS click-to-verify link (public). */
     function sendSmsVerify(clientId: string, body: SendSmsVerifyRequest): Promise<SendSmsVerifyResponse>;
     /** Verify an SMS click-to-verify token via API (public). */

package/dist/api/authKit.js

@@ -62,6 +62,11 @@ export var authKit;
         return request(`/authkit/${encodeURIComponent(clientId)}/auth/whatsapp/status?token=${encodedToken}`);
     }
     authKit.getWhatsAppStatus = getWhatsAppStatus;
+    /** Exchange a verified WhatsApp token for an Auth Kit session (public). */
+    async function exchangeWhatsAppSession(clientId, token, sessionKey) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/auth/whatsapp/exchange-session`, { token, sessionKey });
+    }
+    authKit.exchangeWhatsAppSession = exchangeWhatsAppSession;
     /** Send an SMS click-to-verify link (public). */
     async function sendSmsVerify(clientId, body) {
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/sms/send`, body);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.12  |  Generated: 2026-05-14T16:00:33.063Z
+Version: 1.13.14  |  Generated: 2026-05-15T11:37:00.944Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3046,8 +3046,8 @@ interface WhatsAppReplyOptions {
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber?: string
   redirectUrl?: string
+  prefillMessage?: string
   reply?: WhatsAppReplyOptions
 }
 ```
@@ -3058,10 +3058,21 @@ interface SendWhatsAppResponse {
   waLink: string
   code: string
   token: string
+  sessionKey?: string
   expiresAt: string
 }
 ```
 
+**ExchangeWhatsAppSessionResponse** (interface)
+```typescript
+interface ExchangeWhatsAppSessionResponse {
+  success: boolean
+  token: string
+  user: AuthKitUser
+  accountData?: Record<string, any>
+}
+```
+
 **VerifyWhatsAppResponse** (interface)
 ```typescript
 interface VerifyWhatsAppResponse {
@@ -5129,7 +5140,9 @@ interface RouteChangeMessage {
   type: 'smartlinks-route-change';
   path: string;
   context: Record<string, string>;
-  state: Record<string, string>;
+  state: Record<string, string> & {
+  parentPath?: string;
+  };
   appId?: string;
 }
 ```
@@ -8221,6 +8234,9 @@ Manually verify WhatsApp token if inbound webhook path is unavailable (public).
 **getWhatsAppStatus**(clientId: string, token: string) → `Promise<WhatsAppStatusResponse>`
 Poll WhatsApp verification status for a token (public).
 
+**exchangeWhatsAppSession**(clientId: string, token: string, sessionKey: string) → `Promise<ExchangeWhatsAppSessionResponse>`
+Exchange a verified WhatsApp token for an Auth Kit session (public).
+
 **sendSmsVerify**(clientId: string, body: SendSmsVerifyRequest) → `Promise<SendSmsVerifyResponse>`
 Send an SMS click-to-verify link (public).
 

package/dist/docs/auth-kit.md

@@ -91,6 +91,7 @@ const wa = await authKit.sendWhatsApp(clientId);
 // Optional: pass redirect context and/or a post-verification reply
 // const wa = await authKit.sendWhatsApp(clientId, {
 //   redirectUrl: 'https://app.example.com/checkout/continue',
+//   prefillMessage: 'Please let me bid in this auction. Code: {{token}}',
 //   reply: {
 //     cta: {
 //       body: "You're verified and ready to bid.",
@@ -105,6 +106,12 @@ const wa = await authKit.sendWhatsApp(clientId);
 // Poll status while user switches to WhatsApp and back
 const status = await authKit.getWhatsAppStatus(clientId, wa.token);
 
+// Optional: exchange verified WhatsApp proof for an Auth Kit session
+if (status.status === 'verified' && wa.sessionKey) {
+  const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.sessionKey);
+  // session.token can be used as the authenticated bearer token
+}
+
 // Optional fallback path if webhook confirmation is unavailable
 await authKit.verifyWhatsApp(clientId, wa.token, '+447911123456');
 
@@ -162,6 +169,19 @@ The following template placeholders are available in `reply.text`, `reply.cta` f
 | `{{clientId}}` | The Auth Kit client ID |
 | `{{token}}` | The verification token |
 
+You can also set `prefillMessage` on `sendWhatsApp` to customize the text pre-filled in the `wa.me` deep link. If `{{token}}` is not present, the token is appended to the message.
+
+#### Session exchange after verification
+
+After polling returns `status === 'verified'`, exchange the verification proof for an Auth Kit login session:
+
+```ts
+const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.sessionKey!);
+// session: { success, token, user, accountData? }
+```
+
+`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.
 
 ### Google OAuth

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

@@ -308,6 +308,7 @@ Now that you understand the core concepts, see the implementation guides:
 - **[containers.md](./containers.md)** — Build full-page embedded experiences
 - **[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
 
 ---
 
@@ -316,4 +317,5 @@ Now that you understand the core concepts, see the implementation guides:
 - [theme.system.md](./theme.system.md) — Theming and CSS variables
 - [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
 - [manifests.md](./manifests.md) — App manifest configuration

package/dist/docs/iframe-responder.md

@@ -141,6 +141,8 @@ const responder = new smartlinks.IframeResponder({
 });
 ```
 
+If your app has hierarchical screens, include `state.parentPath` in each `smartlinks-route-change` message so the portal shell can treat its top back button as "up" navigation instead of exiting the embed. See the [Portal Back Button guide](portal-back-button.md) for the contract and recommended router pattern.
+
 ### Local Development Override
 
 ```typescript
@@ -377,7 +379,7 @@ The responder handles these message types from the iframe:
   type: 'smartlinks-route-change',
   path: '/products/wine-123',
   context: { collectionId: 'acme-wines', appId: 'warranty' },
-  state: { tab: 'details' }
+  state: { tab: 'details', parentPath: '/products' }
 }
 ```
 
@@ -439,6 +441,7 @@ import type {
 5. **Validate tokens** server-side for security
 6. **Set height dynamically** based on content using `onResize`
 7. **Sync routes** with parent navigation for better UX
+8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
 ## Troubleshooting
 
@@ -461,3 +464,7 @@ import type {
 - Verify cache storage option is supported (sessionStorage/localStorage)
 - Check browser storage isn't disabled
 - Clear cache and retry with `smartlinks.cache.clear()`
+
+### Portal back exits the app too early
+- Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
+- Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.

package/dist/docs/mpa.md

@@ -122,6 +122,8 @@ The parent SmartLinks platform embeds apps via iframe:
 
 Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed as URL query params and read via the iframe responder. See the [iframe Responder guide](iframe-responder.md) for the full context injection API.
 
+If the embedded app exposes nested screens, document its "up" navigation path with the [Portal Back Button guide](portal-back-button.md) so the shell's back button stays inside the app when appropriate.
+
 ---
 
 ## Related Guides
@@ -133,3 +135,4 @@ Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
 | [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
+| [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/dist/docs/overview.md

@@ -64,6 +64,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
+| **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
@@ -86,6 +87,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
+- **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 
 ---
 

package/dist/docs/portal-back-button.md

@@ -0,0 +1,95 @@
+# Portal Back Button
+
+> **For sub-app authors.** This guide explains how to make the portal's top back button behave like hierarchy-aware "up" navigation inside an embedded app.
+
+When a SmartLinks app is embedded inside the portal shell, the shell can render a top-level back button. By default that button exits the app entirely. That is correct for flat screens, but wrong for apps with internal hierarchy such as lists, detail pages, wizards, or nested checkout flows.
+
+This document describes the contract for telling the portal where "up" goes from the current screen so the shell can keep the app mounted and route to the correct parent screen instead of leaving the embed.
+
+## Why "up", not browser back
+
+Browser back replays history. If a user navigates `list -> item A -> list -> item B`, browser back can yo-yo between detail and list screens in a way that feels wrong for an app chrome back button.
+
+"Up" navigates the content hierarchy instead: `item B -> list -> exit app`. It is single-direction and idempotent. Only your app's router knows that hierarchy, so the portal cannot infer it on its own.
+
+## The contract
+
+When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+
+```ts
+window.parent.postMessage({
+  type: 'smartlinks-route-change',
+  path: '/items/123',
+  context: { collectionId: 'auction-2026', appId: 'auction' },
+  state: {
+    parentPath: '/items',
+  },
+  appId: 'auction',
+}, '*');
+```
+
+| `state.parentPath` value | Portal back-button behaviour |
+| --- | --- |
+| `'/items'` (or any string) | The portal posts `smartlinks-navigate` to the iframe with that path and keeps the app mounted. |
+| `''`, missing, or omitted | The portal falls back to the default behaviour and exits the app. |
+
+The portal only uses `parentPath` when it is present on the current route. Query-string changes, tab switches, and modal state should keep the same parent path.
+
+## Recommended pattern
+
+Keep the hierarchy mapping close to your route definitions:
+
+```ts
+const PARENTS: Record<string, (params: any) => string | null> = {
+  '/': () => null,
+  '/items': () => null,
+  '/items/:id': () => '/items',
+  '/items/:id/bid': ({ id }) => `/items/${id}`,
+  '/checkout': () => '/items',
+};
+
+export function getParentPath(pathname: string): string | null {
+  // Use your router's path matching here and return the parent route.
+  return null;
+}
+```
+
+Then emit `parentPath` whenever the route changes:
+
+```ts
+useDeepLinkSync({
+  getParentPath: ({ pathname }) => getParentPath(pathname),
+});
+```
+
+If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+
+## Receiving the up-message
+
+When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+
+```ts
+{
+  type: 'smartlinks-navigate',
+  appId: 'auction',
+  path: '/items',
+  params: {},
+  target: '_self',
+}
+```
+
+Your app should listen for that message and route accordingly. If your SDK release already includes the inbound `smartlinks-navigate` listener, this can be automatic; otherwise add a small `message` listener and call your router manually.
+
+## Reference
+
+`state` remains a general `Record<string, string>`. `parentPath` is a recognised optional convention, not a breaking protocol change.
+
+## FAQ
+
+**Do I need to push every query-param change as a navigation step?** No. `parentPath` is hierarchy, not history.
+
+**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+
+**Can I disable the portal back button on certain screens?** Not via this protocol. Use the existing `homeScope: 'entry'` portal behaviour if you need the shell back button suppressed.
+
+**What about an in-app back button?** Keep it if you want. The portal back is shell chrome; an in-content back is part of the app UI.

package/dist/openapi.yaml

@@ -8501,6 +8501,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/whatsapp/exchange-session:
+    post:
+      tags:
+        - authKit
+      summary: Exchange a verified WhatsApp token for an Auth Kit session (public).
+      operationId: authKit_exchangeWhatsAppSession
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangeWhatsAppSessionResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/whatsapp/send:
     post:
       tags:
@@ -17892,10 +17918,10 @@ components:
     SendWhatsAppRequest:
       type: object
       properties:
-        phoneNumber:
-          type: string
         redirectUrl:
           type: string
+        prefillMessage:
+          type: string
         reply:
           $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
@@ -17907,6 +17933,8 @@ components:
           type: string
         token:
           type: string
+        sessionKey:
+          type: string
         expiresAt:
           type: string
       required:
@@ -17914,6 +17942,22 @@ components:
         - code
         - token
         - expiresAt
+    ExchangeWhatsAppSessionResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+        token:
+          type: string
+        user:
+          $ref: "#/components/schemas/AuthKitUser"
+        accountData:
+          type: object
+          additionalProperties: true
+      required:
+        - success
+        - token
+        - user
     VerifyWhatsAppResponse:
       type: object
       properties:
@@ -20520,8 +20564,9 @@ components:
             type: string
         state:
           type: object
-          additionalProperties:
-            type: string
+          additionalProperties: true
+        parentPath:
+          type: string
         appId:
           type: string
       required:

package/dist/types/authKit.d.ts

@@ -91,16 +91,23 @@ export interface WhatsAppReplyOptions {
     text?: string;
 }
 export interface SendWhatsAppRequest {
-    phoneNumber?: string;
     redirectUrl?: string;
+    prefillMessage?: string;
     reply?: WhatsAppReplyOptions;
 }
 export interface SendWhatsAppResponse {
     waLink: string;
     code: string;
     token: string;
+    sessionKey?: string;
     expiresAt: string;
 }
+export interface ExchangeWhatsAppSessionResponse {
+    success: boolean;
+    token: string;
+    user: AuthKitUser;
+    accountData?: Record<string, any>;
+}
 export interface VerifyWhatsAppResponse {
     success: boolean;
     verified: boolean;

package/dist/types/iframeResponder.d.ts

@@ -38,7 +38,9 @@ export interface RouteChangeMessage {
     type: 'smartlinks-route-change';
     path: string;
     context: Record<string, string>;
-    state: Record<string, string>;
+    state: Record<string, string> & {
+        parentPath?: string;
+    };
     appId?: string;
 }
 export interface SmartlinksIframeMessage {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.12  |  Generated: 2026-05-14T16:00:33.063Z
+Version: 1.13.14  |  Generated: 2026-05-15T11:37:00.944Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3046,8 +3046,8 @@ interface WhatsAppReplyOptions {
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber?: string
   redirectUrl?: string
+  prefillMessage?: string
   reply?: WhatsAppReplyOptions
 }
 ```
@@ -3058,10 +3058,21 @@ interface SendWhatsAppResponse {
   waLink: string
   code: string
   token: string
+  sessionKey?: string
   expiresAt: string
 }
 ```
 
+**ExchangeWhatsAppSessionResponse** (interface)
+```typescript
+interface ExchangeWhatsAppSessionResponse {
+  success: boolean
+  token: string
+  user: AuthKitUser
+  accountData?: Record<string, any>
+}
+```
+
 **VerifyWhatsAppResponse** (interface)
 ```typescript
 interface VerifyWhatsAppResponse {
@@ -5129,7 +5140,9 @@ interface RouteChangeMessage {
   type: 'smartlinks-route-change';
   path: string;
   context: Record<string, string>;
-  state: Record<string, string>;
+  state: Record<string, string> & {
+  parentPath?: string;
+  };
   appId?: string;
 }
 ```
@@ -8221,6 +8234,9 @@ Manually verify WhatsApp token if inbound webhook path is unavailable (public).
 **getWhatsAppStatus**(clientId: string, token: string) → `Promise<WhatsAppStatusResponse>`
 Poll WhatsApp verification status for a token (public).
 
+**exchangeWhatsAppSession**(clientId: string, token: string, sessionKey: string) → `Promise<ExchangeWhatsAppSessionResponse>`
+Exchange a verified WhatsApp token for an Auth Kit session (public).
+
 **sendSmsVerify**(clientId: string, body: SendSmsVerifyRequest) → `Promise<SendSmsVerifyResponse>`
 Send an SMS click-to-verify link (public).
 

package/docs/auth-kit.md

@@ -91,6 +91,7 @@ const wa = await authKit.sendWhatsApp(clientId);
 // Optional: pass redirect context and/or a post-verification reply
 // const wa = await authKit.sendWhatsApp(clientId, {
 //   redirectUrl: 'https://app.example.com/checkout/continue',
+//   prefillMessage: 'Please let me bid in this auction. Code: {{token}}',
 //   reply: {
 //     cta: {
 //       body: "You're verified and ready to bid.",
@@ -105,6 +106,12 @@ const wa = await authKit.sendWhatsApp(clientId);
 // Poll status while user switches to WhatsApp and back
 const status = await authKit.getWhatsAppStatus(clientId, wa.token);
 
+// Optional: exchange verified WhatsApp proof for an Auth Kit session
+if (status.status === 'verified' && wa.sessionKey) {
+  const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.sessionKey);
+  // session.token can be used as the authenticated bearer token
+}
+
 // Optional fallback path if webhook confirmation is unavailable
 await authKit.verifyWhatsApp(clientId, wa.token, '+447911123456');
 
@@ -162,6 +169,19 @@ The following template placeholders are available in `reply.text`, `reply.cta` f
 | `{{clientId}}` | The Auth Kit client ID |
 | `{{token}}` | The verification token |
 
+You can also set `prefillMessage` on `sendWhatsApp` to customize the text pre-filled in the `wa.me` deep link. If `{{token}}` is not present, the token is appended to the message.
+
+#### Session exchange after verification
+
+After polling returns `status === 'verified'`, exchange the verification proof for an Auth Kit login session:
+
+```ts
+const session = await authKit.exchangeWhatsAppSession(clientId, wa.token, wa.sessionKey!);
+// session: { success, token, user, accountData? }
+```
+
+`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.
 
 ### Google OAuth

package/docs/building-react-components.md

@@ -308,6 +308,7 @@ Now that you understand the core concepts, see the implementation guides:
 - **[containers.md](./containers.md)** — Build full-page embedded experiences
 - **[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
 
 ---
 
@@ -316,4 +317,5 @@ Now that you understand the core concepts, see the implementation guides:
 - [theme.system.md](./theme.system.md) — Theming and CSS variables
 - [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
 - [manifests.md](./manifests.md) — App manifest configuration

package/docs/iframe-responder.md

@@ -141,6 +141,8 @@ const responder = new smartlinks.IframeResponder({
 });
 ```
 
+If your app has hierarchical screens, include `state.parentPath` in each `smartlinks-route-change` message so the portal shell can treat its top back button as "up" navigation instead of exiting the embed. See the [Portal Back Button guide](portal-back-button.md) for the contract and recommended router pattern.
+
 ### Local Development Override
 
 ```typescript
@@ -377,7 +379,7 @@ The responder handles these message types from the iframe:
   type: 'smartlinks-route-change',
   path: '/products/wine-123',
   context: { collectionId: 'acme-wines', appId: 'warranty' },
-  state: { tab: 'details' }
+  state: { tab: 'details', parentPath: '/products' }
 }
 ```
 
@@ -439,6 +441,7 @@ import type {
 5. **Validate tokens** server-side for security
 6. **Set height dynamically** based on content using `onResize`
 7. **Sync routes** with parent navigation for better UX
+8. **Set `parentPath`** for routes that have a meaningful parent screen in the app hierarchy
 
 ## Troubleshooting
 
@@ -461,3 +464,7 @@ import type {
 - Verify cache storage option is supported (sessionStorage/localStorage)
 - Check browser storage isn't disabled
 - Clear cache and retry with `smartlinks.cache.clear()`
+
+### Portal back exits the app too early
+- Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
+- Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.

package/docs/mpa.md

@@ -122,6 +122,8 @@ The parent SmartLinks platform embeds apps via iframe:
 
 Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed as URL query params and read via the iframe responder. See the [iframe Responder guide](iframe-responder.md) for the full context injection API.
 
+If the embedded app exposes nested screens, document its "up" navigation path with the [Portal Back Button guide](portal-back-button.md) so the shell's back button stays inside the app when appropriate.
+
 ---
 
 ## Related Guides
@@ -133,3 +135,4 @@ Context parameters (`collectionId`, `appId`, `productId`, `proofId`) are passed
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
 | [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
+| [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/docs/overview.md

@@ -64,6 +64,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
+| **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
@@ -86,6 +87,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
+- **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 
 ---
 

package/docs/portal-back-button.md

@@ -0,0 +1,95 @@
+# Portal Back Button
+
+> **For sub-app authors.** This guide explains how to make the portal's top back button behave like hierarchy-aware "up" navigation inside an embedded app.
+
+When a SmartLinks app is embedded inside the portal shell, the shell can render a top-level back button. By default that button exits the app entirely. That is correct for flat screens, but wrong for apps with internal hierarchy such as lists, detail pages, wizards, or nested checkout flows.
+
+This document describes the contract for telling the portal where "up" goes from the current screen so the shell can keep the app mounted and route to the correct parent screen instead of leaving the embed.
+
+## Why "up", not browser back
+
+Browser back replays history. If a user navigates `list -> item A -> list -> item B`, browser back can yo-yo between detail and list screens in a way that feels wrong for an app chrome back button.
+
+"Up" navigates the content hierarchy instead: `item B -> list -> exit app`. It is single-direction and idempotent. Only your app's router knows that hierarchy, so the portal cannot infer it on its own.
+
+## The contract
+
+When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+
+```ts
+window.parent.postMessage({
+  type: 'smartlinks-route-change',
+  path: '/items/123',
+  context: { collectionId: 'auction-2026', appId: 'auction' },
+  state: {
+    parentPath: '/items',
+  },
+  appId: 'auction',
+}, '*');
+```
+
+| `state.parentPath` value | Portal back-button behaviour |
+| --- | --- |
+| `'/items'` (or any string) | The portal posts `smartlinks-navigate` to the iframe with that path and keeps the app mounted. |
+| `''`, missing, or omitted | The portal falls back to the default behaviour and exits the app. |
+
+The portal only uses `parentPath` when it is present on the current route. Query-string changes, tab switches, and modal state should keep the same parent path.
+
+## Recommended pattern
+
+Keep the hierarchy mapping close to your route definitions:
+
+```ts
+const PARENTS: Record<string, (params: any) => string | null> = {
+  '/': () => null,
+  '/items': () => null,
+  '/items/:id': () => '/items',
+  '/items/:id/bid': ({ id }) => `/items/${id}`,
+  '/checkout': () => '/items',
+};
+
+export function getParentPath(pathname: string): string | null {
+  // Use your router's path matching here and return the parent route.
+  return null;
+}
+```
+
+Then emit `parentPath` whenever the route changes:
+
+```ts
+useDeepLinkSync({
+  getParentPath: ({ pathname }) => getParentPath(pathname),
+});
+```
+
+If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+
+## Receiving the up-message
+
+When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+
+```ts
+{
+  type: 'smartlinks-navigate',
+  appId: 'auction',
+  path: '/items',
+  params: {},
+  target: '_self',
+}
+```
+
+Your app should listen for that message and route accordingly. If your SDK release already includes the inbound `smartlinks-navigate` listener, this can be automatic; otherwise add a small `message` listener and call your router manually.
+
+## Reference
+
+`state` remains a general `Record<string, string>`. `parentPath` is a recognised optional convention, not a breaking protocol change.
+
+## FAQ
+
+**Do I need to push every query-param change as a navigation step?** No. `parentPath` is hierarchy, not history.
+
+**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+
+**Can I disable the portal back button on certain screens?** Not via this protocol. Use the existing `homeScope: 'entry'` portal behaviour if you need the shell back button suppressed.
+
+**What about an in-app back button?** Keep it if you want. The portal back is shell chrome; an in-content back is part of the app UI.

package/openapi.yaml

@@ -8501,6 +8501,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/whatsapp/exchange-session:
+    post:
+      tags:
+        - authKit
+      summary: Exchange a verified WhatsApp token for an Auth Kit session (public).
+      operationId: authKit_exchangeWhatsAppSession
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExchangeWhatsAppSessionResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/whatsapp/send:
     post:
       tags:
@@ -17892,10 +17918,10 @@ components:
     SendWhatsAppRequest:
       type: object
       properties:
-        phoneNumber:
-          type: string
         redirectUrl:
           type: string
+        prefillMessage:
+          type: string
         reply:
           $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
@@ -17907,6 +17933,8 @@ components:
           type: string
         token:
           type: string
+        sessionKey:
+          type: string
         expiresAt:
           type: string
       required:
@@ -17914,6 +17942,22 @@ components:
         - code
         - token
         - expiresAt
+    ExchangeWhatsAppSessionResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+        token:
+          type: string
+        user:
+          $ref: "#/components/schemas/AuthKitUser"
+        accountData:
+          type: object
+          additionalProperties: true
+      required:
+        - success
+        - token
+        - user
     VerifyWhatsAppResponse:
       type: object
       properties:
@@ -20520,8 +20564,9 @@ components:
             type: string
         state:
           type: object
-          additionalProperties:
-            type: string
+          additionalProperties: true
+        parentPath:
+          type: string
         appId:
           type: string
       required:

package/package.json

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