@proveanything/smartlinks 1.15.10 → 1.15.11

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.11  |  Generated: 2026-07-20T13:46:09.781Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1419,6 +1419,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 +1456,8 @@ interface AppConfigSettings {
 }
 ```
 
+**ProductMode** = `'simple_redirect' | 'rich_redirect' | 'inform' | 'engage'`
+
 ### appManifest
 
 **AppBundle** (interface)

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

package/dist/docs/item-context.md

@@ -163,8 +163,7 @@ const showFakeWarning = await validateCondition({
 - `isAuthentic` — passes when `itemContext.isAuthentic` is true (`valid`/`rescan`)
 - `notAuthentic` — passes when an `itemContext` was resolved but isn't authentic (`invalid`/`not-found`/`error`)
 - `invalidProof` — passes specifically when resolution was attempted and came back `invalid` or `not-found` — the "someone scanned a fake tag / typed a bad serial" case, as distinct from `noProof` ("nothing was on the URL to check at all")
-- `isFirstScan` — the single "this is good, show the full experience" check: authentic AND this is the first time it's been seen (`status === 'valid'`)
-- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both `isFirstScan` and `isRescan` cases
+- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both a fresh tap and a rescan
 
 ## Deprecated
 

package/dist/docs/utils.md

@@ -530,9 +530,9 @@ await utils.validateCondition({
 Status types:
 - Claim/ownership (reads `proof`): `'isClaimable'`, `'notClaimable'`, `'isVirtual'`, `'notVirtual'`
 - Presence (reads `proof`): `'hasProof'`, `'noProof'` — `noProof` only means *nothing was attempted*, not that an attempt failed
-- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isFirstScan'`, `'isRescan'`
+- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isRescan'`
   - `invalidProof` is specifically "an identifier was passed and resolution came back `invalid`/`not-found`", distinct from `noProof`'s "nothing on the URL to check at all"
-  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isFirstScan` (authentic AND `status === 'valid'`) as the single "this is good, show the full experience" check, and `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
+  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
 
 #### Version Conditions
 For A/B testing or versioned content:

package/dist/openapi.yaml

@@ -15666,6 +15666,9 @@ components:
       properties:
         basePlanId:
           type: string
+        productMode:
+          type: object
+          additionalProperties: true
         addOnKeys:
           type: array
           items:

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/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.11  |  Generated: 2026-07-20T13:46:09.781Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1419,6 +1419,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 +1456,8 @@ interface AppConfigSettings {
 }
 ```
 
+**ProductMode** = `'simple_redirect' | 'rich_redirect' | 'inform' | 'engage'`
+
 ### appManifest
 
 **AppBundle** (interface)

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

package/docs/item-context.md

@@ -163,8 +163,7 @@ const showFakeWarning = await validateCondition({
 - `isAuthentic` — passes when `itemContext.isAuthentic` is true (`valid`/`rescan`)
 - `notAuthentic` — passes when an `itemContext` was resolved but isn't authentic (`invalid`/`not-found`/`error`)
 - `invalidProof` — passes specifically when resolution was attempted and came back `invalid` or `not-found` — the "someone scanned a fake tag / typed a bad serial" case, as distinct from `noProof` ("nothing was on the URL to check at all")
-- `isFirstScan` — the single "this is good, show the full experience" check: authentic AND this is the first time it's been seen (`status === 'valid'`)
-- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both `isFirstScan` and `isRescan` cases
+- `isRescan` — authentic but a duplicate/replayed tap (`status === 'rescan'`) — use this to suppress "first scan" celebration UX without treating the tag as fake; `isAuthentic` alone is true for both a fresh tap and a rescan
 
 ## Deprecated
 

package/docs/utils.md

@@ -530,9 +530,9 @@ await utils.validateCondition({
 Status types:
 - Claim/ownership (reads `proof`): `'isClaimable'`, `'notClaimable'`, `'isVirtual'`, `'notVirtual'`
 - Presence (reads `proof`): `'hasProof'`, `'noProof'` — `noProof` only means *nothing was attempted*, not that an attempt failed
-- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isFirstScan'`, `'isRescan'`
+- Authenticity (reads `itemContext`): `'isAuthentic'`, `'notAuthentic'`, `'invalidProof'`, `'isRescan'`
   - `invalidProof` is specifically "an identifier was passed and resolution came back `invalid`/`not-found`", distinct from `noProof`'s "nothing on the URL to check at all"
-  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isFirstScan` (authentic AND `status === 'valid'`) as the single "this is good, show the full experience" check, and `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
+  - `isAuthentic` is true for both a fresh tap and a rescan. Use `isRescan` (authentic but `status === 'rescan'`) to suppress "first scan" celebration UX without treating the tag as fake
 
 #### Version Conditions
 For A/B testing or versioned content:

package/openapi.yaml

@@ -15666,6 +15666,9 @@ components:
       properties:
         basePlanId:
           type: string
+        productMode:
+          type: object
+          additionalProperties: true
         addOnKeys:
           type: array
           items:

package/package.json

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