@proveanything/smartlinks 1.15.11 → 1.15.13

package/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.13  |  Generated: 2026-07-27T08:21:16.504Z
 
 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[]
 }
 ```
 
@@ -3096,6 +3107,66 @@ interface AppleLoginOptions {
 }
 ```
 
+**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
+}
+```
+
 **MagicLinkSendResponse** (interface)
 ```typescript
 interface MagicLinkSendResponse {
@@ -3345,6 +3416,8 @@ interface AuthKitConfig {
 
 **AuthKitErrorCode** = ``
 
+**MfaErrorCode** = ``
+
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
 ### batch
@@ -8543,8 +8616,8 @@ 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).
@@ -8636,23 +8709,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/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/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/docs/auth-kit.md

@@ -304,6 +304,116 @@ 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 are
+deferred to a later phase; don't build against them yet.
+
+The step-up gate is wired into **`login()` only** — `register`, `verifyPhoneCode`, and
+`verifyMagicLink` never return `MFA_REQUIRED`, regardless of client config.
+
+### Handling `MFA_REQUIRED` from `login()`
+
+`login()`'s return type is unchanged. When the client's MFA policy requires a step-up,
+the server returns 403 instead of a session, and `login()` throws:
+
+```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 login() — if still valid, the challenge is skipped entirely
+const session = await authKit.login(clientId, email, password, storedTrustedDeviceToken);
+// If it's revoked/expired, the server silently falls back to requiring a fresh challenge —
+// login() 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 `login()` only — 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