@proveanything/smartlinks 1.15.10 → 1.15.13

package/dist/types/appConfiguration.d.ts

@@ -69,9 +69,25 @@ export interface AppliedOverridesSummary {
     accountType?: boolean;
     note?: string;
 }
+/**
+ * Capability ladder for `system.productMode`, low → high. See
+ * docs/appConfig.md §4.1 for what each tier unlocks. Not exhaustive going
+ * forward — `SystemBlock.productMode` accepts this union for autocomplete
+ * but also any other string, since future tiers will show up as new values
+ * before this type is updated to know about them.
+ */
+export type ProductMode = 'simple_redirect' | 'rich_redirect' | 'inform' | 'engage';
 /** Resolved entitlements — written only by `entitlements-reconcile`, safe for every client to read. */
 export interface SystemBlock {
+    /** Internal billing/plan identifier — see docs/appConfig.md §4.1. Not a capability signal; use `productMode` for that. */
     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 unlocked by add-ons. */
     apps?: string[];

package/dist/types/authKit.d.ts

@@ -120,6 +120,96 @@ export interface AppleLoginOptions {
  * in `SmartlinksApiError.details`.
  */
 export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED';
+/**
+ * Details carried on the `MFA_REQUIRED` error thrown by {@link authKit.login} when the
+ * client's MFA policy requires a step-up. Surfaced as `err.details` (or
+ * `err.errorResponse.details`) on the `SmartlinksApiError` — `login()` never resolves in
+ * this case, it throws a 403 instead.
+ */
+export interface MfaRequiredDetails {
+    /** Short-lived (10 min) and single-use. Pass it to every challenge/finalize call below. */
+    mfaSessionToken: string;
+    /** Only factors the user actually enrolled. */
+    availableFactors: Array<'email' | 'sms'>;
+    /** `sms` is preferred over `email` when both are enrolled. */
+    preferredFactor: 'email' | 'sms';
+    maskedDestinations: {
+        email?: string;
+        sms?: string;
+    };
+}
+/** Response from {@link authKit.mfaChallengeSend}. */
+export interface MfaChallengeSendResponse {
+    success: true;
+    factor: 'email' | 'sms';
+    /** Masked, e.g. `"j***@x.com"` or `"+1******1234"`. */
+    destination: string;
+    /** ISO timestamp, 10 minutes from send. */
+    expiresAt: string;
+}
+/**
+ * Response from {@link authKit.mfaChallengeVerify} / {@link authKit.mfaRecoveryCode}.
+ * Same shape as a normal login response, plus trusted-device fields when the caller sent
+ * `trustDevice: true`.
+ */
+export interface MfaFinalizeResponse extends AuthLoginResponse {
+    /**
+     * Present only when the challenge was completed with `trustDevice: true`. Persist it
+     * alongside the refresh token (same secure storage) and send it as `trustedDeviceToken`
+     * on future {@link authKit.login} calls to skip the challenge on this device.
+     */
+    trustedDeviceToken?: string;
+    trustedDeviceExpiresAt?: string;
+}
+/** Response from {@link authKit.enrollEmailMfa} / {@link authKit.enrollSmsMfa}. */
+export interface MfaEnrollSendResponse {
+    mfaSessionToken: string;
+    destination: string;
+    expiresAt: string;
+}
+/** Response from {@link authKit.confirmEmailMfa} / {@link authKit.confirmSmsMfa}. */
+export interface MfaEnrolledResponse {
+    enrolled: true;
+    factor: 'email' | 'sms';
+}
+/** Response from {@link authKit.getMfaFactors}. */
+export interface MfaFactorsResponse {
+    enrolledFactors: {
+        email?: {
+            enrolledAt: string;
+            destination: string;
+        };
+        sms?: {
+            enrolledAt: string;
+            destination: string;
+        };
+    };
+    recoveryCodesRemaining: number;
+    mfaEnabledForClient: boolean;
+}
+/** One entry from {@link authKit.listTrustedDevices}. */
+export interface TrustedDevice {
+    id: string;
+    label: string | null;
+    createdAtMs: number;
+    lastUsedAtMs: number;
+    expiresAtMs: number;
+}
+/**
+ * Server-defined error codes for the step-up MFA flow, surfaced via
+ * `SmartlinksApiError.errorCode`.
+ *
+ * - `MFA_REQUIRED` (403) — from {@link authKit.login} only; see {@link MfaRequiredDetails}.
+ * - `INVALID_MFA_CODE` (401) — wrong code; let the user retry (attempts are capped, see next).
+ * - `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 (or disabled for the
+ *   client) — a 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; restart the enroll/challenge flow.
+ * - `RECOVERY_CODE_INVALID` (401) — wrong or already-used recovery code.
+ */
+export type MfaErrorCode = 'MFA_REQUIRED' | 'INVALID_MFA_CODE' | 'MFA_TOO_MANY_ATTEMPTS' | 'MFA_FACTOR_NOT_ENROLLED' | 'MFA_SESSION_EXPIRED' | 'MFA_SESSION_INVALID' | 'RECOVERY_CODE_INVALID';
 export interface MagicLinkSendResponse {
     success: boolean;
     message: string;

package/dist/utils/conditions.d.ts

@@ -122,23 +122,19 @@ export interface ValueCondition extends BaseCondition {
  *   passed but didn't resolve" — see `invalidProof` below for that case.
  * - **Authenticity** (reads `params.itemContext` — see `ItemContext`,
  *   docs/item-context.md): `isAuthentic`, `notAuthentic`, `invalidProof`,
- *   `isFirstScan`, `isRescan`.
+ *   `isRescan`.
  *   - `invalidProof` is specifically "an identifier was passed and resolution
  *     was attempted, but it came back invalid or not-found" — the "someone
  *     scanned a fake tag / typed a bad serial" case, as opposed to `noProof`
  *     ("nothing was on the URL to check at all").
- *   - `isAuthentic` is true for both a fresh tap and a rescan — use
- *     `isFirstScan` / `isRescan` when the fresh-vs-duplicate distinction
- *     matters. `isFirstScan` is the common "this is good, show the full
- *     experience" check (authentic AND not seen before, `status === 'valid'`).
- *     `isRescan` is authentic but a duplicate/replayed tap
- *     (`status === 'rescan'`) — e.g. a page refresh or the back button —
- *     for suppressing "first scan" celebration UX without treating the tag
- *     as fake.
+ *   - `isAuthentic` is true for both a fresh tap and a rescan. `isRescan` is
+ *     authentic but a duplicate/replayed tap (`status === 'rescan'`) — e.g.
+ *     a page refresh or the back button — for suppressing "first scan"
+ *     celebration UX without treating the tag as fake.
  */
 export interface ItemStatusCondition extends BaseCondition {
     type: 'itemStatus';
-    statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual' | 'isAuthentic' | 'notAuthentic' | 'invalidProof' | 'isFirstScan' | 'isRescan';
+    statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual' | 'isAuthentic' | 'notAuthentic' | 'invalidProof' | 'isRescan';
 }
 /**
  * Facet-based condition — gates on the facet values assigned to the current product.
@@ -330,7 +326,7 @@ export interface ConditionDebugOptions {
  * - **value** - Custom field comparisons
  * - **itemStatus** - Proof/item status checks: claimable, virtual, presence
  *   (`hasProof`/`noProof`), and authenticity (`isAuthentic`/`notAuthentic`/
- *   `invalidProof`/`isFirstScan`/`isRescan`)
+ *   `invalidProof`/`isRescan`)
  * - **condition** - Nested condition references
  *
  * Conditions can be combined with AND or OR logic.

package/dist/utils/conditions.js

@@ -175,7 +175,7 @@ async function evaluateConditionEntry(condition, params) {
  * - **value** - Custom field comparisons
  * - **itemStatus** - Proof/item status checks: claimable, virtual, presence
  *   (`hasProof`/`noProof`), and authenticity (`isAuthentic`/`notAuthentic`/
- *   `invalidProof`/`isFirstScan`/`isRescan`)
+ *   `invalidProof`/`isRescan`)
  * - **condition** - Nested condition references
  *
  * Conditions can be combined with AND or OR logic.
@@ -819,7 +819,7 @@ async function validateFacet(condition, params) {
  * Validate item status condition
  */
 async function validateItemStatus(condition, params) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     switch (condition.statusType) {
         case 'isClaimable':
             return {
@@ -869,17 +869,11 @@ async function validateItemStatus(condition, params) {
                 detail: 'Checked that resolution was attempted and came back invalid or not-found (as opposed to noProof, where nothing was attempted at all).',
                 context: { itemContextStatus: (_f = params.itemContext) === null || _f === void 0 ? void 0 : _f.status },
             };
-        case 'isFirstScan':
-            return {
-                passed: ((_g = params.itemContext) === null || _g === void 0 ? void 0 : _g.status) === 'valid',
-                detail: 'Checked that itemContext is authentic and this is the first time it has been seen (status === valid, not rescan).',
-                context: { itemContextStatus: (_h = params.itemContext) === null || _h === void 0 ? void 0 : _h.status },
-            };
         case 'isRescan':
             return {
-                passed: ((_j = params.itemContext) === null || _j === void 0 ? void 0 : _j.status) === 'rescan' || !!((_k = params.itemContext) === null || _k === void 0 ? void 0 : _k.isRescan),
+                passed: ((_g = params.itemContext) === null || _g === void 0 ? void 0 : _g.status) === 'rescan' || !!((_h = params.itemContext) === null || _h === void 0 ? void 0 : _h.isRescan),
                 detail: 'Checked that itemContext is authentic but a duplicate/replayed tap (status === rescan).',
-                context: { itemContextStatus: (_l = params.itemContext) === null || _l === void 0 ? void 0 : _l.status },
+                context: { itemContextStatus: (_j = params.itemContext) === null || _j === void 0 ? void 0 : _j.status },
             };
         default:
             return {

package/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/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/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.                                                |