@proveanything/smartlinks 1.11.1 → 1.11.2

package/dist/mobile-admin/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Hardware/software capability tokens a mobile admin host may advertise.
+ * Passed to `AdminMobileHostContext.capabilities` and to
+ * `MobileAdminComponentManifest.capabilities`.
+ */
+export type AdminMobileCapability = 'nfc' | 'nfc-advanced' | 'rfid' | 'qr' | 'camera' | 'keyboard' | 'geolocation' | 'push';
+/**
+ * Canonical identifiers for mobile admin host environments.
+ * Use for display / diagnostics only — feature-detect at runtime via
+ * `AdminMobileHostContext.capabilities` and `'method' in host.actions`.
+ */
+export type AdminMobileHostId = 'custom-android' | 'capacitor-ios' | 'capacitor-android' | 'pwa' | 'browser';
+/**
+ * Discriminated-union of all events the host may emit via
+ * `AdminMobileHostContext.events.subscribe`.
+ */
+export type AdminMobileEvent = {
+    type: 'nfc-tap';
+    uid: string;
+    ndef?: string;
+} | {
+    type: 'rfid-burst';
+    epcs: string[];
+} | {
+    type: 'qr-scan';
+    code: string;
+} | {
+    type: 'key-press';
+    keyCode: number;
+} | {
+    type: 'lifecycle';
+    phase: 'pause' | 'resume' | 'offline' | 'online';
+};
+/** Callback signature for `AdminMobileHostContext.events.subscribe`. */
+export type ScannerEventSubscriber = (event: AdminMobileEvent) => void;
+/**
+ * The `host` prop passed to every mobile admin container component.
+ *
+ * @example
+ *   function StockTakeContainer({ host }: { host: AdminMobileHostContext }) {
+ *     const SL = host.SL; // Always use this — never import the SDK directly
+ *     return <div>...</div>;
+ *   }
+ */
+export interface AdminMobileHostContext {
+    /** SmartLinks collection this session is scoped to. */
+    collectionId: string;
+    /** App owning this container. */
+    appId: string;
+    /**
+     * Currently authenticated admin user, or `null` when unauthenticated.
+     */
+    user: {
+        uid?: string;
+        email?: string;
+        displayName?: string;
+        isAdmin: boolean;
+    } | null;
+    /**
+     * Already-initialised SDK namespace. Containers MUST use this for all API
+     * calls — never `import * as SL from '@proveanything/smartlinks'` inside a
+     * container, as that would create a second SDK instance.
+     */
+    SL: typeof import('../index');
+    /** Capabilities advertised by this host instance. */
+    capabilities: AdminMobileCapability[];
+    /**
+     * Static hardware availability flags.
+     * These reflect physical capability, not runtime permission state.
+     */
+    hardware: {
+        nfc: boolean;
+        rfid: boolean;
+        qr: boolean;
+        camera: boolean;
+        keyboard: boolean;
+    };
+    /** Hardware event stream. */
+    events: {
+        /**
+         * Subscribe to hardware events. Returns an unsubscribe function.
+         * @param cb - Called for every incoming `AdminMobileEvent`.
+         * @returns Cleanup function — call inside `useEffect` return.
+         */
+        subscribe: (cb: ScannerEventSubscriber) => () => void;
+    };
+    /** Imperative hardware actions. */
+    actions: {
+        /**
+         * Open the QR scanner UI and resolve with the decoded string.
+         * Throws `HostCapabilityUnavailableError` if `'qr'` is not in `capabilities`.
+         * Throws `HostTimeoutError` if the user dismisses without scanning.
+         */
+        requestQrScan: () => Promise<string>;
+        /**
+         * Await the next NFC tap and resolve with uid + optional NDEF payload.
+         * @param timeoutMs - Milliseconds before `HostTimeoutError` is thrown (host default if omitted).
+         */
+        requestNfcTap: (timeoutMs?: number) => Promise<{
+            uid: string;
+            ndef?: string;
+        }>;
+        /**
+         * Open the camera shutter once and resolve with the captured `Blob`.
+         * Throws `HostCapabilityUnavailableError` if `'camera'` is not in `capabilities`.
+         */
+        requestCameraPhoto: () => Promise<Blob>;
+        /**
+         * Trigger the native share sheet.
+         * Falls back to clipboard write on hosts that do not implement the Web Share API.
+         */
+        share: (payload: {
+            title: string;
+            url: string;
+            text?: string;
+        }) => Promise<void>;
+        /** Clipboard access. */
+        clipboard: {
+            read: () => Promise<string>;
+            write: (text: string) => Promise<void>;
+        };
+    };
+    /**
+     * Light-touch UI conveniences provided by the host shell.
+     * All methods are optional niceties — containers MUST degrade gracefully
+     * when absent (e.g. in Storybook or unit tests). Guard every call:
+     *
+     * @example
+     *   host.ui.toast?.({ title: 'Saved' });
+     */
+    ui: {
+        /** Show a transient status toast. Optional — see interface note. */
+        toast?: (opts: {
+            title: string;
+            description?: string;
+            variant?: 'default' | 'destructive';
+        }) => void;
+        /** Trigger a haptic pulse. Optional — see interface note. */
+        haptic?: (style?: 'light' | 'success' | 'error') => void;
+        setHeaderTitle: (title: string | null) => void;
+        navigateBack: () => void;
+    };
+    /** Network connectivity helpers. */
+    network: {
+        /** Returns whether the device currently has network access. */
+        isOnline: () => boolean;
+    };
+    /** Device information. */
+    device: {
+        /** Resolves with basic device model/platform metadata. */
+        info: () => Promise<{
+            model: string;
+            platform: string;
+        }>;
+    };
+    /**
+     * Host ABI version — informational only.
+     * DO NOT branch on this value. Feature-detect at runtime instead:
+     * @example
+     *   if ('requestNfcTap' in host.actions) { ... }
+     */
+    _version: number;
+}
+/** Manifest metadata for a single mobile admin container component. */
+export interface MobileAdminComponentManifest {
+    /** Component export name (matches the export in the bundle). */
+    name: string;
+    /** Human-readable description shown in the host launcher UI. */
+    description: string;
+    /**
+     * Hardware capabilities this component requires.
+     * The host will hide or disable the component when a required capability
+     * is absent from `AdminMobileHostContext.capabilities`.
+     */
+    capabilities?: AdminMobileCapability[];
+    /**
+     * When `true`, the component handles its own offline state and may be
+     * launched without network connectivity.
+     * @default false
+     */
+    offline?: boolean;
+}
+/**
+ * Shape of the `mobileAdmin` key inside `app.manifest.json`.
+ * Describes the bundle files and the components it exports.
+ */
+export interface MobileAdminBundleManifest {
+    files: {
+        js: {
+            /** UMD bundle path (relative to dist root). Used by the custom-android host. */
+            umd: string;
+            /** ESM bundle path (relative to dist root). Used by Capacitor/PWA hosts. */
+            esm: string;
+        };
+        /** CSS bundle path, or `null` if the component ships no styles. */
+        css: string | null;
+    };
+    components: MobileAdminComponentManifest[];
+}

package/dist/mobile-admin/types.js

@@ -0,0 +1 @@
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.1  |  Generated: 2026-04-30T12:17:30.051Z
+Version: 1.11.2  |  Generated: 2026-04-30T13:11:24.914Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/app-manifest.md

@@ -117,14 +117,18 @@ The manifest is loaded automatically by the platform for every collection page.
 
   "records": {
     "nutrition": {
-      "scopes": ["product", "facet", "batch"],
-      "defaultScope": "facet",
-      "label": "Nutrition info"
+      "label": "Nutrition info",
+      "cardinality": "singleton",
+      "allowFacetRules": true,
+      "scopes": ["collection", "rule", "product", "facet", "batch"],
+      "defaultScope": "product"
     },
     "cooking_steps": {
-      "scopes": ["product", "facet"],
-      "defaultScope": "product",
-      "label": "Cooking steps"
+      "label": "Cooking steps",
+      "cardinality": "singleton",
+      "allowFacetRules": false,
+      "scopes": ["collection", "product"],
+      "defaultScope": "product"
     }
   }
 }
@@ -268,25 +272,29 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 
 Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
 
-The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` read this block to render the right scope tabs, rule editor, and cardinality-appropriate right pane.
 
 ```json
 "records": {
   "<recordType>": {
-    "scopes": ["product", "facet", "batch"],
-    "defaultScope": "facet",
-    "label": "Human-readable label"
+    "label": "Human-readable label",
+    "cardinality": "singleton",
+    "allowFacetRules": false,
+    "scopes": ["collection", "product", "variant", "batch", "facet"],
+    "defaultScope": "product"
   }
 }
 ```
 
-| Field          | Type     | Required | Description |
-|----------------|----------|----------|-------------|
-| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
-| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
-| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+| Field             | Type     | Default | Description |
+|-------------------|----------|---------|-------------|
+| `label`           | string   | — | Human-readable label for the record type, used in headings and tabs. |
+| `cardinality`     | string   | `'singleton'` | `'singleton'` — one record wins per scope (e.g. ingredients, nutrition). `'collection'` — every matching record is returned in resolution order (e.g. FAQs, recipes). Drives which hook to use on the public side (`useResolvedRecord` vs `useCollectedRecords`) and how the shell lays out the right pane. |
+| `allowFacetRules` | boolean  | `false` | When `true`, the shell renders a **Rule** scope tab and embeds `<FacetRuleEditor>`. Add `'rule'` to `scopes` when setting this. |
+| `scopes`          | string[] | — | Allowed scope kinds in resolution order. Valid values: `"collection"`, `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"rule"`. `'rule'` is a synthetic scope holding `facetRule`-targeted records. `'collection'` replaces the legacy empty-ref catch-all — **there is no `'global'` scope**. |
+| `defaultScope`    | string   | — | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
 
-An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [records-admin-pattern.md](records-admin-pattern.md) for the full admin + public pattern.
 
 #### `executor`
 

package/docs/app-objects.md

@@ -495,7 +495,7 @@ The `ref` field is derived automatically from anchor fields when omitted:
 ```
 productId: 'prod_abc'                               → ref: 'product:prod_abc'
 productId: 'prod_abc', variantId: 'var_x'          → ref: 'product:prod_abc/variant:var_x'
-(no anchor fields)                                  → ref: '' (universal)
+(no anchor fields)                                  → ref: '' (collection-level catch-all)
 facetRule: { ... }                                  → ref: 'rule:<ulid>'
 ```
 
@@ -513,6 +513,20 @@ When multiple scoped records match a context, they are ordered by `specificity`.
 | Per `anyOf` value | +1 |
 | No anchors / no rule | 0 |
 
+### Resolution order
+
+When the public side of a records-based app needs "the data that applies to this product context", the platform walks a canonical chain from most-specific to least-specific:
+
+```
+proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →  collection
+```
+
+- `rule(*)` — `facetRule`-targeted records are scored by **specificity** (number of clauses + number of constrained values). The most specific rule wins at its tier.
+- `facet(*)` — legacy single-facet anchors, walked alphabetically. Prefer `facetRule` for new work.
+- `collection` — the top of the chain and the catch-all for any record with no anchor fields. **There is no `'global'` tier above collection.**
+
+For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [records-admin-pattern.md §2](records-admin-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
+
 ### Singleton Cardinality
 
 By default, `create` always inserts a new row — calling it twice produces two records with identical anchor fields. **Singleton cardinality** changes that: pass `singletonPer` on creation and the server will **upsert** instead, ensuring at most one record of a given `recordType` exists per scope boundary.
@@ -592,12 +606,11 @@ for (const entry of data) {
     case 'product':    /* "Inherited from product" */ break;
     case 'facet':      /* "Tier-specific" */          break;
     case 'collection': /* "Collection default" */     break;
-    case 'universal':  /* "Default" */                break;
   }
 }
 ```
 
-Precedence follows: `rule > proof > batch > variant > product > facet > collection > universal`.
+Precedence follows: `proof > batch > variant > product > rule > facet > collection`. There is no scope above `collection` — a record with no anchor fields is a collection-level catch-all.
 
 #### React — `useResolvedRecord`
 
@@ -806,7 +819,7 @@ Examples:
 | `productId: 'prod_abc', variantId: 'var_500ml'` | `product:prod_abc/variant:var_500ml` |
 | `batchId: 'batch_q1'` | `batch:batch_q1` |
 | `facetRule: { ... }` | `rule:<ulid>` |
-| *(no anchor fields)* | `''` (universal) |
+| *(no anchor fields)* | `''` (collection-level catch-all) |
 
 `parseRef` / `buildRef` in `data/refs.ts` should be used for **display and URL round-tripping only**, never as upsert keys. For ETL use cases, set an explicit `ref` using a stable external key (see [External ID / ETL Workflow](#external-id--etl-workflow)).
 

package/docs/mobile-admin-container.md

@@ -58,6 +58,8 @@ Your container **never** detects the host directly. It receives a `host` prop fr
 
 Every container mounted by the SmartLinks Mobile launcher receives a single `host` prop — `AdminMobileHostContext`. Do not reach for `window.SmartlinksScanner` or `window.Capacitor` directly; both are wrapped here.
 
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed.
+
 ```typescript
 interface AdminMobileHostContext {
   // Identity
@@ -460,7 +462,7 @@ vite build --config vite.config.mobile-admin.ts
 ```typescript
 // src/mobile-admin/WarehousePickContainer.tsx
 import { useEffect, useState } from 'react'
-import type { AdminMobileHostContext } from '@/lib/admin-mobile-host-context'
+import type { AdminMobileHostContext } from '@proveanything/smartlinks'
 
 interface Props {
   host: AdminMobileHostContext