@proveanything/smartlinks 1.11.2 → 1.11.4

package/dist/docs/API_SUMMARY.md

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

package/dist/docs/mobile-admin-container.md

@@ -58,7 +58,7 @@ 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.
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `ActionableCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `AdminMobileEventCallback`, `AdminMobileEventSubscriber`, `AdminMobileComponentManifest`, and `AdminMobileBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed. `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` still export as deprecated aliases.
 
 ```typescript
 interface AdminMobileHostContext {
@@ -82,8 +82,8 @@ interface AdminMobileHostContext {
     keyboard: boolean
   }
 
-  // Unified hardware event stream
-  events: { subscribe: ScannerEventSubscriber }
+  // Unified hardware event stream — callback type: AdminMobileEventCallback
+  events: { subscribe: (cb: AdminMobileEventCallback) => () => void }
 
   // Promise-based hardware actions — reject with a structured error when unavailable
   actions: {
@@ -97,12 +97,12 @@ interface AdminMobileHostContext {
     }
   }
 
-  // Host-provided UI helpers
+  // Host-provided UI helpers — all optional, see §3 note
   ui: {
-    toast: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
-    haptic: (style?: 'light' | 'success' | 'error') => void
-    setHeaderTitle: (title: string | null) => void
-    navigateBack: () => void
+    toast?: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
+    haptic?: (style?: 'light' | 'success' | 'error') => void
+    setHeaderTitle?: (title: string | null) => void
+    navigateBack?: () => void
   }
 
   // Network & device info
@@ -143,9 +143,10 @@ if (host.hardware.nfc) {
 
 ### `host.ui` — native helpers vs. your own components
 
-`host.ui.setHeaderTitle()` and `host.ui.navigateBack()` are **host-only** — there is no in-container equivalent. Call them via `host.ui` or omit them.
+All four `host.ui` methods are **optional by design**. A container may run in the Sidekick mobile shell, a standalone PWA or browser tab, Storybook, or a screenshot harness — none of those environments is guaranteed to have a native toast system, a managed header, or a back stack. Forcing every host implementer to provide them would exclude the web and desktop use-cases the rest of the contract explicitly supports. Always guard with `?.`:
 
-`host.ui.toast()` and `host.ui.haptic()` are **optional conveniences**. Use them when you want native system feedback. When rendering in Storybook, unit tests, or a plain browser tab, your own `<Toaster />` is a perfectly valid substitute — you do not need to stub the entire `host.ui` surface just to get toast notifications.
+- `host.ui.toast?.({...})` / `host.ui.haptic?.('success')` — optional native feedback. Fall back to your own `<Toaster />` when absent.
+- `host.ui.setHeaderTitle?.('Scanning…')` / `host.ui.navigateBack?.()` — host-shell integrations with no in-container equivalent. Silently no-op when the host doesn't implement them.
 
 **Stub pattern for testing and Storybook:**
 
@@ -222,12 +223,23 @@ The custom Kotlin shell and both Capacitor shells ship the same baseline plugin
 | `@capacitor/device` | `host.device.info()` |
 | `@capacitor/share` | `host.actions.share()` |
 | `@capacitor/clipboard` | `host.actions.clipboard.*` |
-| `@capacitor/preferences` | `host.storage.*` *(planned)* |
+| `@capacitor/preferences` | `host.storage.*` *(planned — see note below)* |
 | `@capacitor/app` | host-managed (back button, deep links) |
 | `@capacitor/status-bar` | host-managed |
 | `@capacitor/keyboard` | host-managed |
 | `@capacitor/toast` | wired into `host.ui.toast()` |
 
+> **`host.storage` — planned shape.** Once released, the surface will wrap `@capacitor/preferences` directly:
+> ```ts
+> host.storage: {
+>   get(key: string): Promise<string | null>
+>   set(key: string, value: string): Promise<void>
+>   remove(key: string): Promise<void>
+>   keys(): Promise<string[]>
+> }
+> ```
+> Until then: `localStorage` works on web hosts; use `@capacitor/preferences` directly (bundle it in) on native.
+
 ### Tier 2 — capability-gated (declare in manifest)
 
 | Plugin | Capability flag |
@@ -385,7 +397,9 @@ try {
 | `lifecycle: 'pause'` | App backgrounded | Pause readers to save battery |
 | `lifecycle: 'resume'` | App foregrounded | Resubscribe; refresh stale data |
 
-Use `host.events.subscribe` for all lifecycle events — it fires identically on every host.
+Use `host.events.subscribe` for all lifecycle events — all five host types (`custom-android`, `capacitor-ios`, `capacitor-android`, `pwa`, `browser`) are guaranteed to emit every `'pause'`/`'resume'`/`'offline'`/`'online'` phase. No `window.addEventListener('online')` fallback is needed.
+
+> **Planned** — `phase: 'mount' | 'unmount'` events are on the roadmap. These will fire when the container becomes visible / is removed from the host view stack, enabling deferred reader start-up without a `useEffect` dependency.
 
 ---
 
@@ -521,8 +535,8 @@ export const MOBILE_ADMIN_MANIFEST = {
 
 - **Always check `host.hardware.X` before calling `host.actions.X`** — never assume a capability is available.
 - **Always wrap action calls in try/catch** — handle `HostPermissionDeniedError`, `HostTimeoutError`, and `HostCapabilityUnavailableError`.
-- **Use `host.ui.setHeaderTitle` and `host.ui.navigateBack`** for header integration — these are host-only and have no in-container equivalent.
-- **`host.ui.toast` and `host.ui.haptic` are optional** — use them for native feedback, or fall back to your own `<Toaster />` when testing in isolation.
+- **All four `host.ui` methods are optional** (`toast`, `haptic`, `setHeaderTitle`, `navigateBack`) — guard every call with `?.`. See the `host.ui` section above.
+- **`host.ui.setHeaderTitle` and `host.ui.navigateBack`** integrate with the host shell and have no in-container equivalent; call with `?.`.
 - **Use `host.events.subscribe` for lifecycle events** — `'offline'`/`'online'`/`'pause'`/`'resume'` fire consistently on every host.
 - **Never call `initializeApi`, never use top-level SDK imports for API calls** — `host.SL` is already configured. `SL.method()` instead of `host.SL.method()` silently uses the wrong baseURL.
 - **Bundle Capacitor plugins in** (do not externalise) — so the component degrades gracefully on PWA/browser without crashing.

package/dist/index.d.ts

@@ -23,5 +23,7 @@ export type { Collection, CollectionResponse, CollectionCreateRequest, Collectio
 export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";
-export type { AdminMobileCapability, AdminMobileHostId, AdminMobileEvent, ScannerEventSubscriber, AdminMobileHostContext, MobileAdminComponentManifest, MobileAdminBundleManifest, } from './mobile-admin/types';
+export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
+AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest, MobileAdminComponentManifest, // @deprecated — use AdminMobileComponentManifest
+MobileAdminBundleManifest, } from './mobile-admin/types';
 export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';

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

@@ -5,6 +5,7 @@
  * All three classes call `Object.setPrototypeOf(this, new.target.prototype)` so
  * `instanceof` works correctly when transpiled to ES5.
  */
+import type { ActionableCapability, AdminMobileHostId } from './types';
 /**
  * Thrown when a container requests a hardware action that the current host
  * does not support (e.g. calling `requestNfcTap` on a `'pwa'` host).
@@ -20,10 +21,10 @@
  */
 export declare class HostCapabilityUnavailableError extends Error {
     /** The capability that was requested but is unavailable. */
-    capability: 'nfc' | 'rfid' | 'qr' | 'camera';
-    /** `AdminMobileHostId` string of the host that rejected the request. */
-    host: string;
-    constructor(capability: HostCapabilityUnavailableError['capability'], host: string);
+    capability: ActionableCapability;
+    /** The host on which the capability is unavailable. */
+    host: AdminMobileHostId;
+    constructor(capability: ActionableCapability, host: AdminMobileHostId);
 }
 /**
  * Thrown when the user denies a runtime permission request (e.g. camera or
@@ -40,8 +41,8 @@ export declare class HostCapabilityUnavailableError extends Error {
  */
 export declare class HostPermissionDeniedError extends Error {
     /** The capability for which permission was denied. */
-    capability: 'nfc' | 'rfid' | 'qr' | 'camera';
-    constructor(capability: HostPermissionDeniedError['capability']);
+    capability: ActionableCapability;
+    constructor(capability: ActionableCapability);
 }
 /**
  * Thrown when a time-bounded host action (NFC tap, QR scan) exceeds its
@@ -58,7 +59,7 @@ export declare class HostPermissionDeniedError extends Error {
  */
 export declare class HostTimeoutError extends Error {
     /** The capability that timed out. */
-    capability: 'nfc' | 'qr';
+    capability: Extract<ActionableCapability, 'nfc' | 'qr' | 'geolocation'>;
     /** The timeout threshold in milliseconds. */
     timeoutMs: number;
     constructor(capability: HostTimeoutError['capability'], timeoutMs: number);

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

@@ -1,9 +1,15 @@
 /**
  * Hardware/software capability tokens a mobile admin host may advertise.
  * Passed to `AdminMobileHostContext.capabilities` and to
- * `MobileAdminComponentManifest.capabilities`.
+ * `AdminMobileComponentManifest.capabilities`.
  */
 export type AdminMobileCapability = 'nfc' | 'nfc-advanced' | 'rfid' | 'qr' | 'camera' | 'keyboard' | 'geolocation' | 'push';
+/**
+ * Subset of `AdminMobileCapability` that can be the subject of a structured
+ * error. `'keyboard'` is excluded — it is a passive event source with no
+ * request method that can fail.
+ */
+export type ActionableCapability = Exclude<AdminMobileCapability, 'keyboard'>;
 /**
  * Canonical identifiers for mobile admin host environments.
  * Use for display / diagnostics only — feature-detect at runtime via
@@ -31,8 +37,19 @@ export type AdminMobileEvent = {
     type: 'lifecycle';
     phase: 'pause' | 'resume' | 'offline' | 'online';
 };
-/** Callback signature for `AdminMobileHostContext.events.subscribe`. */
-export type ScannerEventSubscriber = (event: AdminMobileEvent) => void;
+/** Callback invoked for every hardware event emitted by the host. */
+export type AdminMobileEventCallback = (event: AdminMobileEvent) => void;
+/**
+ * The full type of `AdminMobileHostContext.events.subscribe` —
+ * takes a callback and returns a cleanup function.
+ */
+export type AdminMobileEventSubscriber = (cb: AdminMobileEventCallback) => () => void;
+/**
+ * @deprecated Renamed to `AdminMobileEventCallback` in 1.12.
+ * Will be removed in a future minor release.
+ * @see AdminMobileEventCallback
+ */
+export type ScannerEventSubscriber = AdminMobileEventCallback;
 /**
  * The `host` prop passed to every mobile admin container component.
  *
@@ -82,7 +99,7 @@ export interface AdminMobileHostContext {
          * @param cb - Called for every incoming `AdminMobileEvent`.
          * @returns Cleanup function — call inside `useEffect` return.
          */
-        subscribe: (cb: ScannerEventSubscriber) => () => void;
+        subscribe: (cb: AdminMobileEventCallback) => () => void;
     };
     /** Imperative hardware actions. */
     actions: {
@@ -137,8 +154,16 @@ export interface AdminMobileHostContext {
         }) => void;
         /** Trigger a haptic pulse. Optional — see interface note. */
         haptic?: (style?: 'light' | 'success' | 'error') => void;
-        setHeaderTitle: (title: string | null) => void;
-        navigateBack: () => void;
+        /**
+         * Optional — host shell may not provide a managed header
+         * (browser tabs, Storybook, desktop views). Guard with `?.`.
+         */
+        setHeaderTitle?: (title: string | null) => void;
+        /**
+         * Optional — host shell may not have a native back stack
+         * (browser tabs, Storybook, desktop views). Guard with `?.`.
+         */
+        navigateBack?: () => void;
     };
     /** Network connectivity helpers. */
     network: {
@@ -162,7 +187,7 @@ export interface AdminMobileHostContext {
     _version: number;
 }
 /** Manifest metadata for a single mobile admin container component. */
-export interface MobileAdminComponentManifest {
+export interface AdminMobileComponentManifest {
     /** Component export name (matches the export in the bundle). */
     name: string;
     /** Human-readable description shown in the host launcher UI. */
@@ -184,7 +209,7 @@ export interface MobileAdminComponentManifest {
  * Shape of the `mobileAdmin` key inside `app.manifest.json`.
  * Describes the bundle files and the components it exports.
  */
-export interface MobileAdminBundleManifest {
+export interface AdminMobileBundleManifest {
     files: {
         js: {
             /** UMD bundle path (relative to dist root). Used by the custom-android host. */
@@ -195,5 +220,15 @@ export interface MobileAdminBundleManifest {
         /** CSS bundle path, or `null` if the component ships no styles. */
         css: string | null;
     };
-    components: MobileAdminComponentManifest[];
+    components: AdminMobileComponentManifest[];
 }
+/**
+ * @deprecated Renamed to `AdminMobileComponentManifest` in 1.12.
+ * @see AdminMobileComponentManifest
+ */
+export type MobileAdminComponentManifest = AdminMobileComponentManifest;
+/**
+ * @deprecated Renamed to `AdminMobileBundleManifest` in 1.12.
+ * @see AdminMobileBundleManifest
+ */
+export type MobileAdminBundleManifest = AdminMobileBundleManifest;

package/docs/API_SUMMARY.md

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

package/docs/mobile-admin-container.md

@@ -58,7 +58,7 @@ 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.
+> **SDK export** — `AdminMobileHostContext`, `AdminMobileCapability`, `ActionableCapability`, `AdminMobileHostId`, `AdminMobileEvent`, `AdminMobileEventCallback`, `AdminMobileEventSubscriber`, `AdminMobileComponentManifest`, and `AdminMobileBundleManifest` are all exported from `@proveanything/smartlinks`. Import via `import type { AdminMobileHostContext } from '@proveanything/smartlinks'` — no local mirror needed. `ScannerEventSubscriber`, `MobileAdminComponentManifest`, and `MobileAdminBundleManifest` still export as deprecated aliases.
 
 ```typescript
 interface AdminMobileHostContext {
@@ -82,8 +82,8 @@ interface AdminMobileHostContext {
     keyboard: boolean
   }
 
-  // Unified hardware event stream
-  events: { subscribe: ScannerEventSubscriber }
+  // Unified hardware event stream — callback type: AdminMobileEventCallback
+  events: { subscribe: (cb: AdminMobileEventCallback) => () => void }
 
   // Promise-based hardware actions — reject with a structured error when unavailable
   actions: {
@@ -97,12 +97,12 @@ interface AdminMobileHostContext {
     }
   }
 
-  // Host-provided UI helpers
+  // Host-provided UI helpers — all optional, see §3 note
   ui: {
-    toast: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
-    haptic: (style?: 'light' | 'success' | 'error') => void
-    setHeaderTitle: (title: string | null) => void
-    navigateBack: () => void
+    toast?: (opts: { title: string; description?: string; variant?: 'default' | 'destructive' }) => void
+    haptic?: (style?: 'light' | 'success' | 'error') => void
+    setHeaderTitle?: (title: string | null) => void
+    navigateBack?: () => void
   }
 
   // Network & device info
@@ -143,9 +143,10 @@ if (host.hardware.nfc) {
 
 ### `host.ui` — native helpers vs. your own components
 
-`host.ui.setHeaderTitle()` and `host.ui.navigateBack()` are **host-only** — there is no in-container equivalent. Call them via `host.ui` or omit them.
+All four `host.ui` methods are **optional by design**. A container may run in the Sidekick mobile shell, a standalone PWA or browser tab, Storybook, or a screenshot harness — none of those environments is guaranteed to have a native toast system, a managed header, or a back stack. Forcing every host implementer to provide them would exclude the web and desktop use-cases the rest of the contract explicitly supports. Always guard with `?.`:
 
-`host.ui.toast()` and `host.ui.haptic()` are **optional conveniences**. Use them when you want native system feedback. When rendering in Storybook, unit tests, or a plain browser tab, your own `<Toaster />` is a perfectly valid substitute — you do not need to stub the entire `host.ui` surface just to get toast notifications.
+- `host.ui.toast?.({...})` / `host.ui.haptic?.('success')` — optional native feedback. Fall back to your own `<Toaster />` when absent.
+- `host.ui.setHeaderTitle?.('Scanning…')` / `host.ui.navigateBack?.()` — host-shell integrations with no in-container equivalent. Silently no-op when the host doesn't implement them.
 
 **Stub pattern for testing and Storybook:**
 
@@ -222,12 +223,23 @@ The custom Kotlin shell and both Capacitor shells ship the same baseline plugin
 | `@capacitor/device` | `host.device.info()` |
 | `@capacitor/share` | `host.actions.share()` |
 | `@capacitor/clipboard` | `host.actions.clipboard.*` |
-| `@capacitor/preferences` | `host.storage.*` *(planned)* |
+| `@capacitor/preferences` | `host.storage.*` *(planned — see note below)* |
 | `@capacitor/app` | host-managed (back button, deep links) |
 | `@capacitor/status-bar` | host-managed |
 | `@capacitor/keyboard` | host-managed |
 | `@capacitor/toast` | wired into `host.ui.toast()` |
 
+> **`host.storage` — planned shape.** Once released, the surface will wrap `@capacitor/preferences` directly:
+> ```ts
+> host.storage: {
+>   get(key: string): Promise<string | null>
+>   set(key: string, value: string): Promise<void>
+>   remove(key: string): Promise<void>
+>   keys(): Promise<string[]>
+> }
+> ```
+> Until then: `localStorage` works on web hosts; use `@capacitor/preferences` directly (bundle it in) on native.
+
 ### Tier 2 — capability-gated (declare in manifest)
 
 | Plugin | Capability flag |
@@ -385,7 +397,9 @@ try {
 | `lifecycle: 'pause'` | App backgrounded | Pause readers to save battery |
 | `lifecycle: 'resume'` | App foregrounded | Resubscribe; refresh stale data |
 
-Use `host.events.subscribe` for all lifecycle events — it fires identically on every host.
+Use `host.events.subscribe` for all lifecycle events — all five host types (`custom-android`, `capacitor-ios`, `capacitor-android`, `pwa`, `browser`) are guaranteed to emit every `'pause'`/`'resume'`/`'offline'`/`'online'` phase. No `window.addEventListener('online')` fallback is needed.
+
+> **Planned** — `phase: 'mount' | 'unmount'` events are on the roadmap. These will fire when the container becomes visible / is removed from the host view stack, enabling deferred reader start-up without a `useEffect` dependency.
 
 ---
 
@@ -521,8 +535,8 @@ export const MOBILE_ADMIN_MANIFEST = {
 
 - **Always check `host.hardware.X` before calling `host.actions.X`** — never assume a capability is available.
 - **Always wrap action calls in try/catch** — handle `HostPermissionDeniedError`, `HostTimeoutError`, and `HostCapabilityUnavailableError`.
-- **Use `host.ui.setHeaderTitle` and `host.ui.navigateBack`** for header integration — these are host-only and have no in-container equivalent.
-- **`host.ui.toast` and `host.ui.haptic` are optional** — use them for native feedback, or fall back to your own `<Toaster />` when testing in isolation.
+- **All four `host.ui` methods are optional** (`toast`, `haptic`, `setHeaderTitle`, `navigateBack`) — guard every call with `?.`. See the `host.ui` section above.
+- **`host.ui.setHeaderTitle` and `host.ui.navigateBack`** integrate with the host shell and have no in-container equivalent; call with `?.`.
 - **Use `host.events.subscribe` for lifecycle events** — `'offline'`/`'online'`/`'pause'`/`'resume'` fire consistently on every host.
 - **Never call `initializeApi`, never use top-level SDK imports for API calls** — `host.SL` is already configured. `SL.method()` instead of `host.SL.method()` silently uses the wrong baseURL.
 - **Bundle Capacitor plugins in** (do not externalise) — so the component degrades gracefully on PWA/browser without crashing.

package/package.json

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