@proveanything/smartlinks 1.15.8 → 1.15.10

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.8  |  Generated: 2026-07-19T09:55:23.623Z
+Version: 1.15.10  |  Generated: 2026-07-19T13:35:07.171Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5878,6 +5878,23 @@ interface InteractionEventContext {
 
 **EffectConfig** = ``
 
+### itemContext
+
+**ItemContext** (interface)
+```typescript
+interface ItemContext {
+  isAuthentic: boolean
+  status: ItemContextStatus
+  source: 'nfc' | 'serial'
+  errorMessage?: string
+  isRescan?: boolean
+  tag?: TagContext
+  checkedAt: number
+}
+```
+
+**ItemContextStatus** = ``
+
 ### jobs
 
 **Job** (interface)
@@ -6408,6 +6425,24 @@ interface NfcClaimTagRequest {
 }
 ```
 
+**TagContext** (interface)
+```typescript
+interface TagContext {
+  status: TagStatus
+  tagId?: string
+  claimSetId?: string
+  codeId?: string
+  count?: number
+  previousCount?: number
+  data?: Record<string, unknown>
+  source: 'nfc-validate' | 'nfc-lookup' | 'tag-index' | 'none'
+  validatedAt: number
+  errorMessage?: string
+}
+```
+
+**TagStatus** = `'valid' | 'rescan' | 'invalid' | 'error'`
+
 ### order
 
 **OrderItem** (interface)
@@ -7692,6 +7727,15 @@ interface SmartLinksWidgetProps {
   * accepted for backward compatibility.
   onNavigate?: (request: NavigationRequest | string) => void
   publicPortalUrl?: string
+  * Authenticity context for the specific item (proof) the URL points at,
+  * resolved via an NFC tap or a serial proof URL. `undefined` for
+  * collection- and product-only URLs, where there's no item to verify.
+  * See docs/item-context.md.
+  itemContext?: ItemContext
+  * @deprecated Use `itemContext.tag` instead. Kept for one release for
+  * backward compatibility with scanner-aware apps that read raw NFC/SUN
+  * data directly. See docs/item-context.md.
+  tag?: TagContext
   size?: 'compact' | 'standard' | 'large'
   lang?: string
   translations?: Record<string, string>
@@ -7861,6 +7905,7 @@ interface ConditionParams {
   product?: ProductInfo
   proof?: ProofInfo
   collection?: CollectionInfo
+  itemContext?: ItemContext
   stats?: StatsInfo
   fetchCondition?: (collectionId: string, conditionId: string) => Promise<ConditionSet | null>
   getLocation?: () => Promise<{ latitude: number; longitude: number }>

package/dist/docs/containers.md

@@ -231,6 +231,8 @@ All standard widget props apply:
 | `productId`       | string         | ❌       | Product context                         |
 | `proofId`         | string         | ❌       | Proof context                           |
 | `user`            | object         | ❌       | Current user info                       |
+| `itemContext`     | `ItemContext`  | ❌       | Authenticity context for the specific item (proof) the URL points at; `undefined` for collection/product-only URLs — see [item-context.md](item-context.md) |
+| `tag`             | `TagContext`   | ❌       | **Deprecated** — use `itemContext.tag` instead. Kept for one release. |
 | `onNavigate`      | function       | ❌       | Navigation callback (accepts `NavigationRequest` or legacy string) |
 | `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
 | `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |

package/dist/docs/item-context.md

@@ -0,0 +1,184 @@
+# Item Context (container prop)
+
+> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
+
+When the URL points at a specific item — either a **serial proof URL** or an
+**NFC tap** — the portal derives an `ItemContext` describing what it found
+and hands it to the container as the **`itemContext`** prop.
+
+For collection- and product-only URLs there is no item to describe, so
+`itemContext` is `undefined`. Sub-apps that don't care about authenticity
+can simply ignore the prop.
+
+The prop is named `itemContext` (not `item`) to make clear it's *context
+about the item*, not the item record itself. The underlying record is
+passed separately via `proof`, `product` and `collection` props.
+
+```tsx
+export default function MyContainer({ itemContext, collection, product, proof }) {
+  if (!itemContext) {
+    // Collection or product view — nothing to verify.
+    return <BrowseView collection={collection} product={product} />;
+  }
+  if (itemContext.isAuthentic) {
+    return <RealContent proof={proof} />;
+  }
+  if (itemContext.status === 'not-found' || itemContext.status === 'invalid') {
+    return <NotGenuine message={itemContext.errorMessage} />;
+  }
+  // status === 'error' — transport failure
+  return <TransientError message={itemContext.errorMessage} />;
+}
+```
+
+---
+
+## Shape
+
+```ts
+interface ItemContext {
+  /** True only for `valid` and `rescan`. Read this for the simple case. */
+  isAuthentic: boolean;
+
+  status:
+    | 'valid'        // genuine
+    | 'rescan'       // genuine, but this exact NFC tap has been seen before
+    | 'invalid'      // SDK rejected the NFC payload (bad crypto)
+    | 'not-found'    // identifier well-formed but 404
+    | 'error';       // transport / network failure — cannot tell
+
+  source: 'nfc' | 'serial';
+
+  /** Set for `invalid` / `not-found` / `error`. Safe to display. */
+  errorMessage?: string;
+
+  /** True when SDK reports this exact NFC tap was seen before. */
+  isRescan?: boolean;
+
+  /** Full NFC payload (SUN counter, tagId, claimSetId, codeId, mirror…). Present only when source === 'nfc'. */
+  tag?: TagContext;
+
+  /** Epoch ms when the check was derived. */
+  checkedAt: number;
+}
+```
+
+Also exported from `@proveanything/smartlinks` as `ItemContext` /
+`ItemContextStatus` (`src/types/itemContext.ts`). The nested `TagContext`
+shape is unchanged (`src/types/nfc.ts`).
+
+## When `itemContext` is present
+
+| URL points at                                  | itemContext         |
+| ---------------------------------------------- | -------------------- |
+| Collection root                                | `undefined`          |
+| Product page (no proof)                        | `undefined`          |
+| Serial proof URL (any outcome)                 | present, source `serial` |
+| NFC tap (any outcome)                          | present, source `nfc`    |
+
+## Status matrix (when present)
+
+| Situation                                             | source   | status        | isAuthentic |
+| ----------------------------------------------------- | -------- | ------------- | :---------: |
+| Fresh NFC tap, SUN counter validated                  | `nfc`    | `valid`       | ✅          |
+| Same NFC tap replayed / refresh                       | `nfc`    | `rescan`      | ✅          |
+| NFC payload rejected (bad crypto / bad params)        | `nfc`    | `invalid`     | ❌          |
+| Serial proof URL, proof fetched OK                    | `serial` | `valid`       | ✅          |
+| Serial proof URL, proof returned 404                  | `serial` | `not-found`   | ❌          |
+| Network / 5xx while resolving proof or NFC            | (either) | `error`       | ❌          |
+
+`isAuthentic === (status === 'valid' || status === 'rescan')`.
+
+## How it's delivered
+
+**Direct-mounted containers** (default public mode):
+
+```tsx
+type Props = {
+  collection: Collection;
+  product?: Product;
+  proof?: Proof;
+  itemContext?: ItemContext;     // ← only when URL targets a specific item
+  // …plus the normal navigation / theme / auth props
+};
+```
+
+NFC-aware apps that need the raw SUN / tag payload read `itemContext.tag`.
+
+**Iframe containers**: the portal serialises `ItemContext` to JSON, base64-
+encodes it (UTF-8 safe) and appends it as an `itemContext` query param on
+the iframe URL — omitted entirely when there is no item context:
+
+```ts
+function readItemContext(): ItemContext | undefined {
+  const raw = new URLSearchParams(location.search).get('itemContext');
+  if (!raw) return undefined;
+  try { return JSON.parse(decodeURIComponent(escape(atob(raw)))); }
+  catch { return undefined; }
+}
+```
+
+## Guarantees
+
+- `itemContext` is present on every container mount whose URL targeted an
+  item (proof or NFC tap). Absent otherwise.
+- `SL.nfc.validate` is called at most once per `(claimSetId, codeId)` per
+  browser session — SUN counters are never double-consumed on refresh.
+- SSR uses `SL.nfc.lookupTag` (non-consuming) only.
+- `isAuthentic === true` implies the SDK either validated an NFC payload
+  or returned a full proof document. It is never inferred from URL shape.
+- The portal will **not** render its full-page error surface for a 404 on
+  a proof — that surfaces as `status: 'not-found'` on `itemContext`, and
+  the container is still mounted so it can present the message its own way.
+
+## What containers should do
+
+| Status        | Recommended UI                                                    |
+| ------------- | ------------------------------------------------------------------ |
+| `valid`       | Full experience. Show ownership, actions, etc.                    |
+| `rescan`      | Same as `valid`, optionally with a subtle "seen before" hint.     |
+| `invalid`     | Clear "this doesn't look genuine" message. Do NOT reveal data.    |
+| `not-found`   | "We don't recognise this item." Offer a link home.                 |
+| `error`       | Neutral "couldn't verify right now." Offer retry.                  |
+| _absent_      | Standard browse UI. Don't mention authenticity at all.             |
+
+## Gating UX with conditions
+
+Sub-apps should standardize on passing `itemContext` into `validateCondition()`
+and gating with `itemStatus` — the same condition type already used for
+claim/virtual checks, extended with authenticity `statusType`s that read
+`itemContext` instead of `proof`:
+
+```ts
+import { validateCondition } from '@proveanything/smartlinks';
+
+const showFakeWarning = await validateCondition({
+  condition: {
+    conditions: [{ type: 'itemStatus', statusType: 'invalidProof' }],
+  },
+  itemContext, // the prop delivered to the container
+});
+```
+
+- `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
+
+## Deprecated
+
+The old top-level `tag` prop (`TagContext`) is still forwarded for one
+release for backward compatibility with scanner-aware apps that read raw
+SUN data. New code should read `itemContext.tag` and treat `itemContext`
+as the source of truth.
+
+## Note on terminology
+
+Today the SDK still uses `proof` for a specific item record (a serialised
+instance of a product). "Item record" is under consideration as a clearer
+name — no API changes are planned imminently, but a future SDK version may
+support both `proof`- and `item record`-shaped names for the same
+functions/types side by side. `itemContext` is deliberately future-proof:
+it describes context about whatever the URL points at, regardless of what
+we ultimately call the record itself.

package/dist/docs/utils.md

@@ -485,9 +485,12 @@ await utils.validateCondition({
 ```
 
 #### Item Status Conditions
-Check proof/item status:
+Check proof/item status — claim/ownership state, and authenticity of the
+item (proof) the URL points at (via NFC tap or serial proof URL — see
+[item-context.md](item-context.md)):
 
 ```typescript
+// Claim/ownership — unchanged, reads `proof`
 await utils.validateCondition({
   condition: {
     type: 'and',
@@ -498,9 +501,38 @@ await utils.validateCondition({
   },
   proof: { claimable: true }
 })
+
+// Authenticity — reads `itemContext`
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{
+      type: 'itemStatus',
+      statusType: 'invalidProof'
+    }]
+  },
+  itemContext: { isAuthentic: false, status: 'invalid', source: 'nfc', checkedAt: Date.now() }
+})
+
+// Fresh scan vs. duplicate/replayed scan — both authentic, different UX
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{
+      type: 'itemStatus',
+      statusType: 'isRescan'
+    }]
+  },
+  itemContext: { isAuthentic: true, status: 'rescan', source: 'nfc', checkedAt: Date.now() }
+})
 ```
 
-Status types: `'isClaimable'`, `'notClaimable'`, `'noProof'`, `'hasProof'`, `'isVirtual'`, `'notVirtual'`
+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'`
+  - `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
 
 #### Version Conditions
 For A/B testing or versioned content:
@@ -720,6 +752,7 @@ See [examples/utils-demo.ts](../examples/utils-demo.ts) for comprehensive exampl
 - **[API Summary](API_SUMMARY.md)** - Complete SDK reference with all namespaces and functions
 - **[QR Codes](API_SUMMARY.md#qr)** - QR code lookup functions that work with generated paths
 - **[NFC](API_SUMMARY.md#nfc)** - NFC tag claiming and validation
+- **[Item Context](item-context.md)** - `itemContext` prop delivered to containers describing the item (proof) the URL points at and whether it's authentic
 - **[Collections](API_SUMMARY.md#collection)** - Collection management functions
 - **[Products](API_SUMMARY.md#product)** - Product CRUD operations
 - **[Batches](API_SUMMARY.md#batch)** - Batch management

package/dist/docs/widgets.md

@@ -159,6 +159,13 @@ interface SmartLinksWidgetProps {
   // Base URL to the full public portal for deep linking
   publicPortalUrl?: string;
   
+  // Authenticity context for the specific item (proof) the URL points at.
+  // undefined for collection- and product-only URLs.
+  itemContext?: ItemContext;
+  
+  // @deprecated Use itemContext.tag instead — kept for one release
+  tag?: TagContext;
+  
   // Size hint for responsive rendering
   size?: 'compact' | 'standard' | 'large';
   
@@ -180,6 +187,8 @@ interface SmartLinksWidgetProps {
 | `SL` | `typeof SL` | Pre-initialized SmartLinks SDK |
 | `onNavigate` | `function?` | Callback to navigate within parent app (accepts `NavigationRequest` or legacy string) |
 | `publicPortalUrl` | `string?` | Base URL to full portal for deep links |
+| `itemContext` | `ItemContext?` | Authenticity context for the specific item (proof) the URL points at; `undefined` for collection/product-only URLs — see [item-context.md](item-context.md) |
+| `tag` | `TagContext?` | **Deprecated** — use `itemContext.tag` instead. Kept for one release. |
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |

package/dist/openapi.yaml

@@ -22203,6 +22203,31 @@ components:
         - metadata
         - broadcastId
         - journeyId
+    ItemContext:
+      type: object
+      properties:
+        isAuthentic:
+          type: boolean
+        status:
+          $ref: "#/components/schemas/ItemContextStatus"
+        source:
+          type: string
+          enum:
+            - nfc
+            - serial
+        errorMessage:
+          type: string
+        isRescan:
+          type: boolean
+        tag:
+          $ref: "#/components/schemas/TagContext"
+        checkedAt:
+          type: number
+      required:
+        - isAuthentic
+        - status
+        - source
+        - checkedAt
     Job:
       type: object
       properties:
@@ -23034,6 +23059,39 @@ components:
         - claimSetId
         - codeId
         - data
+    TagContext:
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/TagStatus"
+        tagId:
+          type: string
+        claimSetId:
+          type: string
+        codeId:
+          type: string
+        count:
+          type: number
+        previousCount:
+          type: number
+        data:
+          type: object
+          additionalProperties: true
+        source:
+          type: string
+          enum:
+            - nfc-validate
+            - nfc-lookup
+            - tag-index
+            - none
+        validatedAt:
+          type: number
+        errorMessage:
+          type: string
+      required:
+        - status
+        - source
+        - validatedAt
     OrderItem:
       type: object
       properties:
@@ -25211,6 +25269,10 @@ components:
           additionalProperties: true
         publicPortalUrl:
           type: string
+        itemContext:
+          $ref: "#/components/schemas/ItemContext"
+        tag:
+          $ref: "#/components/schemas/TagContext"
         size:
           type: string
           enum:

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export * from "./claimSet";
 export * from "./auth";
 export * from "./comms";
 export * from "./nfc";
+export * from "./itemContext";
 export * from "./contact";
 export * from "./broadcasts";
 export * from "./segments";

package/dist/types/index.js

@@ -13,6 +13,7 @@ export * from "./claimSet";
 export * from "./auth";
 export * from "./comms";
 export * from "./nfc";
+export * from "./itemContext";
 export * from "./contact";
 export * from "./broadcasts";
 export * from "./segments";

package/dist/types/itemContext.d.ts

@@ -0,0 +1,30 @@
+import type { TagContext } from './nfc';
+/**
+ * Authenticity status for a specific item — a proof, resolved via an NFC
+ * tap or a serial proof URL. Collection- and product-only URLs have no
+ * item to describe, so there is no "nothing checkable" status here: absence
+ * of an `ItemContext` altogether is how that case is represented (see the
+ * `itemContext` prop on `SmartLinksWidgetProps`).
+ */
+export type ItemContextStatus = 'valid' | 'rescan' | 'invalid' | 'not-found' | 'error';
+/**
+ * Describes a specific item the current URL points at and whether it's
+ * authentic — delivered to containers as the `itemContext` prop.
+ * Supersedes the NFC-only `TagContext`: still available, nested at
+ * `itemContext.tag`, and for one release also as a deprecated top-level
+ * `tag` prop. See docs/item-context.md.
+ */
+export interface ItemContext {
+    /** True only for `valid` and `rescan`. Read this for the simple case. */
+    isAuthentic: boolean;
+    status: ItemContextStatus;
+    source: 'nfc' | 'serial';
+    /** Set for `invalid` / `not-found` / `error`. Safe to display. */
+    errorMessage?: string;
+    /** True when the SDK reports this exact NFC tap was seen before. */
+    isRescan?: boolean;
+    /** Full NFC payload (SUN counter, tagId, claimSetId, codeId, mirror…). Present only when `source === 'nfc'`. */
+    tag?: TagContext;
+    /** Epoch ms when the check was derived. */
+    checkedAt: number;
+}

package/dist/types/itemContext.js

@@ -0,0 +1,2 @@
+// src/types/itemContext.ts
+export {};

package/dist/types/nfc.d.ts

@@ -39,3 +39,41 @@ export interface NfcClaimTagRequest {
     codeId: string;
     data: Record<string, any>;
 }
+/**
+ * Outcome of validating the NFC/QR tag that brought the visitor to a
+ * SmartLinks app.
+ *
+ * - `valid` — fresh, genuine tap. SUN counter advanced (or a non-consuming
+ *   lookup succeeded).
+ * - `rescan` — genuine tag, but this exact tap was already seen (refresh,
+ *   back button, or a non-advancing SUN counter).
+ * - `invalid` — validation rejected the payload outright (bad crypto,
+ *   unknown tag, tampered URL) — i.e. a fake/counterfeit tag or serial.
+ * - `error` — network/transport failure; authenticity could not be
+ *   confirmed either way.
+ */
+export type TagStatus = 'valid' | 'rescan' | 'invalid' | 'error';
+/**
+ * Result of resolving the tag identifiers on the entry URL, handed to
+ * sub-apps so they can render status-appropriate UX instead of a generic
+ * error. See docs/tag-context.md for the full contract.
+ */
+export interface TagContext {
+    /** Always present when a `TagContext` is delivered at all. */
+    status: TagStatus;
+    /** Identifiers, when known. */
+    tagId?: string;
+    claimSetId?: string;
+    codeId?: string;
+    /** SUN counter values, present when validation returned them. */
+    count?: number;
+    previousCount?: number;
+    /** Arbitrary tag-level payload returned by validation/lookup. */
+    data?: Record<string, unknown>;
+    /** How the identifiers were resolved. */
+    source: 'nfc-validate' | 'nfc-lookup' | 'tag-index' | 'none';
+    /** Epoch ms at resolution time. */
+    validatedAt: number;
+    /** Human-readable message for `invalid` / `error`. */
+    errorMessage?: string;
+}

package/dist/types/widgets.d.ts

@@ -1,3 +1,5 @@
+import type { TagContext } from './nfc';
+import type { ItemContext } from './itemContext';
 /**
  * Structured navigation request emitted via the `onNavigate` prop when a
  * widget or container needs to navigate the parent platform shell to another
@@ -62,6 +64,19 @@ export interface SmartLinksWidgetProps {
     onNavigate?: (request: NavigationRequest | string) => void;
     /** Base URL of the full public portal, used for constructing deep links */
     publicPortalUrl?: string;
+    /**
+     * Authenticity context for the specific item (proof) the URL points at,
+     * resolved via an NFC tap or a serial proof URL. `undefined` for
+     * collection- and product-only URLs, where there's no item to verify.
+     * See docs/item-context.md.
+     */
+    itemContext?: ItemContext;
+    /**
+     * @deprecated Use `itemContext.tag` instead. Kept for one release for
+     * backward compatibility with scanner-aware apps that read raw NFC/SUN
+     * data directly. See docs/item-context.md.
+     */
+    tag?: TagContext;
     /** Responsive size hint */
     size?: 'compact' | 'standard' | 'large';
     /** BCP-47 language code (e.g. `'en'`, `'fr'`) */

package/dist/utils/conditions.d.ts

@@ -1,3 +1,4 @@
+import type { ItemContext } from '../types/itemContext';
 /**
  * Geographic region definitions for country-based conditions
  */
@@ -108,11 +109,36 @@ export interface ValueCondition extends BaseCondition {
     value: string | number | boolean;
 }
 /**
- * Item status condition
+ * Item status condition — one condition type for everything conditions
+ * need to know about "the item," so sub-apps don't have to juggle a
+ * separate authenticity condition alongside this one.
+ *
+ * Two families of `statusType`, kept in one enum on purpose:
+ * - **Claim/ownership** (unchanged): `isClaimable`, `notClaimable`,
+ *   `isVirtual`, `notVirtual`, `hasProof`, `noProof`. These read
+ *   `params.proof` — whether a resolved proof record was supplied at all,
+ *   and its claim/virtual flags. `noProof` only means "nothing was even
+ *   attempted"; it does NOT distinguish that from "an identifier was
+ *   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`.
+ *   - `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.
  */
 export interface ItemStatusCondition extends BaseCondition {
     type: 'itemStatus';
-    statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual';
+    statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual' | 'isAuthentic' | 'notAuthentic' | 'invalidProof' | 'isFirstScan' | 'isRescan';
 }
 /**
  * Facet-based condition — gates on the facet values assigned to the current product.
@@ -263,6 +289,8 @@ export interface ConditionParams {
     proof?: ProofInfo;
     /** Collection information */
     collection?: CollectionInfo;
+    /** Authenticity context for the item (proof) the URL points at, if any */
+    itemContext?: ItemContext;
     /** Statistics/tracking information */
     stats?: StatsInfo;
     /** Function to fetch conditions by ID (optional) */
@@ -300,7 +328,9 @@ export interface ConditionDebugOptions {
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons
- * - **itemStatus** - Proof/item status checks (claimable, virtual, etc.)
+ * - **itemStatus** - Proof/item status checks: claimable, virtual, presence
+ *   (`hasProof`/`noProof`), and authenticity (`isAuthentic`/`notAuthentic`/
+ *   `invalidProof`/`isFirstScan`/`isRescan`)
  * - **condition** - Nested condition references
  *
  * Conditions can be combined with AND or OR logic.

package/dist/utils/conditions.js

@@ -173,7 +173,9 @@ async function evaluateConditionEntry(condition, params) {
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons
- * - **itemStatus** - Proof/item status checks (claimable, virtual, etc.)
+ * - **itemStatus** - Proof/item status checks: claimable, virtual, presence
+ *   (`hasProof`/`noProof`), and authenticity (`isAuthentic`/`notAuthentic`/
+ *   `invalidProof`/`isFirstScan`/`isRescan`)
  * - **condition** - Nested condition references
  *
  * Conditions can be combined with AND or OR logic.
@@ -817,6 +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;
     switch (condition.statusType) {
         case 'isClaimable':
             return {
@@ -848,6 +851,36 @@ async function validateItemStatus(condition, params) {
                 passed: !!(params.proof && !params.proof.virtual),
                 detail: 'Checked proof.virtual for falsiness.',
             };
+        case 'isAuthentic':
+            return {
+                passed: !!((_a = params.itemContext) === null || _a === void 0 ? void 0 : _a.isAuthentic),
+                detail: 'Checked itemContext.isAuthentic for truthiness.',
+                context: { itemContextStatus: (_b = params.itemContext) === null || _b === void 0 ? void 0 : _b.status },
+            };
+        case 'notAuthentic':
+            return {
+                passed: !!(params.itemContext && !params.itemContext.isAuthentic),
+                detail: 'Checked that an itemContext was resolved and isAuthentic is false.',
+                context: { itemContextStatus: (_c = params.itemContext) === null || _c === void 0 ? void 0 : _c.status },
+            };
+        case 'invalidProof':
+            return {
+                passed: ((_d = params.itemContext) === null || _d === void 0 ? void 0 : _d.status) === 'invalid' || ((_e = params.itemContext) === null || _e === void 0 ? void 0 : _e.status) === 'not-found',
+                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),
+                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 },
+            };
         default:
             return {
                 passed: false,

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.8  |  Generated: 2026-07-19T09:55:23.623Z
+Version: 1.15.10  |  Generated: 2026-07-19T13:35:07.171Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5878,6 +5878,23 @@ interface InteractionEventContext {
 
 **EffectConfig** = ``
 
+### itemContext
+
+**ItemContext** (interface)
+```typescript
+interface ItemContext {
+  isAuthentic: boolean
+  status: ItemContextStatus
+  source: 'nfc' | 'serial'
+  errorMessage?: string
+  isRescan?: boolean
+  tag?: TagContext
+  checkedAt: number
+}
+```
+
+**ItemContextStatus** = ``
+
 ### jobs
 
 **Job** (interface)
@@ -6408,6 +6425,24 @@ interface NfcClaimTagRequest {
 }
 ```
 
+**TagContext** (interface)
+```typescript
+interface TagContext {
+  status: TagStatus
+  tagId?: string
+  claimSetId?: string
+  codeId?: string
+  count?: number
+  previousCount?: number
+  data?: Record<string, unknown>
+  source: 'nfc-validate' | 'nfc-lookup' | 'tag-index' | 'none'
+  validatedAt: number
+  errorMessage?: string
+}
+```
+
+**TagStatus** = `'valid' | 'rescan' | 'invalid' | 'error'`
+
 ### order
 
 **OrderItem** (interface)
@@ -7692,6 +7727,15 @@ interface SmartLinksWidgetProps {
   * accepted for backward compatibility.
   onNavigate?: (request: NavigationRequest | string) => void
   publicPortalUrl?: string
+  * Authenticity context for the specific item (proof) the URL points at,
+  * resolved via an NFC tap or a serial proof URL. `undefined` for
+  * collection- and product-only URLs, where there's no item to verify.
+  * See docs/item-context.md.
+  itemContext?: ItemContext
+  * @deprecated Use `itemContext.tag` instead. Kept for one release for
+  * backward compatibility with scanner-aware apps that read raw NFC/SUN
+  * data directly. See docs/item-context.md.
+  tag?: TagContext
   size?: 'compact' | 'standard' | 'large'
   lang?: string
   translations?: Record<string, string>
@@ -7861,6 +7905,7 @@ interface ConditionParams {
   product?: ProductInfo
   proof?: ProofInfo
   collection?: CollectionInfo
+  itemContext?: ItemContext
   stats?: StatsInfo
   fetchCondition?: (collectionId: string, conditionId: string) => Promise<ConditionSet | null>
   getLocation?: () => Promise<{ latitude: number; longitude: number }>

package/docs/containers.md

@@ -231,6 +231,8 @@ All standard widget props apply:
 | `productId`       | string         | ❌       | Product context                         |
 | `proofId`         | string         | ❌       | Proof context                           |
 | `user`            | object         | ❌       | Current user info                       |
+| `itemContext`     | `ItemContext`  | ❌       | Authenticity context for the specific item (proof) the URL points at; `undefined` for collection/product-only URLs — see [item-context.md](item-context.md) |
+| `tag`             | `TagContext`   | ❌       | **Deprecated** — use `itemContext.tag` instead. Kept for one release. |
 | `onNavigate`      | function       | ❌       | Navigation callback (accepts `NavigationRequest` or legacy string) |
 | `size`            | string         | ❌       | `"compact"`, `"standard"`, or `"large"` |
 | `lang`            | string         | ❌       | Language code (e.g., `"en"`)            |

package/docs/item-context.md

@@ -0,0 +1,184 @@
+# Item Context (container prop)
+
+> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
+
+When the URL points at a specific item — either a **serial proof URL** or an
+**NFC tap** — the portal derives an `ItemContext` describing what it found
+and hands it to the container as the **`itemContext`** prop.
+
+For collection- and product-only URLs there is no item to describe, so
+`itemContext` is `undefined`. Sub-apps that don't care about authenticity
+can simply ignore the prop.
+
+The prop is named `itemContext` (not `item`) to make clear it's *context
+about the item*, not the item record itself. The underlying record is
+passed separately via `proof`, `product` and `collection` props.
+
+```tsx
+export default function MyContainer({ itemContext, collection, product, proof }) {
+  if (!itemContext) {
+    // Collection or product view — nothing to verify.
+    return <BrowseView collection={collection} product={product} />;
+  }
+  if (itemContext.isAuthentic) {
+    return <RealContent proof={proof} />;
+  }
+  if (itemContext.status === 'not-found' || itemContext.status === 'invalid') {
+    return <NotGenuine message={itemContext.errorMessage} />;
+  }
+  // status === 'error' — transport failure
+  return <TransientError message={itemContext.errorMessage} />;
+}
+```
+
+---
+
+## Shape
+
+```ts
+interface ItemContext {
+  /** True only for `valid` and `rescan`. Read this for the simple case. */
+  isAuthentic: boolean;
+
+  status:
+    | 'valid'        // genuine
+    | 'rescan'       // genuine, but this exact NFC tap has been seen before
+    | 'invalid'      // SDK rejected the NFC payload (bad crypto)
+    | 'not-found'    // identifier well-formed but 404
+    | 'error';       // transport / network failure — cannot tell
+
+  source: 'nfc' | 'serial';
+
+  /** Set for `invalid` / `not-found` / `error`. Safe to display. */
+  errorMessage?: string;
+
+  /** True when SDK reports this exact NFC tap was seen before. */
+  isRescan?: boolean;
+
+  /** Full NFC payload (SUN counter, tagId, claimSetId, codeId, mirror…). Present only when source === 'nfc'. */
+  tag?: TagContext;
+
+  /** Epoch ms when the check was derived. */
+  checkedAt: number;
+}
+```
+
+Also exported from `@proveanything/smartlinks` as `ItemContext` /
+`ItemContextStatus` (`src/types/itemContext.ts`). The nested `TagContext`
+shape is unchanged (`src/types/nfc.ts`).
+
+## When `itemContext` is present
+
+| URL points at                                  | itemContext         |
+| ---------------------------------------------- | -------------------- |
+| Collection root                                | `undefined`          |
+| Product page (no proof)                        | `undefined`          |
+| Serial proof URL (any outcome)                 | present, source `serial` |
+| NFC tap (any outcome)                          | present, source `nfc`    |
+
+## Status matrix (when present)
+
+| Situation                                             | source   | status        | isAuthentic |
+| ----------------------------------------------------- | -------- | ------------- | :---------: |
+| Fresh NFC tap, SUN counter validated                  | `nfc`    | `valid`       | ✅          |
+| Same NFC tap replayed / refresh                       | `nfc`    | `rescan`      | ✅          |
+| NFC payload rejected (bad crypto / bad params)        | `nfc`    | `invalid`     | ❌          |
+| Serial proof URL, proof fetched OK                    | `serial` | `valid`       | ✅          |
+| Serial proof URL, proof returned 404                  | `serial` | `not-found`   | ❌          |
+| Network / 5xx while resolving proof or NFC            | (either) | `error`       | ❌          |
+
+`isAuthentic === (status === 'valid' || status === 'rescan')`.
+
+## How it's delivered
+
+**Direct-mounted containers** (default public mode):
+
+```tsx
+type Props = {
+  collection: Collection;
+  product?: Product;
+  proof?: Proof;
+  itemContext?: ItemContext;     // ← only when URL targets a specific item
+  // …plus the normal navigation / theme / auth props
+};
+```
+
+NFC-aware apps that need the raw SUN / tag payload read `itemContext.tag`.
+
+**Iframe containers**: the portal serialises `ItemContext` to JSON, base64-
+encodes it (UTF-8 safe) and appends it as an `itemContext` query param on
+the iframe URL — omitted entirely when there is no item context:
+
+```ts
+function readItemContext(): ItemContext | undefined {
+  const raw = new URLSearchParams(location.search).get('itemContext');
+  if (!raw) return undefined;
+  try { return JSON.parse(decodeURIComponent(escape(atob(raw)))); }
+  catch { return undefined; }
+}
+```
+
+## Guarantees
+
+- `itemContext` is present on every container mount whose URL targeted an
+  item (proof or NFC tap). Absent otherwise.
+- `SL.nfc.validate` is called at most once per `(claimSetId, codeId)` per
+  browser session — SUN counters are never double-consumed on refresh.
+- SSR uses `SL.nfc.lookupTag` (non-consuming) only.
+- `isAuthentic === true` implies the SDK either validated an NFC payload
+  or returned a full proof document. It is never inferred from URL shape.
+- The portal will **not** render its full-page error surface for a 404 on
+  a proof — that surfaces as `status: 'not-found'` on `itemContext`, and
+  the container is still mounted so it can present the message its own way.
+
+## What containers should do
+
+| Status        | Recommended UI                                                    |
+| ------------- | ------------------------------------------------------------------ |
+| `valid`       | Full experience. Show ownership, actions, etc.                    |
+| `rescan`      | Same as `valid`, optionally with a subtle "seen before" hint.     |
+| `invalid`     | Clear "this doesn't look genuine" message. Do NOT reveal data.    |
+| `not-found`   | "We don't recognise this item." Offer a link home.                 |
+| `error`       | Neutral "couldn't verify right now." Offer retry.                  |
+| _absent_      | Standard browse UI. Don't mention authenticity at all.             |
+
+## Gating UX with conditions
+
+Sub-apps should standardize on passing `itemContext` into `validateCondition()`
+and gating with `itemStatus` — the same condition type already used for
+claim/virtual checks, extended with authenticity `statusType`s that read
+`itemContext` instead of `proof`:
+
+```ts
+import { validateCondition } from '@proveanything/smartlinks';
+
+const showFakeWarning = await validateCondition({
+  condition: {
+    conditions: [{ type: 'itemStatus', statusType: 'invalidProof' }],
+  },
+  itemContext, // the prop delivered to the container
+});
+```
+
+- `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
+
+## Deprecated
+
+The old top-level `tag` prop (`TagContext`) is still forwarded for one
+release for backward compatibility with scanner-aware apps that read raw
+SUN data. New code should read `itemContext.tag` and treat `itemContext`
+as the source of truth.
+
+## Note on terminology
+
+Today the SDK still uses `proof` for a specific item record (a serialised
+instance of a product). "Item record" is under consideration as a clearer
+name — no API changes are planned imminently, but a future SDK version may
+support both `proof`- and `item record`-shaped names for the same
+functions/types side by side. `itemContext` is deliberately future-proof:
+it describes context about whatever the URL points at, regardless of what
+we ultimately call the record itself.

package/docs/utils.md

@@ -485,9 +485,12 @@ await utils.validateCondition({
 ```
 
 #### Item Status Conditions
-Check proof/item status:
+Check proof/item status — claim/ownership state, and authenticity of the
+item (proof) the URL points at (via NFC tap or serial proof URL — see
+[item-context.md](item-context.md)):
 
 ```typescript
+// Claim/ownership — unchanged, reads `proof`
 await utils.validateCondition({
   condition: {
     type: 'and',
@@ -498,9 +501,38 @@ await utils.validateCondition({
   },
   proof: { claimable: true }
 })
+
+// Authenticity — reads `itemContext`
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{
+      type: 'itemStatus',
+      statusType: 'invalidProof'
+    }]
+  },
+  itemContext: { isAuthentic: false, status: 'invalid', source: 'nfc', checkedAt: Date.now() }
+})
+
+// Fresh scan vs. duplicate/replayed scan — both authentic, different UX
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{
+      type: 'itemStatus',
+      statusType: 'isRescan'
+    }]
+  },
+  itemContext: { isAuthentic: true, status: 'rescan', source: 'nfc', checkedAt: Date.now() }
+})
 ```
 
-Status types: `'isClaimable'`, `'notClaimable'`, `'noProof'`, `'hasProof'`, `'isVirtual'`, `'notVirtual'`
+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'`
+  - `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
 
 #### Version Conditions
 For A/B testing or versioned content:
@@ -720,6 +752,7 @@ See [examples/utils-demo.ts](../examples/utils-demo.ts) for comprehensive exampl
 - **[API Summary](API_SUMMARY.md)** - Complete SDK reference with all namespaces and functions
 - **[QR Codes](API_SUMMARY.md#qr)** - QR code lookup functions that work with generated paths
 - **[NFC](API_SUMMARY.md#nfc)** - NFC tag claiming and validation
+- **[Item Context](item-context.md)** - `itemContext` prop delivered to containers describing the item (proof) the URL points at and whether it's authentic
 - **[Collections](API_SUMMARY.md#collection)** - Collection management functions
 - **[Products](API_SUMMARY.md#product)** - Product CRUD operations
 - **[Batches](API_SUMMARY.md#batch)** - Batch management

package/docs/widgets.md

@@ -159,6 +159,13 @@ interface SmartLinksWidgetProps {
   // Base URL to the full public portal for deep linking
   publicPortalUrl?: string;
   
+  // Authenticity context for the specific item (proof) the URL points at.
+  // undefined for collection- and product-only URLs.
+  itemContext?: ItemContext;
+  
+  // @deprecated Use itemContext.tag instead — kept for one release
+  tag?: TagContext;
+  
   // Size hint for responsive rendering
   size?: 'compact' | 'standard' | 'large';
   
@@ -180,6 +187,8 @@ interface SmartLinksWidgetProps {
 | `SL` | `typeof SL` | Pre-initialized SmartLinks SDK |
 | `onNavigate` | `function?` | Callback to navigate within parent app (accepts `NavigationRequest` or legacy string) |
 | `publicPortalUrl` | `string?` | Base URL to full portal for deep links |
+| `itemContext` | `ItemContext?` | Authenticity context for the specific item (proof) the URL points at; `undefined` for collection/product-only URLs — see [item-context.md](item-context.md) |
+| `tag` | `TagContext?` | **Deprecated** — use `itemContext.tag` instead. Kept for one release. |
 | `size` | `string?` | Size hint: 'compact', 'standard', or 'large' |
 | `lang` | `string?` | Language code (e.g., 'en', 'de', 'fr') |
 | `translations` | `object?` | Translation overrides |

package/openapi.yaml

@@ -22203,6 +22203,31 @@ components:
         - metadata
         - broadcastId
         - journeyId
+    ItemContext:
+      type: object
+      properties:
+        isAuthentic:
+          type: boolean
+        status:
+          $ref: "#/components/schemas/ItemContextStatus"
+        source:
+          type: string
+          enum:
+            - nfc
+            - serial
+        errorMessage:
+          type: string
+        isRescan:
+          type: boolean
+        tag:
+          $ref: "#/components/schemas/TagContext"
+        checkedAt:
+          type: number
+      required:
+        - isAuthentic
+        - status
+        - source
+        - checkedAt
     Job:
       type: object
       properties:
@@ -23034,6 +23059,39 @@ components:
         - claimSetId
         - codeId
         - data
+    TagContext:
+      type: object
+      properties:
+        status:
+          $ref: "#/components/schemas/TagStatus"
+        tagId:
+          type: string
+        claimSetId:
+          type: string
+        codeId:
+          type: string
+        count:
+          type: number
+        previousCount:
+          type: number
+        data:
+          type: object
+          additionalProperties: true
+        source:
+          type: string
+          enum:
+            - nfc-validate
+            - nfc-lookup
+            - tag-index
+            - none
+        validatedAt:
+          type: number
+        errorMessage:
+          type: string
+      required:
+        - status
+        - source
+        - validatedAt
     OrderItem:
       type: object
       properties:
@@ -25211,6 +25269,10 @@ components:
           additionalProperties: true
         publicPortalUrl:
           type: string
+        itemContext:
+          $ref: "#/components/schemas/ItemContext"
+        tag:
+          $ref: "#/components/schemas/TagContext"
         size:
           type: string
           enum:

package/package.json

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