@proveanything/smartlinks 1.13.11 → 1.13.13

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.11  |  Generated: 2026-05-13T07:57:31.015Z
+Version: 1.13.13  |  Generated: 2026-05-15T11:06:27.909Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3024,11 +3024,31 @@ interface EmailVerifyTokenResponse {
 }
 ```
 
+**WhatsAppReplyCta** (interface)
+```typescript
+interface WhatsAppReplyCta {
+  body: string
+  buttonLabel: string
+  buttonUrl: string
+}
+```
+
+**WhatsAppReplyOptions** (interface)
+```typescript
+interface WhatsAppReplyOptions {
+  contentSid?: string
+  contentVariables?: Record<string, unknown>
+  cta?: WhatsAppReplyCta
+  text?: string
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber?: string
   redirectUrl?: string
+  prefillMessage?: string
+  reply?: WhatsAppReplyOptions
 }
 ```
 
@@ -3038,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 {
@@ -8201,6 +8232,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

@@ -88,15 +88,30 @@ import { authKit } from '@proveanything/smartlinks';
 // 1) Send WhatsApp verification deep link
 const wa = await authKit.sendWhatsApp(clientId);
 
-// Optional: pass redirect context only
+// 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.",
+//       buttonLabel: 'Back to Auction',
+//       buttonUrl: '{{returnUrl}}',
+//     },
+//     text: "You're verified. Return to the app to continue.",
+//   },
 // });
 
 // wa.waLink can be opened directly by the app/browser
 // 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');
 
@@ -135,6 +150,40 @@ Verification status values returned by `authKit.getWhatsAppStatus` are:
 - `expired`
 - `unknown`
 
+#### Post-verification reply
+
+Pass a `reply` object in `sendWhatsApp` to send a message back to the user after they confirm `CONFIRM <token>`. Reply resolution order:
+
+1. `reply.contentSid` — explicit Twilio Content SID
+2. `reply.cta` — CTA shorthand using the shared generic Twilio Content template SID (`TWILIO_WHATSAPP_GENERIC_CTA_SID`)
+3. `reply.text` — plain-text fallback
+4. Per-client default (`authKit/{clientId}.whatsapp` config)
+5. Built-in default text
+
+The following template placeholders are available in `reply.text`, `reply.cta` fields, and `reply.contentVariables` values:
+
+| Placeholder | Description |
+|---|---|
+| `{{returnUrl}}` | The resolved redirect URL |
+| `{{phoneNumber}}` | The verified phone number |
+| `{{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
 
 ```ts

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:
@@ -17864,13 +17890,40 @@ components:
       required:
         - success
         - message
-    SendWhatsAppRequest:
+    WhatsAppReplyCta:
       type: object
       properties:
-        phoneNumber:
+        body:
+          type: string
+        buttonLabel:
+          type: string
+        buttonUrl:
+          type: string
+      required:
+        - body
+        - buttonLabel
+        - buttonUrl
+    WhatsAppReplyOptions:
+      type: object
+      properties:
+        contentSid:
+          type: string
+        contentVariables:
+          type: object
+          additionalProperties: true
+        cta:
+          $ref: "#/components/schemas/WhatsAppReplyCta"
+        text:
           type: string
+    SendWhatsAppRequest:
+      type: object
+      properties:
         redirectUrl:
           type: string
+        prefillMessage:
+          type: string
+        reply:
+          $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
       type: object
       properties:
@@ -17880,6 +17933,8 @@ components:
           type: string
         token:
           type: string
+        sessionKey:
+          type: string
         expiresAt:
           type: string
       required:
@@ -17887,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:

package/dist/types/authKit.d.ts

@@ -76,16 +76,38 @@ export interface EmailVerifyTokenResponse {
     emailVerificationMode?: 'immediate' | 'verify-auto-login' | 'verify-manual-login';
 }
 export type VerifyStatus = 'pending' | 'verified' | 'failed' | 'expired' | 'unknown';
+export interface WhatsAppReplyCta {
+    body: string;
+    buttonLabel: string;
+    buttonUrl: string;
+}
+export interface WhatsAppReplyOptions {
+    /** Option A: explicit Twilio Content SID */
+    contentSid?: string;
+    contentVariables?: Record<string, unknown>;
+    /** Option B: CTA shorthand (uses shared generic CTA content SID) */
+    cta?: WhatsAppReplyCta;
+    /** Option C: plain-text fallback */
+    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/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.11  |  Generated: 2026-05-13T07:57:31.015Z
+Version: 1.13.13  |  Generated: 2026-05-15T11:06:27.909Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3024,11 +3024,31 @@ interface EmailVerifyTokenResponse {
 }
 ```
 
+**WhatsAppReplyCta** (interface)
+```typescript
+interface WhatsAppReplyCta {
+  body: string
+  buttonLabel: string
+  buttonUrl: string
+}
+```
+
+**WhatsAppReplyOptions** (interface)
+```typescript
+interface WhatsAppReplyOptions {
+  contentSid?: string
+  contentVariables?: Record<string, unknown>
+  cta?: WhatsAppReplyCta
+  text?: string
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber?: string
   redirectUrl?: string
+  prefillMessage?: string
+  reply?: WhatsAppReplyOptions
 }
 ```
 
@@ -3038,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 {
@@ -8201,6 +8232,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

@@ -88,15 +88,30 @@ import { authKit } from '@proveanything/smartlinks';
 // 1) Send WhatsApp verification deep link
 const wa = await authKit.sendWhatsApp(clientId);
 
-// Optional: pass redirect context only
+// 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.",
+//       buttonLabel: 'Back to Auction',
+//       buttonUrl: '{{returnUrl}}',
+//     },
+//     text: "You're verified. Return to the app to continue.",
+//   },
 // });
 
 // wa.waLink can be opened directly by the app/browser
 // 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');
 
@@ -135,6 +150,40 @@ Verification status values returned by `authKit.getWhatsAppStatus` are:
 - `expired`
 - `unknown`
 
+#### Post-verification reply
+
+Pass a `reply` object in `sendWhatsApp` to send a message back to the user after they confirm `CONFIRM <token>`. Reply resolution order:
+
+1. `reply.contentSid` — explicit Twilio Content SID
+2. `reply.cta` — CTA shorthand using the shared generic Twilio Content template SID (`TWILIO_WHATSAPP_GENERIC_CTA_SID`)
+3. `reply.text` — plain-text fallback
+4. Per-client default (`authKit/{clientId}.whatsapp` config)
+5. Built-in default text
+
+The following template placeholders are available in `reply.text`, `reply.cta` fields, and `reply.contentVariables` values:
+
+| Placeholder | Description |
+|---|---|
+| `{{returnUrl}}` | The resolved redirect URL |
+| `{{phoneNumber}}` | The verified phone number |
+| `{{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
 
 ```ts

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:
@@ -17864,13 +17890,40 @@ components:
       required:
         - success
         - message
-    SendWhatsAppRequest:
+    WhatsAppReplyCta:
       type: object
       properties:
-        phoneNumber:
+        body:
+          type: string
+        buttonLabel:
+          type: string
+        buttonUrl:
+          type: string
+      required:
+        - body
+        - buttonLabel
+        - buttonUrl
+    WhatsAppReplyOptions:
+      type: object
+      properties:
+        contentSid:
+          type: string
+        contentVariables:
+          type: object
+          additionalProperties: true
+        cta:
+          $ref: "#/components/schemas/WhatsAppReplyCta"
+        text:
           type: string
+    SendWhatsAppRequest:
+      type: object
+      properties:
         redirectUrl:
           type: string
+        prefillMessage:
+          type: string
+        reply:
+          $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
       type: object
       properties:
@@ -17880,6 +17933,8 @@ components:
           type: string
         token:
           type: string
+        sessionKey:
+          type: string
         expiresAt:
           type: string
       required:
@@ -17887,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:

package/package.json

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