@proveanything/smartlinks 1.15.10 → 1.15.13

package/dist/api/authKit.d.ts

@@ -1,11 +1,25 @@
-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";
+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, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaEnrolledResponse, MfaFactorsResponse, TrustedDevice } from "../types/authKit";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
  */
 export declare namespace authKit {
-    /** Login with email + password (public). */
-    function login(clientId: string, email: string, password: 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.
+     *
+     * @param trustedDeviceToken - Optional. If a previous MFA challenge on this device
+     *   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.
+     */
+    function login(clientId: string, email: string, password: string, trustedDeviceToken?: string): Promise<AuthLoginResponse>;
     /** Register a new user (public). */
     function register(clientId: string, data: {
         email: string;
@@ -124,6 +138,47 @@ export declare namespace authKit {
     function verifyEmailChange(clientId: string, token: string): Promise<SuccessResponse>;
     function updatePhone(clientId: string, phoneNumber: string, verificationCode: string): Promise<SuccessResponse>;
     function deleteAccount(clientId: string, password: string, confirmText: string): Promise<SuccessResponse>;
+    /** Send (or resend) an MFA challenge code to the given factor (public). */
+    function mfaChallengeSend(clientId: string, mfaSessionToken: string, factor: 'email' | 'sms'): Promise<MfaChallengeSendResponse>;
+    /**
+     * 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.
+     *
+     * @param trustDevice - When `true`, the response includes `trustedDeviceToken` — persist
+     *   it and pass it to future {@link login} calls to skip the challenge on this device.
+     */
+    function mfaChallengeVerify(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}.
+     */
+    function mfaRecoveryCode(clientId: string, mfaSessionToken: string, code: string, trustDevice?: boolean, deviceLabel?: string): Promise<MfaFinalizeResponse>;
+    /** List enrolled factors and recovery-code count for the current user (authenticated). */
+    function getMfaFactors(clientId: string): Promise<MfaFactorsResponse>;
+    /** Begin email-factor enrollment; sends a code to the account's existing email (authenticated). */
+    function enrollEmailMfa(clientId: string): Promise<MfaEnrollSendResponse>;
+    /** Confirm email-factor enrollment with the code sent by {@link enrollEmailMfa} (authenticated). */
+    function confirmEmailMfa(clientId: string, mfaSessionToken: string, code: string): Promise<MfaEnrolledResponse>;
+    /** Begin SMS-factor enrollment; sends a code to the given phone number (authenticated). */
+    function enrollSmsMfa(clientId: string, phoneNumber: string): Promise<MfaEnrollSendResponse>;
+    /** Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated). */
+    function confirmSmsMfa(clientId: string, mfaSessionToken: string, code: string): Promise<MfaEnrolledResponse>;
+    /**
+     * 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.
+     */
+    function generateMfaRecoveryCodes(clientId: string, password: string): Promise<{
+        recoveryCodes: string[];
+    }>;
+    /** Remove an enrolled MFA factor (authenticated). Server route is DELETE with a body. */
+    function removeMfaFactor(clientId: string, factor: 'email' | 'sms', password: string): Promise<SuccessResponse>;
+    /** List devices trusted to skip MFA challenges for the current user (authenticated). */
+    function listTrustedDevices(clientId: string): Promise<{
+        devices: TrustedDevice[];
+    }>;
+    /** Revoke a single trusted device by id (authenticated). */
+    function revokeTrustedDevice(clientId: string, id: string): Promise<SuccessResponse>;
     function load(authKitId: string): Promise<AuthKitConfig>;
     function get(collectionId: string, authKitId: string): Promise<AuthKitConfig>;
     function list(collectionId: string, admin?: boolean): Promise<AuthKitConfig[]>;

package/dist/api/authKit.js

@@ -1,4 +1,4 @@
-import { request, post, put, del, setBearerToken, invalidateCache } from "../http";
+import { request, post, put, del, requestWithOptions, setBearerToken, invalidateCache } from "../http";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -8,9 +8,26 @@ export var authKit;
     /* ===================================
      * Authentication (Per client)
      * =================================== */
-    /** Login with email + password (public). */
-    async function login(clientId, email, password) {
-        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/login`, { email, password });
+    /**
+     * 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.
+     *
+     * @param trustedDeviceToken - Optional. If a previous MFA challenge on this device
+     *   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.
+     */
+    async function login(clientId, email, password, trustedDeviceToken) {
+        const body = { email, password };
+        if (trustedDeviceToken)
+            body.trustedDeviceToken = trustedDeviceToken;
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/login`, body);
         if (res.token) {
             setBearerToken(res.token);
             invalidateCache();
@@ -277,6 +294,101 @@ export var authKit;
         return res;
     }
     authKit.deleteAccount = deleteAccount;
+    /* ===================================
+     * Step-up MFA — completing a challenged login (public)
+     *
+     * Called after login() throws MFA_REQUIRED. mfaSessionToken is short-lived (10 min) and
+     * single-use — burned on 5 failed attempts (MFA_TOO_MANY_ATTEMPTS) or on success.
+     * challenge/send can be called again on the same token (while unexpired/unburned) to
+     * switch factors or resend.
+     * =================================== */
+    /** Send (or resend) an MFA challenge code to the given factor (public). */
+    async function mfaChallengeSend(clientId, mfaSessionToken, factor) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/challenge/send`, { mfaSessionToken, factor });
+    }
+    authKit.mfaChallengeSend = mfaChallengeSend;
+    /**
+     * 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.
+     *
+     * @param trustDevice - When `true`, the response includes `trustedDeviceToken` — persist
+     *   it and pass it to future {@link login} calls to skip the challenge on this device.
+     */
+    async function mfaChallengeVerify(clientId, mfaSessionToken, code, trustDevice, deviceLabel) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/mfa/challenge/verify`, { mfaSessionToken, code, trustDevice, deviceLabel });
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.mfaChallengeVerify = mfaChallengeVerify;
+    /**
+     * Finalize a challenged login using a single-use recovery code instead of a sent code
+     * (public). Same finalize-session behaviour as {@link mfaChallengeVerify}.
+     */
+    async function mfaRecoveryCode(clientId, mfaSessionToken, code, trustDevice, deviceLabel) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/mfa/challenge/recovery-code`, { mfaSessionToken, code, trustDevice, deviceLabel });
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.mfaRecoveryCode = mfaRecoveryCode;
+    /* ===================================
+     * Step-up MFA — factor management (Authenticated)
+     * =================================== */
+    /** List enrolled factors and recovery-code count for the current user (authenticated). */
+    async function getMfaFactors(clientId) {
+        return request(`/authkit/${encodeURIComponent(clientId)}/mfa/factors`);
+    }
+    authKit.getMfaFactors = getMfaFactors;
+    /** Begin email-factor enrollment; sends a code to the account's existing email (authenticated). */
+    async function enrollEmailMfa(clientId) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/email/enroll`, {});
+    }
+    authKit.enrollEmailMfa = enrollEmailMfa;
+    /** Confirm email-factor enrollment with the code sent by {@link enrollEmailMfa} (authenticated). */
+    async function confirmEmailMfa(clientId, mfaSessionToken, code) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/email/confirm`, { mfaSessionToken, code });
+    }
+    authKit.confirmEmailMfa = confirmEmailMfa;
+    /** Begin SMS-factor enrollment; sends a code to the given phone number (authenticated). */
+    async function enrollSmsMfa(clientId, phoneNumber) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/sms/enroll`, { phoneNumber });
+    }
+    authKit.enrollSmsMfa = enrollSmsMfa;
+    /** Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated). */
+    async function confirmSmsMfa(clientId, mfaSessionToken, code) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/sms/confirm`, { mfaSessionToken, code });
+    }
+    authKit.confirmSmsMfa = confirmSmsMfa;
+    /**
+     * 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.
+     */
+    async function generateMfaRecoveryCodes(clientId, password) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/recovery-codes/generate`, { password });
+    }
+    authKit.generateMfaRecoveryCodes = generateMfaRecoveryCodes;
+    /** Remove an enrolled MFA factor (authenticated). Server route is DELETE with a body. */
+    async function removeMfaFactor(clientId, factor, password) {
+        const path = `/authkit/${encodeURIComponent(clientId)}/mfa/factors/${factor}`;
+        return requestWithOptions(path, { method: 'DELETE', body: JSON.stringify({ password }) });
+    }
+    authKit.removeMfaFactor = removeMfaFactor;
+    /** List devices trusted to skip MFA challenges for the current user (authenticated). */
+    async function listTrustedDevices(clientId) {
+        return request(`/authkit/${encodeURIComponent(clientId)}/mfa/trusted-devices`);
+    }
+    authKit.listTrustedDevices = listTrustedDevices;
+    /** Revoke a single trusted device by id (authenticated). */
+    async function revokeTrustedDevice(clientId, id) {
+        return del(`/authkit/${encodeURIComponent(clientId)}/mfa/trusted-devices/${encodeURIComponent(id)}`);
+    }
+    authKit.revokeTrustedDevice = revokeTrustedDevice;
     /* ===================================
      * Collection-based AuthKit
      * =================================== */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.10  |  Generated: 2026-07-19T13:35:07.171Z
+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[]
 }
 ```
 
@@ -1419,6 +1430,11 @@ interface AppliedOverridesSummary {
 ```typescript
 interface SystemBlock {
   basePlanId?: string
+  * Stable capability tier microapps should branch on instead of
+  * `basePlanId` — see docs/appConfig.md §4.1. Known tiers are `ProductMode`;
+  * an unrecognised value is a future tier your code doesn't know about yet
+  * — fail closed to the nearest tier you do understand rather than erroring.
+  productMode?: ProductMode | (string & {})
   addOnKeys?: string[]
   apps?: string[]
   * Explicit overrides only — an absent key is NOT "off". Resolve with
@@ -1451,6 +1467,8 @@ interface AppConfigSettings {
 }
 ```
 
+**ProductMode** = `'simple_redirect' | 'rich_redirect' | 'inform' | 'engage'`
+
 ### appManifest
 
 **AppBundle** (interface)
@@ -3089,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 {
@@ -3338,6 +3416,8 @@ interface AuthKitConfig {
 
 **AuthKitErrorCode** = ``
 
+**MfaErrorCode** = ``
+
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
 ### batch
@@ -8536,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).
@@ -8629,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/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/appConfig.md

@@ -60,9 +60,15 @@ export interface AppEntry {
   [k: string]: unknown;           // per-module inline settings preserved
 }
 
+/** Known `productMode` tiers, low → high — see §4.1. Not exhaustive; unrecognised values are future tiers. */
+export type ProductMode = 'simple_redirect' | 'rich_redirect' | 'inform' | 'engage';
+
 /** Resolved entitlements — safe for every client to read. */
 export interface SystemBlock {
+  /** Internal billing identifier — not a capability signal, see §4. */
   basePlanId?: string;
+  /** Stable capability tier — see §4.1. Prefer this over basePlanId. */
+  productMode?: ProductMode | (string & {});
   addOnKeys?: string[];
   apps?: string[];                       // apps unlocked by add-ons
   features?: Record<string, boolean>;    // explicit overrides only — see §4.4 for absent-key resolution
@@ -184,12 +190,46 @@ Written only by `entitlements-reconcile`. Represents the union of:
 - every add-on line item on their Stripe subscription
 - `systemPrivate.overrides` (applied last, always wins)
 
-### 4.1 `basePlanId`
+`basePlanId` is an internal Stripe billing/plan identifier (string,
+sourced from subscription metadata) — a billing concern, not a capability
+signal. Don't branch app behavior on its literal value or its internal
+plan names; that's what `productMode` is for.
+
+### 4.1 `productMode`
+
+Stable capability tier the app should branch on instead of `basePlanId`
+(a billing identity that can change independently of capability). Written
+by `entitlements-reconcile` on every sync. Typed as `ProductMode` in the
+SDK (`src/types/appConfiguration.ts`) — a union of the known tiers below,
+plus any other string, since future tiers will show up as new values
+before the SDK type is updated to know their names.
+
+Ladder, low → high:
+
+| `productMode`     | Unlocks (roughly)                                                              |
+| ------------------ | --------------------------------------------------------------------------------- |
+| `simple_redirect`  | Redirect-only: scanning a tag/QR sends the user straight to a URL — no product/proof page, no catalog UI. |
+| `rich_redirect`    | Adds a rendered product/proof page (image, description, spec data) — still no deeper apps. |
+| `inform`           | Adds informational surfaces beyond the basic page — documentation, provenance, facts-style apps. |
+| `engage`           | Adds engagement/ownership capabilities — claim, CRM, loyalty, interaction tracking. Top of the ladder today. |
+
+> These four one-liners are inferred from the tier names and ladder
+> ordering, not copied from an authoritative source — worth a sanity check
+> against the actual capability gating before treating them as precise.
+
+```ts
+const mode = cfg.system?.productMode;
+if (mode === 'simple_redirect' || mode === 'rich_redirect') {
+  // redirect-only surface — hide catalog UI
+}
+```
+
+Unknown values (future tiers your code predates) should fail closed to
+the nearest tier you understand, not throw or assume the top tier.
 
-String id of the tier. Sourced from Stripe subscription metadata
-(`basePlanId` or legacy `planId`). Examples: `simple_redirect`,
-`rich_redirect`, `inform`, `enrich`, `engage`, `hub_inform`,
-`hub_enrich`, `hub_engage`.
+Not a feature flag and not a billing key — per-capability gating still
+goes through `features` (§4.4); Stripe price selection still goes
+through `basePlanId` + add-ons.
 
 ### 4.2 `addOnKeys[]`
 
@@ -253,6 +293,7 @@ about:
 | Flag           | Gates                                                                 |
 | -------------- | ---------------------------------------------------------------------- |
 | `analytics`    | Analytics surfaces (dashboards, reporting, event exploration).       |
+| `authenticity` | Live authenticity tracking — flags genuine vs. counterfeit items and enables auditing/tracing on them (e.g. impossible-travel detection). |
 | `crm`          | Customer interaction / CRM — contact records, broadcasts, segments. Sub-features hang off the `crm.*` dotted prefix, e.g. `crm.broadcasts`, `crm.segments`. |
 | `hub`          | The Hub module.                                                      |
 | `portal`       | QR code scan portals.                                                |