@proveanything/smartlinks 1.14.15 → 1.14.16

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse } from "../types/authKit";
+import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, 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*).
@@ -35,6 +35,35 @@ export declare namespace authKit {
      * @see AppleLoginOptions
      */
     function appleLogin(clientId: string, identityToken: string, opts?: AppleLoginOptions): Promise<AuthLoginResponse>;
+    /**
+     * Exchange a refresh token for a fresh access token (public — the refresh token IS
+     * the credential). **Native sessions only**; refresh tokens are issued only when the
+     * host opted in via `initializeApi({ platform: 'native' })`.
+     *
+     * On success the new access token is stored automatically (`setBearerToken`). The
+     * returned `refreshToken` is **rotated** — the caller must persist it and discard the
+     * old one before refreshing again.
+     *
+     * ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request
+     * and never retries: replaying a consumed refresh token triggers
+     * `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is
+     * responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or
+     * resume events).
+     *
+     * Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`):
+     * `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401),
+     * `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
+     *
+     * @see RefreshErrorCode
+     */
+    function refreshToken(clientId: string, refreshToken: string): Promise<RefreshResponse>;
+    /**
+     * Revoke a refresh token's entire family server-side (that device's whole rotation
+     * chain) and clear the in-memory bearer token. Idempotent — always resolves to
+     * `{ success: true }`, never revealing whether the token existed. Call on explicit
+     * sign-out. Persisted tokens in the host's own storage must be cleared separately.
+     */
+    function logout(clientId: string, refreshToken: string): Promise<LogoutResponse>;
     /** Send a magic link email to the user (public). */
     function sendMagicLink(clientId: string, data: {
         email: string;

package/dist/api/authKit.js

@@ -70,6 +70,52 @@ export var authKit;
         return res;
     }
     authKit.appleLogin = appleLogin;
+    /* ===================================
+     * Native session refresh (public)
+     * =================================== */
+    /**
+     * Exchange a refresh token for a fresh access token (public — the refresh token IS
+     * the credential). **Native sessions only**; refresh tokens are issued only when the
+     * host opted in via `initializeApi({ platform: 'native' })`.
+     *
+     * On success the new access token is stored automatically (`setBearerToken`). The
+     * returned `refreshToken` is **rotated** — the caller must persist it and discard the
+     * old one before refreshing again.
+     *
+     * ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request
+     * and never retries: replaying a consumed refresh token triggers
+     * `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is
+     * responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or
+     * resume events).
+     *
+     * Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`):
+     * `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401),
+     * `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
+     *
+     * @see RefreshErrorCode
+     */
+    async function refreshToken(clientId, refreshToken) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/refresh`, { refreshToken });
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.refreshToken = refreshToken;
+    /**
+     * Revoke a refresh token's entire family server-side (that device's whole rotation
+     * chain) and clear the in-memory bearer token. Idempotent — always resolves to
+     * `{ success: true }`, never revealing whether the token existed. Call on explicit
+     * sign-out. Persisted tokens in the host's own storage must be cleared separately.
+     */
+    async function logout(clientId, refreshToken) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/logout`, { refreshToken });
+        setBearerToken(undefined);
+        invalidateCache();
+        return res;
+    }
+    authKit.logout = logout;
     /** Send a magic link email to the user (public). */
     async function sendMagicLink(clientId, data) {
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/magic-link/send`, data);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.15  |  Generated: 2026-05-31T15:31:06.561Z
+Version: 1.14.16  |  Generated: 2026-06-01T09:33:51.336Z
 
 This is a concise summary of all available API functions and types.
 
@@ -152,12 +152,11 @@ Return whether proxy mode is currently enabled.
   proxyMode?: boolean
   ngrokSkipBrowserWarning?: boolean
   extraHeaders?: Record<string, string>
-  iframeAutoResize?: boolean // default true when in iframe
-  logger?: Logger // optional console-like or function to enable verbose logging
   /**
-   * When true, the bearer token is automatically saved to localStorage after login
-   * and restored on the next page load. Eliminates the need to manually persist
-   * the token across refreshes. Clear it by calling setBearerToken(undefined) → `void`
+   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
+   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
+   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
+   * short-lived access token. Omit (or `'web'`) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 
 **setNgrokSkipBrowserWarning**(flag: boolean) → `void`
@@ -2963,6 +2962,33 @@ interface AuthLoginResponse {
   * or null when the server could not decode it. Currently only populated by the Apple
   * login endpoint.
   expiresAt?: number | null
+  * Opaque, single-use refresh token. **Native clients only** — present only when the
+  * request opted in via `initializeApi({ platform: 'native' })` (or the
+  * `X-Client-Platform: native` header). For native logins, `token` above is the
+  * short-lived access token; pair it with this refresh token. Undefined for web.
+  refreshToken?: string
+  * Absolute expiry of the refresh-token family, in **milliseconds since epoch**.
+  * Fixed at login — it does **not** move when the token is rotated. Native only.
+  refreshTokenExpiresAt?: number
+}
+```
+
+**RefreshResponse** (interface)
+```typescript
+interface RefreshResponse {
+  token: string
+  refreshToken: string
+  refreshTokenExpiresAt: number
+  expiresAt: number
+  user: AuthKitUser
+  accountData?: Record<string, any>
+}
+```
+
+**LogoutResponse** (interface)
+```typescript
+interface LogoutResponse {
+  success: true
 }
 ```
 
@@ -3218,6 +3244,8 @@ interface AuthKitConfig {
 }
 ```
 
+**RefreshErrorCode** = ``
+
 **AuthKitErrorCode** = ``
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
@@ -8297,6 +8325,12 @@ Google OAuth login via server-side authorization code (public).
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy.
 
+**refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
+Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
+
+**logout**(clientId: string, refreshToken: string) → `Promise<LogoutResponse>`
+Revoke a refresh token's entire family server-side (that device's whole rotation chain) and clear the in-memory bearer token. Idempotent — always resolves to `{ success: true }`, never revealing whether the token existed. Call on explicit sign-out. Persisted tokens in the host's own storage must be cleared separately.
+
 **sendMagicLink**(clientId: string, data: { email: string; redirectUrl: string; accountData?: Record<string, any> }) → `Promise<MagicLinkSendResponse>`
 Send a magic link email to the user (public).
 

package/dist/docs/auth-kit.md

@@ -258,6 +258,50 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Refresh tokens (native sessions)
+
+Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**
+at startup so every request carries `X-Client-Platform: native`:
+
+```ts
+initializeApi({ baseURL, platform: 'native' });
+```
+
+With the opt-in active, the login endpoints (`login`, `register` in immediate mode,
+`googleLogin`, `appleLogin`, `verifyPhoneCode`, `verifyMagicLink`,
+`exchangeWhatsAppSession`) additionally return `refreshToken`, `refreshTokenExpiresAt`
+(absolute, fixed, ms epoch), and a **short-lived** access `token`. Web clients are
+unaffected and receive the unchanged response.
+
+```ts
+// Later — exchange the refresh token for a fresh access token.
+const r = await authKit.refreshToken(clientId, storedRefreshToken);
+// r.refreshToken is ROTATED — persist it and discard the old one BEFORE the next call.
+// The SDK already swapped in r.token as the active bearer for you.
+persist(r.refreshToken, r.refreshTokenExpiresAt);
+
+// On explicit sign-out — revokes the whole device family server-side + clears the bearer.
+await authKit.logout(clientId, storedRefreshToken);
+clearPersistedTokens();
+```
+
+**Rotation rules the host MUST respect:**
+
+1. **Single-use + rotation.** Every `refreshToken()` returns a new token. Persist it and
+   overwrite the old one *before* the next call.
+2. **Serialize refreshes.** Fire a single in-flight refresh and queue callers behind it —
+   the SDK does **not** serialize for you, and racing two refreshes spends the same token.
+3. **Reuse = family death.** Replaying a consumed token throws
+   `SmartlinksApiError` with `errorCode === 'REFRESH_TOKEN_REUSE_DETECTED'`; treat as a
+   hard logout (clear storage, force re-login). `INVALID_REFRESH_TOKEN` (expired/revoked)
+   is handled the same way.
+4. **Absolute expiry is fixed.** `refreshTokenExpiresAt` never moves on rotation; once it
+   passes (default 90 days) the user must log in again.
+
+> Resume-refresh scheduling and transparent refresh-on-401 are the responsibility of the
+> host/auth-ui layer, not this SDK — the SDK only exposes the `refreshToken()` / `logout()`
+> primitives and the `platform` opt-in.
+
 ---
 
 ## Profile management

package/dist/http.d.ts

@@ -14,6 +14,14 @@ export declare function initializeApi(options: {
     proxyMode?: boolean;
     ngrokSkipBrowserWarning?: boolean;
     extraHeaders?: Record<string, string>;
+    /**
+     * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
+     * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
+     * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
+     * short-lived access token. Omit (or `'web'`) for standard web behaviour. Preserved
+     * across re-initialization when not supplied.
+     */
+    platform?: 'native' | 'web';
     iframeAutoResize?: boolean;
     logger?: Logger;
     /**

package/dist/http.js

@@ -33,6 +33,12 @@ let bearerToken = undefined;
 let proxyMode = false;
 let ngrokSkipBrowserWarning = false;
 let extraHeadersGlobal = {};
+/**
+ * Client platform opt-in. When set to 'native', every request carries the
+ * `X-Client-Platform: native` header, which tells AuthKit login endpoints to
+ * issue refresh tokens and short-lived access tokens. Undefined → web behaviour.
+ */
+let clientPlatform = undefined;
 /** Whether initializeApi has been successfully called at least once. */
 let initialized = false;
 /** Safely returns the current browser hostname, or an empty string in non-browser / Node environments. */
@@ -395,6 +401,11 @@ export function initializeApi(options) {
         ? !!options.ngrokSkipBrowserWarning
         : inferredNgrok;
     extraHeadersGlobal = options.extraHeaders ? Object.assign({}, options.extraHeaders) : {};
+    // Platform opt-in (native refresh tokens). Preserve an earlier value when a
+    // re-init call omits it, so long-lived native sessions aren't downgraded by a
+    // later bootstrap that forgot to pass platform.
+    if (options.platform !== undefined)
+        clientPlatform = options.platform;
     // Auto-enable iframe resize unless explicitly disabled
     if (iframe.isIframe() && options.iframeAutoResize !== false) {
         iframe.enableAutoIframeResize();
@@ -1084,6 +1095,8 @@ export async function request(path) {
                     headers["X-API-Key"] = apiKey;
                 if (bearerToken)
                     headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+                if (clientPlatform)
+                    headers["X-Client-Platform"] = clientPlatform;
                 if (ngrokSkipBrowserWarning)
                     headers["ngrok-skip-browser-warning"] = "true";
                 const _getDomain = getSourceDomain();
@@ -1157,6 +1170,8 @@ export async function post(path, body, extraHeaders) {
         headers["X-API-Key"] = apiKey;
     if (bearerToken)
         headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+    if (clientPlatform)
+        headers["X-Client-Platform"] = clientPlatform;
     if (ngrokSkipBrowserWarning)
         headers["ngrok-skip-browser-warning"] = "true";
     const _postDomain = getSourceDomain();
@@ -1214,6 +1229,8 @@ export async function put(path, body, extraHeaders) {
         headers["X-API-Key"] = apiKey;
     if (bearerToken)
         headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+    if (clientPlatform)
+        headers["X-Client-Platform"] = clientPlatform;
     if (ngrokSkipBrowserWarning)
         headers["ngrok-skip-browser-warning"] = "true";
     const _putDomain = getSourceDomain();
@@ -1271,6 +1288,8 @@ export async function patch(path, body, extraHeaders) {
         headers["X-API-Key"] = apiKey;
     if (bearerToken)
         headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+    if (clientPlatform)
+        headers["X-Client-Platform"] = clientPlatform;
     if (ngrokSkipBrowserWarning)
         headers["ngrok-skip-browser-warning"] = "true";
     const _patchDomain = getSourceDomain();
@@ -1375,7 +1394,7 @@ export async function requestWithOptions(path, options) {
                 }
             }
             const _rwoDomain = getSourceDomain();
-            const headers = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ "Content-Type": "application/json" }, (apiKey ? { "X-API-Key": apiKey } : {})), (bearerToken ? { "AUTHORIZATION": `Bearer ${bearerToken}` } : {})), (ngrokSkipBrowserWarning ? { "ngrok-skip-browser-warning": "true" } : {})), (_rwoDomain ? { "X-Source-Domain": _rwoDomain } : {})), extraHeaders);
+            const headers = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ "Content-Type": "application/json" }, (apiKey ? { "X-API-Key": apiKey } : {})), (bearerToken ? { "AUTHORIZATION": `Bearer ${bearerToken}` } : {})), (clientPlatform ? { "X-Client-Platform": clientPlatform } : {})), (ngrokSkipBrowserWarning ? { "ngrok-skip-browser-warning": "true" } : {})), (_rwoDomain ? { "X-Source-Domain": _rwoDomain } : {})), extraHeaders);
             // Merge global custom headers (do not override existing keys from options.headers)
             for (const [k, v] of Object.entries(extraHeadersGlobal))
                 if (!(k in headers))
@@ -1479,6 +1498,8 @@ export async function del(path, extraHeaders) {
         headers["X-API-Key"] = apiKey;
     if (bearerToken)
         headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+    if (clientPlatform)
+        headers["X-Client-Platform"] = clientPlatform;
     if (ngrokSkipBrowserWarning)
         headers["ngrok-skip-browser-warning"] = "true";
     const _delDomain = getSourceDomain();
@@ -1519,6 +1540,8 @@ export function getApiHeaders() {
         headers["X-API-Key"] = apiKey;
     if (bearerToken)
         headers["AUTHORIZATION"] = `Bearer ${bearerToken}`;
+    if (clientPlatform)
+        headers["X-Client-Platform"] = clientPlatform;
     if (ngrokSkipBrowserWarning)
         headers["ngrok-skip-browser-warning"] = "true";
     const sourceDomain = getSourceDomain();

package/dist/index.d.ts

@@ -25,4 +25,4 @@ AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest,
 MobileAdminBundleManifest, } from './mobile-admin/types';
 export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
 export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';
-export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';
+export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';

package/dist/openapi.yaml

@@ -8313,6 +8313,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/logout:
+    post:
+      tags:
+        - authKit
+      summary: "Revoke a refresh token's entire family server-side (that device's whole rotation chain) and clear the in-memory bearer token."
+      operationId: authKit_logout
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LogoutResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/magic-link/send:
     post:
       tags:
@@ -8424,6 +8450,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/refresh:
+    post:
+      tags:
+        - authKit
+      summary: authKit.refreshToken
+      operationId: authKit_refreshToken
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RefreshResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/register:
     post:
       tags:
@@ -17965,8 +18017,42 @@ components:
           type: boolean
         expiresAt:
           type: number
+        refreshToken:
+          type: string
+        refreshTokenExpiresAt:
+          type: number
       required:
         - user
+    RefreshResponse:
+      type: object
+      properties:
+        token:
+          type: string
+        refreshToken:
+          type: string
+        refreshTokenExpiresAt:
+          type: number
+        expiresAt:
+          type: number
+        user:
+          $ref: "#/components/schemas/AuthKitUser"
+        accountData:
+          type: object
+          additionalProperties: true
+      required:
+        - token
+        - refreshToken
+        - refreshTokenExpiresAt
+        - expiresAt
+        - user
+    LogoutResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+      required:
+        - success
     AppleLoginOptions:
       type: object
       properties:

package/dist/types/authKit.d.ts

@@ -48,7 +48,49 @@ export interface AuthLoginResponse {
      * login endpoint.
      */
     expiresAt?: number | null;
+    /**
+     * Opaque, single-use refresh token. **Native clients only** — present only when the
+     * request opted in via `initializeApi({ platform: 'native' })` (or the
+     * `X-Client-Platform: native` header). For native logins, `token` above is the
+     * short-lived access token; pair it with this refresh token. Undefined for web.
+     */
+    refreshToken?: string;
+    /**
+     * Absolute expiry of the refresh-token family, in **milliseconds since epoch**.
+     * Fixed at login — it does **not** move when the token is rotated. Native only.
+     */
+    refreshTokenExpiresAt?: number;
 }
+/**
+ * Response from {@link authKit.refreshToken}. The `refreshToken` is **rotated** on every
+ * call — persist the new value and discard the old one before refreshing again.
+ */
+export interface RefreshResponse {
+    /** New short-lived access token (a `SL.` bearer JWT). */
+    token: string;
+    /** Rotated refresh token — replace the stored value with this. */
+    refreshToken: string;
+    /** Absolute family expiry (ms epoch). Unchanged across rotations. */
+    refreshTokenExpiresAt: number;
+    /** New access-token expiry (ms epoch). */
+    expiresAt: number;
+    user: AuthKitUser;
+    accountData?: Record<string, any>;
+}
+/** Response from {@link authKit.logout}. Idempotent — always `{ success: true }`. */
+export interface LogoutResponse {
+    success: true;
+}
+/**
+ * Server-defined error codes for the refresh/logout flow, surfaced via
+ * `SmartlinksApiError.errorCode`.
+ *
+ * - `MISSING_REFRESH_TOKEN` (400) — programming error; no token sent.
+ * - `INVALID_REFRESH_TOKEN` (401) — unknown / expired / revoked / wrong client → `logout()` + route to login.
+ * - `REFRESH_TOKEN_REUSE_DETECTED` (401) — a consumed token was replayed; the **entire session
+ *   family was revoked server-side**. Hard logout: clear storage, force re-login.
+ */
+export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'REFRESH_TOKEN_REUSE_DETECTED';
 /**
  * Options for {@link authKit.appleLogin}. All fields are optional — only the
  * `identityToken` (passed as a positional argument) is required by the server.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.15  |  Generated: 2026-05-31T15:31:06.561Z
+Version: 1.14.16  |  Generated: 2026-06-01T09:33:51.336Z
 
 This is a concise summary of all available API functions and types.
 
@@ -152,12 +152,11 @@ Return whether proxy mode is currently enabled.
   proxyMode?: boolean
   ngrokSkipBrowserWarning?: boolean
   extraHeaders?: Record<string, string>
-  iframeAutoResize?: boolean // default true when in iframe
-  logger?: Logger // optional console-like or function to enable verbose logging
   /**
-   * When true, the bearer token is automatically saved to localStorage after login
-   * and restored on the next page load. Eliminates the need to manually persist
-   * the token across refreshes. Clear it by calling setBearerToken(undefined) → `void`
+   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
+   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
+   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
+   * short-lived access token. Omit (or `'web'`) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 
 **setNgrokSkipBrowserWarning**(flag: boolean) → `void`
@@ -2963,6 +2962,33 @@ interface AuthLoginResponse {
   * or null when the server could not decode it. Currently only populated by the Apple
   * login endpoint.
   expiresAt?: number | null
+  * Opaque, single-use refresh token. **Native clients only** — present only when the
+  * request opted in via `initializeApi({ platform: 'native' })` (or the
+  * `X-Client-Platform: native` header). For native logins, `token` above is the
+  * short-lived access token; pair it with this refresh token. Undefined for web.
+  refreshToken?: string
+  * Absolute expiry of the refresh-token family, in **milliseconds since epoch**.
+  * Fixed at login — it does **not** move when the token is rotated. Native only.
+  refreshTokenExpiresAt?: number
+}
+```
+
+**RefreshResponse** (interface)
+```typescript
+interface RefreshResponse {
+  token: string
+  refreshToken: string
+  refreshTokenExpiresAt: number
+  expiresAt: number
+  user: AuthKitUser
+  accountData?: Record<string, any>
+}
+```
+
+**LogoutResponse** (interface)
+```typescript
+interface LogoutResponse {
+  success: true
 }
 ```
 
@@ -3218,6 +3244,8 @@ interface AuthKitConfig {
 }
 ```
 
+**RefreshErrorCode** = ``
+
 **AuthKitErrorCode** = ``
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
@@ -8297,6 +8325,12 @@ Google OAuth login via server-side authorization code (public).
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy.
 
+**refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
+Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
+
+**logout**(clientId: string, refreshToken: string) → `Promise<LogoutResponse>`
+Revoke a refresh token's entire family server-side (that device's whole rotation chain) and clear the in-memory bearer token. Idempotent — always resolves to `{ success: true }`, never revealing whether the token existed. Call on explicit sign-out. Persisted tokens in the host's own storage must be cleared separately.
+
 **sendMagicLink**(clientId: string, data: { email: string; redirectUrl: string; accountData?: Record<string, any> }) → `Promise<MagicLinkSendResponse>`
 Send a magic link email to the user (public).
 

package/docs/auth-kit.md

@@ -258,6 +258,50 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Refresh tokens (native sessions)
+
+Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**
+at startup so every request carries `X-Client-Platform: native`:
+
+```ts
+initializeApi({ baseURL, platform: 'native' });
+```
+
+With the opt-in active, the login endpoints (`login`, `register` in immediate mode,
+`googleLogin`, `appleLogin`, `verifyPhoneCode`, `verifyMagicLink`,
+`exchangeWhatsAppSession`) additionally return `refreshToken`, `refreshTokenExpiresAt`
+(absolute, fixed, ms epoch), and a **short-lived** access `token`. Web clients are
+unaffected and receive the unchanged response.
+
+```ts
+// Later — exchange the refresh token for a fresh access token.
+const r = await authKit.refreshToken(clientId, storedRefreshToken);
+// r.refreshToken is ROTATED — persist it and discard the old one BEFORE the next call.
+// The SDK already swapped in r.token as the active bearer for you.
+persist(r.refreshToken, r.refreshTokenExpiresAt);
+
+// On explicit sign-out — revokes the whole device family server-side + clears the bearer.
+await authKit.logout(clientId, storedRefreshToken);
+clearPersistedTokens();
+```
+
+**Rotation rules the host MUST respect:**
+
+1. **Single-use + rotation.** Every `refreshToken()` returns a new token. Persist it and
+   overwrite the old one *before* the next call.
+2. **Serialize refreshes.** Fire a single in-flight refresh and queue callers behind it —
+   the SDK does **not** serialize for you, and racing two refreshes spends the same token.
+3. **Reuse = family death.** Replaying a consumed token throws
+   `SmartlinksApiError` with `errorCode === 'REFRESH_TOKEN_REUSE_DETECTED'`; treat as a
+   hard logout (clear storage, force re-login). `INVALID_REFRESH_TOKEN` (expired/revoked)
+   is handled the same way.
+4. **Absolute expiry is fixed.** `refreshTokenExpiresAt` never moves on rotation; once it
+   passes (default 90 days) the user must log in again.
+
+> Resume-refresh scheduling and transparent refresh-on-401 are the responsibility of the
+> host/auth-ui layer, not this SDK — the SDK only exposes the `refreshToken()` / `logout()`
+> primitives and the `platform` opt-in.
+
 ---
 
 ## Profile management

package/openapi.yaml

@@ -8313,6 +8313,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/logout:
+    post:
+      tags:
+        - authKit
+      summary: "Revoke a refresh token's entire family server-side (that device's whole rotation chain) and clear the in-memory bearer token."
+      operationId: authKit_logout
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LogoutResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/magic-link/send:
     post:
       tags:
@@ -8424,6 +8450,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/refresh:
+    post:
+      tags:
+        - authKit
+      summary: authKit.refreshToken
+      operationId: authKit_refreshToken
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RefreshResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authkit/{clientId}/auth/register:
     post:
       tags:
@@ -17965,8 +18017,42 @@ components:
           type: boolean
         expiresAt:
           type: number
+        refreshToken:
+          type: string
+        refreshTokenExpiresAt:
+          type: number
       required:
         - user
+    RefreshResponse:
+      type: object
+      properties:
+        token:
+          type: string
+        refreshToken:
+          type: string
+        refreshTokenExpiresAt:
+          type: number
+        expiresAt:
+          type: number
+        user:
+          $ref: "#/components/schemas/AuthKitUser"
+        accountData:
+          type: object
+          additionalProperties: true
+      required:
+        - token
+        - refreshToken
+        - refreshTokenExpiresAt
+        - expiresAt
+        - user
+    LogoutResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+      required:
+        - success
     AppleLoginOptions:
       type: object
       properties:

package/package.json

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