@proveanything/smartlinks 1.15.11 → 1.15.14

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.11  |  Generated: 2026-07-20T13:46:09.781Z
+Version: 1.15.14  |  Generated: 2026-07-29T07:45:17.540Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1139,6 +1139,17 @@ interface AnalyticsFilterRequest {
   claimIds?: string[]
   isAdmin?: boolean
   hasLocation?: boolean
+  * Filter web-events rows by the `source` column (list-match). Web-events
+  * only - has no effect on `source: 'tag'` queries.
+  *
+  * There is deliberately no singular `source` filter: the request's own
+  * top-level `source` field (`'events'` vs `'tag'`) already owns that name
+  * as the table selector and predates this column - same word, two
+  * different things. Use a single-element array (`sources: ['portal']`)
+  * for an exact-match filter.
+  sources?: string[]
+  redirectMode?: string
+  redirectModes?: string[]
 }
 ```
 
@@ -3093,6 +3104,70 @@ interface AppleLoginOptions {
   * these again, and never inside the token. Forwarded so the server can persist the
   * display name on first account creation. Treated as untrusted (never used for identity).
   userInfo?: { email?: string; name?: string }
+  * A previously-issued trusted-device token (from a prior MFA `challenge/verify`
+  * or `challenge/recovery-code` response). If still valid, the server skips any
+  * step-up challenge for this login. See `SDK_AUTHKIT_MFA_UPDATE.md` §3.
+  trustedDeviceToken?: string
+}
+```
+
+**MfaRequiredDetails** (interface)
+```typescript
+interface MfaRequiredDetails {
+  mfaSessionToken: string
+  availableFactors: Array<'email' | 'sms'>
+  preferredFactor: 'email' | 'sms'
+  maskedDestinations: { email?: string; sms?: string }
+}
+```
+
+**MfaChallengeSendResponse** (interface)
+```typescript
+interface MfaChallengeSendResponse {
+  success: true
+  factor: 'email' | 'sms'
+  destination: string
+  expiresAt: string
+}
+```
+
+**MfaEnrollSendResponse** (interface)
+```typescript
+interface MfaEnrollSendResponse {
+  mfaSessionToken: string
+  destination: string
+  expiresAt: string
+}
+```
+
+**MfaEnrolledResponse** (interface)
+```typescript
+interface MfaEnrolledResponse {
+  enrolled: true
+  factor: 'email' | 'sms'
+}
+```
+
+**MfaFactorsResponse** (interface)
+```typescript
+interface MfaFactorsResponse {
+  enrolledFactors: {
+  email?: { enrolledAt: string; destination: string }
+  sms?: { enrolledAt: string; destination: string }
+  }
+  recoveryCodesRemaining: number
+  mfaEnabledForClient: boolean
+}
+```
+
+**TrustedDevice** (interface)
+```typescript
+interface TrustedDevice {
+  id: string
+  label: string | null
+  createdAtMs: number
+  lastUsedAtMs: number
+  expiresAtMs: number
 }
 ```
 
@@ -3345,6 +3420,8 @@ interface AuthKitConfig {
 
 **AuthKitErrorCode** = ``
 
+**MfaErrorCode** = ``
+
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
 ### batch
@@ -3705,6 +3782,21 @@ interface Collection {
   portalUrl?: string // URL for the collection's portal (if applicable)
   allowAutoGenerateClaims?: boolean
   defaultAuthKitId: string // default auth kit for this collection, used for auth
+  admin?: {
+  * Redirect behavior for plain collection-level scans (a short link with
+  * no product/serial code in the path, e.g. `https://.../c/shortId`).
+  * Unset means such links always go to the normal collection page.
+  redirect?: CollectionRedirectConfig
+  }
+}
+```
+
+**CollectionRedirectConfig** (interface)
+```typescript
+interface CollectionRedirectConfig {
+  mode: 'fixed' | 'dynamic' | 'deep'
+  url?: string
+  template?: string
 }
 ```
 
@@ -8543,20 +8635,20 @@ Gets current account information for the logged in user. Returns user, owner, ac
 
 ### authKit
 
-**login**(clientId: string, email: string, password: string) → `Promise<AuthLoginResponse>`
-Login with email + password (public).
+**login**(clientId: string, email: string, password: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
+Login with email + password (public). When the client's MFA policy requires a step-up, the server returns **403 `MFA_REQUIRED`** instead of a session — `login()` throws a `SmartlinksApiError` with `err.errorResponse?.errorCode === 'MFA_REQUIRED'` and the challenge details in `err.details` (see {@link MfaRequiredDetails}). Route the caller to {@link mfaChallengeSend} on that error; this method's return type is unchanged. returned one (via {@link mfaChallengeVerify}/{@link mfaRecoveryCode} with `trustDevice: true`), pass it here to skip the challenge entirely as long as it's still valid. If it's revoked/expired, the server silently falls back to requiring a fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling.
 
 **register**(clientId: string, data: { email: string; password: string; displayName?: string; accountData?: Record<string, any> }) → `Promise<AuthLoginResponse>`
-Register a new user (public).
+Register a new user (public). Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's nothing to challenge against.
 
-**googleLogin**(clientId: string, idToken: string) → `Promise<AuthLoginResponse>`
-Google OAuth login via ID token (public).
+**googleLogin**(clientId: string, idToken: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
+Google OAuth login via ID token (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. {@link mfaChallengeVerify}/{@link mfaRecoveryCode} (with `trustDevice: true`) to skip the challenge on this device, same as {@link login}.
 
 **googleCodeLogin**(clientId: string, code: string, redirectUri: string) → `Promise<AuthLoginResponse>`
 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.
+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. Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. Pass `opts.trustedDeviceToken` to skip the challenge on a recognized device.
 
 **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.
@@ -8567,26 +8659,26 @@ Revoke a refresh token's entire family server-side (that device's whole rotation
 **sendMagicLink**(clientId: string, data: { email: string; redirectUrl: string; accountData?: Record<string, any> }) → `Promise<MagicLinkSendResponse>`
 Send a magic link email to the user (public).
 
-**verifyMagicLink**(clientId: string, token: string) → `Promise<MagicLinkVerifyResponse>`
-Verify a magic link token and authenticate/create the user (public).
+**verifyMagicLink**(clientId: string, token: string, trustedDeviceToken?: string) → `Promise<MagicLinkVerifyResponse>`
+Verify a magic link token and authenticate/create the user (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape.
 
 **sendPhoneCode**(clientId: string, phoneNumber: string) → `Promise<PhoneSendCodeResponse>`
 Send phone verification code (public).
 
-**verifyPhoneCode**(clientId: string, phoneNumber: string, code: string) → `Promise<PhoneVerifyResponse>`
-Verify phone verification code (public).
+**verifyPhoneCode**(clientId: string, phoneNumber: string, code: string, trustedDeviceToken?: string) → `Promise<PhoneVerifyResponse>`
+Verify phone verification code (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape.
 
 **sendWhatsApp**(clientId: string, body: SendWhatsAppRequest = {}) → `Promise<SendWhatsAppResponse>`
 Send a WhatsApp verification deep-link (public).
 
 **verifyWhatsApp**(clientId: string, token: string, phoneNumber: string) → `Promise<VerifyWhatsAppResponse>`
-Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback).
+Manually verify WhatsApp token if inbound webhook path is unavailable (legacy/public fallback). Not gated by step-up MFA — this endpoint only confirms the code, it never issues a session/bearer token, so there is nothing to challenge. {@link exchangeWhatsAppSession} is the WhatsApp method that's gated.
 
 **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).
+**exchangeWhatsAppSession**(clientId: string, token: string, sessionKey: string, trustedDeviceToken?: string) → `Promise<ExchangeWhatsAppSessionResponse>`
+Exchange a verified WhatsApp token for an Auth Kit session (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. This is the WhatsApp method that needs `trustedDeviceToken`, not {@link verifyWhatsApp} (which never issues a session).
 
 **sendSmsVerify**(clientId: string, body: SendSmsVerifyRequest) → `Promise<SendSmsVerifyResponse>`
 Send an SMS click-to-verify link (public).
@@ -8636,23 +8728,59 @@ Update the authenticated user's profile and replace the bearer token when refres
 **deleteAccount**(clientId: string, password: string, confirmText: string) → `Promise<SuccessResponse>`
 Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
 
+**mfaChallengeSend**(clientId: string, mfaSessionToken: string, factor: 'email' | 'sms') → `Promise<MfaChallengeSendResponse>`
+Send (or resend) an MFA challenge code to the given factor (public).
+
+**mfaChallengeVerify**(clientId: string, mfaSessionToken: string, code: string, trustDevice?: boolean, deviceLabel?: string) → `Promise<MfaFinalizeResponse>`
+Verify an MFA challenge code and finalize the login (public). On success this behaves like {@link login} — the bearer token is adopted and the cache invalidated. it and pass it to future {@link login} calls to skip the challenge on this device.
+
+**mfaRecoveryCode**(clientId: string, mfaSessionToken: string, code: string, trustDevice?: boolean, deviceLabel?: string) → `Promise<MfaFinalizeResponse>`
+Finalize a challenged login using a single-use recovery code instead of a sent code (public). Same finalize-session behaviour as {@link mfaChallengeVerify}.
+
+**getMfaFactors**(clientId: string) → `Promise<MfaFactorsResponse>`
+List enrolled factors and recovery-code count for the current user (authenticated).
+
+**enrollEmailMfa**(clientId: string) → `Promise<MfaEnrollSendResponse>`
+Begin email-factor enrollment; sends a code to the account's existing email (authenticated).
+
+**confirmEmailMfa**(clientId: string, mfaSessionToken: string, code: string) → `Promise<MfaEnrolledResponse>`
+Confirm email-factor enrollment with the code sent by {@link enrollEmailMfa} (authenticated).
+
+**enrollSmsMfa**(clientId: string, phoneNumber: string) → `Promise<MfaEnrollSendResponse>`
+Begin SMS-factor enrollment; sends a code to the given phone number (authenticated).
+
+**confirmSmsMfa**(clientId: string, mfaSessionToken: string, code: string) → `Promise<MfaEnrolledResponse>`
+Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated).
+
+**generateMfaRecoveryCodes**(clientId: string, password: string) → `Promise<`
+Generate a fresh set of recovery codes, invalidating any previous set (authenticated). Returned **in plaintext, exactly once** — nothing else in the API ever returns them again, so the caller must display/export them immediately.
+
+**removeMfaFactor**(clientId: string, factor: 'email' | 'sms', password: string) → `Promise<SuccessResponse>`
+Remove an enrolled MFA factor (authenticated). Server route is DELETE with a body.
+
+**listTrustedDevices**(clientId: string) → `Promise<`
+List devices trusted to skip MFA challenges for the current user (authenticated).
+
+**revokeTrustedDevice**(clientId: string, id: string) → `Promise<SuccessResponse>`
+Revoke a single trusted device by id (authenticated).
+
 **load**(authKitId: string) → `Promise<AuthKitConfig>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 **get**(collectionId: string, authKitId: string) → `Promise<AuthKitConfig>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 **list**(collectionId: string, admin?: boolean) → `Promise<AuthKitConfig[]>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 **create**(collectionId: string, data: any) → `Promise<AuthKitConfig>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 **update**(collectionId: string, authKitId: string, data: any) → `Promise<AuthKitConfig>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 **remove**(collectionId: string, authKitId: string) → `Promise<void>`
-Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
+Revoke a single trusted device by id (authenticated).
 
 ### batch
 

package/dist/docs/analytics-metadata-conventions.md

@@ -15,6 +15,8 @@ Some of these are now promoted top-level analytics fields. Others remain good me
 - `entryType`
 - `pageId`
 - `scanMethod`
+- `source` - collection/web-events only. Free-form client app identifier, e.g. `'portal'`, `'hub'`. No enum/whitelist. Not available on tag events - see the `analytics.tag.track(event)` section in [docs/analytics.md](analytics.md) for why.
+- `redirectMode` - tag-events only. Usually server-written; only set this yourself if you're logging a redirect-style event.
 
 These should be sent as top-level analytics fields, not inside `metadata`.
 
@@ -59,6 +61,7 @@ These keys give teams a shared vocabulary for:
 - Send promoted fields at top level.
 - Keep values flat and scalar where possible so they are easier to filter and break down later.
 - Promote a field to a first-class backend column only when it becomes a hot platform-wide dimension.
+- Note: `source` (the event column) and the query-time `source` parameter (`'events' | 'tag'`, which table to query) are unrelated fields that happen to share a name. When filtering by the `source` column, use the plural `sources` array - there is no singular `source` filter, precisely to avoid colliding with the table selector.
 
 ---
 
@@ -77,6 +80,7 @@ analytics.collection.track({
   campaign: 'summer-launch',
   utmSource: 'email',
   pageId: 'QR123',
+  source: 'portal',
   metadata: {
     pagePath: '/c/demo-collection',
   },

package/dist/docs/analytics.md

@@ -48,6 +48,12 @@ The backend stores custom analytics dimensions in `metadata`, but promoted analy
 
 See [docs/analytics-metadata-conventions.md](analytics-metadata-conventions.md) for the recommended key set.
 
+### A note on server-written events
+
+Not every row in these tables is written by your app. As of 2026-07-23, the server itself logs a `scan_redirect` event on the tag-events table at the moment a GS1 digital-link scan, claim short-link scan, or NFC tap decides on a redirect destination - before the client ever loads anything. This is separate from `scan_tag`, which your app still writes on landing exactly as before. `scan_blank_tag` remains excluded from the analytics pipeline.
+
+Server-issued redirects also append `?sid=<value>` to the destination URL. If your landing page reads `sid` off the URL and reuses it as its own `sessionId` on the next `analytics.collection.track(...)` or `analytics.tag.track(...)` call, "did the redirect actually land" becomes a free `sessionId` join - nothing new to send, just reuse the value if it's present.
+
 ---
 
 ## Quick Start
@@ -67,6 +73,7 @@ analytics.collection.track({
   appId: 'homepage',
   path: '/c/demo-collection',
   deviceType: 'mobile',
+  source: 'portal',
 })
 ```
 
@@ -298,7 +305,9 @@ Tracks generic collection analytics events such as:
 - internal navigation
 - outbound link activity
 
-Supported top-level fields include the core event fields plus promoted analytics columns such as `visitorId`, `referrerHost`, `pageId`, and `entryType`, along with custom metadata dimensions like `group`, `placement`, `pagePath`, and `qrCodeId`.
+Supported top-level fields include the core event fields plus promoted analytics columns such as `visitorId`, `referrerHost`, `pageId`, `entryType`, and `source`, along with custom metadata dimensions like `group`, `placement`, `pagePath`, and `qrCodeId`.
+
+`source` is a free-form string identifying which client app logged the event, e.g. `'portal'`, `'hub'` - there's no enum or whitelist, send whatever identifies your app. It's web-events only; there is no equivalent field on tag events (see the `analytics.tag.track(event)` section below for why).
 
 Example:
 
@@ -321,6 +330,7 @@ analytics.collection.track({
   group: 'summer-launch',
   placement: 'hero',
   pageId: 'QR123',
+  source: 'portal',
   metadata: { pagePath: '/c/demo-collection?pageId=QR123' },
 })
 ```
@@ -334,7 +344,11 @@ Tracks physical scan analytics such as:
 - claim/code activity
 - admin vs customer scan behavior
 
-Supported top-level fields include the core scan fields plus promoted analytics columns such as `visitorId`, `entryType`, and `scanMethod`, along with custom metadata dimensions like `group`, `tag`, and campaign extras.
+Supported top-level fields include the core scan fields plus promoted analytics columns such as `visitorId`, `entryType`, `scanMethod`, and `redirectMode`, along with custom metadata dimensions like `group`, `tag`, and campaign extras.
+
+`redirectMode` is only relevant if you're logging a redirect-style event yourself - in practice it's mostly written by the server automatically (see [A note on server-written events](#a-note-on-server-written-events) above).
+
+There is deliberately no `source` field on tag events, even though one exists on collection events. `eventType` already tells you who wrote a tag-events row - `scan_redirect` is always server-written, `scan_tag`/`scan_blank_tag` are always client-written - so a `source` column here would just duplicate that. To segment tag scans by NFC vs. QR, use `entryType`/`scanMethod` instead.
 
 Example:
 
@@ -541,6 +555,24 @@ const countries = await analytics.admin.breakdown('demo-collection', {
 })
 ```
 
+Breaking down or filtering by the new `source` *column* (web-events only) works the same way, just watch the naming: the request's own top-level `source: 'events'` is the pre-existing table selector, and it sits alongside a `sources` array that filters by the column's value. They are unrelated fields that happen to share a name.
+
+```typescript
+const appSources = await analytics.admin.breakdown('demo-collection', {
+  source: 'events',       // table selector: query web-events
+  dimension: 'source',    // break down by the `source` column
+  metric: 'count',
+})
+
+const portalOnly = await analytics.admin.events('demo-collection', {
+  source: 'events',       // table selector
+  sources: ['portal'],    // column filter - single-element array for exact match
+  limit: 100,
+})
+```
+
+There is no singular `source` filter field for this reason - use `sources: ['portal']` for an exact match.
+
 ### Raw events
 
 ```typescript
@@ -588,7 +620,7 @@ For metrics, generic queries support:
 - `uniqueSessions`
 - `uniqueVisitors`
 
-Extra collection-event filters include:
+Extra collection-event (web-events) filters include:
 
 - `appId`, `appIds[]`
 - `destinationAppId`, `destinationAppIds[]`
@@ -596,6 +628,7 @@ Extra collection-event filters include:
 - `href`, `path`
 - `hrefContains`, `pathContains`
 - `isExternal`
+- `sources[]` - filter by the `source` column (list-match only, no singular form - see [Breakdown](#breakdown))
 
 Extra tag-event filters include:
 
@@ -603,6 +636,7 @@ Extra tag-event filters include:
 - `claimId`, `claimIds[]`
 - `isAdmin`
 - `hasLocation`
+- `redirectMode`, `redirectModes[]`
 
 ---
 

package/dist/docs/auth-kit.md

@@ -226,6 +226,7 @@ const session = await authKit.appleLogin(clientId, appleIdentityToken, {
   // All optional:
   nonce,                                  // raw nonce, if you used nonce binding
   userInfo: { name, email },              // first authorization callback ONLY — Apple never resends it
+  trustedDeviceToken,                     // skip an MFA step-up challenge on a recognized device — see "Step-up MFA" below
 });
 // session.isNewUser and session.expiresAt (ms epoch) are populated by this endpoint.
 ```
@@ -304,6 +305,137 @@ clearPersistedTokens();
 
 ---
 
+## Step-up MFA (Phase 1)
+
+Backend-only for now — **no admin-console UI and no challenge UI ship with this pass.**
+Factors: **email OTP, SMS OTP, recovery codes**. WhatsApp OTP, TOTP, and passkeys as
+*factors* are deferred to a later phase; don't build against them yet.
+
+The step-up gate applies to **every login method that issues a session**:
+
+| Method | Gated? |
+|---|---|
+| `login()` | ✅ |
+| `googleLogin()` | ✅ |
+| `appleLogin()` | ✅ — pass `opts.trustedDeviceToken` |
+| `verifyPhoneCode()` | ✅ |
+| `verifyMagicLink()` | ✅ |
+| `exchangeWhatsAppSession()` | ✅ — **this is the WhatsApp method that needs a trusted-device token, not `verifyWhatsApp()`** |
+| `verifyWhatsApp()` | ❌ — only confirms the code, never issues a session, so there's nothing to gate |
+| `register()` | ❌ — a brand-new user has no enrolled factors to challenge against |
+| `googleCodeLogin()` | ❌ — no `/auth/google-code` route exists server-side |
+
+All six gated methods accept an optional `trustedDeviceToken` param (the last positional
+argument, or `opts.trustedDeviceToken` for `appleLogin()`) — same purpose everywhere: skip
+the challenge on a device the user already verified.
+
+### Handling `MFA_REQUIRED`
+
+Every gated method's return type is unchanged. When the client's MFA policy requires a
+step-up, the server returns 403 instead of a session, and the method throws — identically
+for all six:
+
+```ts
+import { authKit, SmartlinksApiError } from '@proveanything/smartlinks';
+
+try {
+  const session = await authKit.login(clientId, email, password);
+  // logged in, no MFA required
+} catch (err) {
+  if (err instanceof SmartlinksApiError && err.errorCode === 'MFA_REQUIRED') {
+    const { mfaSessionToken, availableFactors, preferredFactor, maskedDestinations } = err.details!;
+    // → route to a challenge UI; call authKit.mfaChallengeSend(clientId, mfaSessionToken, preferredFactor)
+  } else {
+    throw err;
+  }
+}
+```
+
+### Completing the challenge
+
+```ts
+// Send (or resend, or switch factor) a code on the same mfaSessionToken
+const sent = await authKit.mfaChallengeSend(clientId, mfaSessionToken, 'sms');
+// sent.destination is masked, e.g. "+1******1234"
+
+// Verify the code — behaves like login() on success: bearer token is adopted automatically
+const session = await authKit.mfaChallengeVerify(clientId, mfaSessionToken, '123456', /* trustDevice */ true, 'My Laptop');
+
+// Or finalize with a single-use recovery code instead
+const session = await authKit.mfaRecoveryCode(clientId, mfaSessionToken, recoveryCode);
+```
+
+`mfaSessionToken` is short-lived (10 min) and single-use — burned on 5 failed attempts
+(`MFA_TOO_MANY_ATTEMPTS`) or on success. Once burned/expired, there's no "resend within the
+same session" — the caller must restart from `login()`.
+
+### Trusted devices — "don't ask again on this device"
+
+There's no fingerprinting involved: a "recognized device" is purely "the caller presented a
+valid, unexpired, unrevoked `trustedDeviceToken`". Handle it like the native refresh token
+above — same secure storage, same persist-before-next-call discipline:
+
+```ts
+// 1) Persist trustedDeviceToken from a successful challenge (trustDevice: true)
+persistTrustedDeviceToken(session.trustedDeviceToken, session.trustedDeviceExpiresAt);
+
+// 2) Send it on every subsequent call to ANY of the six gated methods — if still valid,
+//    the challenge is skipped entirely. It isn't tied to which method the user challenged
+//    through, so "remember this device" works no matter which login method they pick next.
+const session = await authKit.login(clientId, email, password, storedTrustedDeviceToken);
+const session = await authKit.googleLogin(clientId, idToken, storedTrustedDeviceToken);
+const session = await authKit.exchangeWhatsAppSession(clientId, waToken, sessionKey, storedTrustedDeviceToken);
+// ...and so on for appleLogin (via opts), verifyPhoneCode, verifyMagicLink.
+// If it's revoked/expired, the server silently falls back to requiring a fresh challenge —
+// the method just throws MFA_REQUIRED again, no special-case handling needed.
+
+// 3) Let users audit/revoke devices from a Settings screen
+const { devices } = await authKit.listTrustedDevices(clientId);
+await authKit.revokeTrustedDevice(clientId, deviceId);
+```
+
+### Factor management (Settings → Security)
+
+Authenticated (bearer token) — same `mfaSessionToken` + code mechanism as login challenges,
+just against a `purpose: 'enroll'` challenge instead of `'login'`.
+
+```ts
+// Enroll email (uses the account's existing email)
+const { mfaSessionToken } = await authKit.enrollEmailMfa(clientId);
+await authKit.confirmEmailMfa(clientId, mfaSessionToken, code);
+
+// Enroll SMS
+const { mfaSessionToken: smsToken } = await authKit.enrollSmsMfa(clientId, '+61400000000');
+await authKit.confirmSmsMfa(clientId, smsToken, code);
+
+// Recovery codes — plaintext, shown exactly once; nothing else in the API returns them again
+const { recoveryCodes } = await authKit.generateMfaRecoveryCodes(clientId, password);
+
+// Inspect / remove
+const factors = await authKit.getMfaFactors(clientId);
+// factors: { enrolledFactors: { email?, sms? }, recoveryCodesRemaining, mfaEnabledForClient }
+await authKit.removeMfaFactor(clientId, 'sms', password);
+```
+
+> Enrollment endpoints don't currently check the client's `mfa.mode` — enrolling is possible
+> even when MFA is configured `'off'` for a client. Those factors simply won't be challenged
+> at login until an admin turns the mode on (via the existing admin AuthKit config update,
+> no new admin route in this pass).
+
+### MFA error codes
+
+| `errorCode` | HTTP | Meaning / client action |
+|---|---|---|
+| `MFA_REQUIRED` | 403 | From any of the six gated login methods — see above |
+| `INVALID_MFA_CODE` | 401 | Wrong code — let the user retry (attempts are capped) |
+| `MFA_TOO_MANY_ATTEMPTS` | 429 | 5 wrong attempts — the challenge is burned; restart from `login()` |
+| `MFA_FACTOR_NOT_ENROLLED` | 400 | Requested factor isn't enrolled — programming error if the UI only offers `availableFactors` |
+| `MFA_SESSION_EXPIRED` | 401 | `mfaSessionToken` past its 10-minute TTL — restart from `login()` |
+| `MFA_SESSION_INVALID` | 401 | Unknown/wrong-client/already-consumed token, or (on enroll confirm) mismatched user |
+| `RECOVERY_CODE_INVALID` | 401 | Wrong or already-used recovery code |
+
+---
+
 ## Profile management
 
 ```ts