@proveanything/smartlinks 1.6.7 → 1.7.0

package/dist/types/appManifest.d.ts

@@ -55,6 +55,129 @@ export interface AppContainerComponent {
         optional?: string[];
     };
 }
+/**
+ * A single navigable state exposed by a SmartLinks app.
+ * Used in both `app.manifest.json` (static routes) and `appConfig.linkable` (dynamic content entries).
+ *
+ * @example
+ *   // In app.manifest.json — static routes, declared at build time
+ *   { "title": "Gallery", "path": "/gallery" }
+ *   { "title": "Advanced Settings", "path": "/settings", "params": { "tab": "advanced" } }
+ *
+ *   // In appConfig.linkable — dynamic content, synced at runtime
+ *   { "title": "About Us", "params": { "pageId": "about-us" } }
+ */
+export interface DeepLinkEntry {
+    /** Human-readable label shown in menus and offered to AI agents */
+    title: string;
+    /**
+     * Hash route path within the app (optional).
+     * Defaults to "/" if omitted.
+     * @example "/gallery"
+     */
+    path?: string;
+    /**
+     * App-specific query params appended to the hash route URL.
+     * Do NOT include platform context params (collectionId, appId, productId, etc.) —
+     * those are injected by the platform automatically.
+     */
+    params?: Record<string, string>;
+}
+/**
+ * Context object passed to every executor factory function.
+ */
+export interface ExecutorContext {
+    collectionId: string;
+    appId: string;
+    /** Pre-initialised SmartLinks SDK — passed in to avoid duplicate instances */
+    SL: any;
+}
+/**
+ * Input passed to an executor's `getSEO()` function.
+ * The server pre-fetches collection/product/proof and passes them in;
+ * avoid making extra SL calls inside getSEO() to stay within the 200ms budget.
+ */
+export interface SEOInput {
+    collectionId: string;
+    appId: string;
+    productId?: string;
+    proofId?: string;
+    SL: any;
+    /** Pre-fetched collection object */
+    collection?: Record<string, any>;
+    /** Pre-fetched product object */
+    product?: Record<string, any>;
+    /** Pre-fetched proof object */
+    proof?: Record<string, any>;
+}
+/**
+ * Return value from an executor's `getSEO()` function.
+ * Singular fields (title, description, ogImage) use highest-priority-wins merging across apps.
+ * Additive fields (jsonLd, contentSummary, topics) are merged from all apps on the page.
+ */
+export interface SEOResult {
+    /** Page title — singular, highest `meta.seo.priority` wins */
+    title?: string;
+    /** Meta description — singular */
+    description?: string;
+    /** Open Graph image URL — singular */
+    ogImage?: string;
+    /** JSON-LD structured data — additive, concatenated from all apps */
+    jsonLd?: Record<string, any> | Record<string, any>[];
+    /** Plain text summary for AI crawlers — additive, concatenated */
+    contentSummary?: string;
+    /** Topic tags — additive, merged and deduplicated */
+    topics?: string[];
+}
+/** A single section returned by an executor's `getLLMContent()` function */
+export interface LLMContentSection {
+    /** Section heading displayed in the rendered HTML and read by AI crawlers */
+    heading: string;
+    /** Markdown content */
+    content: string;
+    /** Sort order — lower numbers appear first (default: 100) */
+    order?: number;
+}
+/**
+ * Input passed to an executor's `getLLMContent()` function.
+ * Similar to SEOInput but includes `pageSlug` for page-aware content.
+ * Timeout is 500ms (longer than SEO — LLM content may fetch app config).
+ */
+export interface LLMContentInput {
+    collectionId: string;
+    appId: string;
+    productId?: string;
+    proofId?: string;
+    SL: any;
+    collection?: Record<string, any>;
+    product?: Record<string, any>;
+    proof?: Record<string, any>;
+    /** Which page slug is being rendered */
+    pageSlug?: string;
+}
+/** Return value from an executor's `getLLMContent()` function */
+export interface LLMContentResult {
+    sections: LLMContentSection[];
+}
+/**
+ * The `executor` block in `app.manifest.json`.
+ * Declares the executor bundle and its exported capabilities.
+ */
+export interface AppManifestExecutor {
+    files: AppManifestFiles;
+    /** Name of the factory function that creates a configured executor instance */
+    factory?: string;
+    /** All named exports from the bundle */
+    exports?: string[];
+    /** Human-readable description for AI orchestrators and admin UIs */
+    description?: string;
+    /** LLM content contract — declares the getLLMContent function and its timeout */
+    llmContent?: {
+        function: string;
+        timeout?: number;
+        responseShape?: Record<string, any>;
+    };
+}
 /**
  * Shape of `app.admin.json` -- the separate admin configuration file pointed to
  * by `AppManifest.admin`. Fetch this file yourself when you need setup / import /
@@ -149,6 +272,21 @@ export interface AppManifest {
         version: string;
         platformRevision?: string;
         appId: string;
+        /**
+         * SEO configuration for this app.
+         * `priority` controls which app's singular fields (title, description, ogImage) win
+         * when multiple apps appear on the same page. Default is 0; higher wins.
+         */
+        seo?: {
+            strategy?: 'executor' | string;
+            priority?: number;
+            contract?: {
+                function: string;
+                input?: string[];
+                timeout?: number;
+                responseShape?: Record<string, string>;
+            };
+        };
     };
     /**
      * Relative path to the admin configuration file (e.g. `"app.admin.json"`).
@@ -167,6 +305,20 @@ export interface AppManifest {
         files: AppManifestFiles;
         components: AppContainerComponent[];
     };
+    /**
+     * Static deep-linkable states built into this app.
+     * These are fixed routes that exist regardless of content — declared once at build time.
+     * Dynamic content entries (e.g. CMS pages) are stored separately in `appConfig.linkable`.
+     * Consumers should merge both sources to get the full set of navigable states.
+     * @see DeepLinkEntry
+     */
+    linkable?: DeepLinkEntry[];
+    /**
+     * Executor bundle declaration. Present when the app ships a programmatic executor
+     * for AI-driven configuration, server-side SEO, and LLM content generation.
+     * @see AppManifestExecutor
+     */
+    executor?: AppManifestExecutor;
     [key: string]: any;
 }
 /**

package/dist/types/attestation.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Legacy Firestore-backed attestation response.
+ * Use {@link Attestation} from `attestations.ts` for new integrations.
+ */
 export interface AttestationResponse {
     /** Attestation id */
     id: string;
@@ -12,6 +16,10 @@ export interface AttestationResponse {
     /** Associated proof reference/data */
     proof: Record<string, any>;
 }
+/**
+ * @deprecated Legacy Firestore attestation create request.
+ * Use {@link CreateAttestationInput} from `attestations.ts` for new integrations.
+ */
 export interface AttestationCreateRequest {
     /** Public attestation payload */
     public: Record<string, any>;
@@ -20,6 +28,10 @@ export interface AttestationCreateRequest {
     /** Proof linkage or payload */
     proof: Record<string, any>;
 }
+/**
+ * @deprecated The new attestation system is append-only; updates are not supported.
+ * Append a corrective record via {@link CreateAttestationInput} instead.
+ */
 export interface AttestationUpdateRequest {
     /** Update operation/type */
     type?: string;

package/dist/types/attestations.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Attestations API Types — Postgres-backed (v2)
+ *
+ * These types support the new append-only, tamper-evident attestation system
+ * which is polymorphic over subject types (container, proof, product, tag, etc.),
+ * exposes three data-visibility zones, and maintains a SHA-256 hash chain for
+ * cryptographic integrity verification.
+ *
+ * @see docs/attestations.md
+ */
+/** Types of entities that can be the subject of an attestation. */
+export type AttestationSubjectType = 'container' | 'proof' | 'product' | 'tag' | 'serial' | 'order_item' | string;
+/**
+ * Per-record visibility.  Set once at write time; never changed.
+ * - `'public'`  — visible to any caller
+ * - `'owner'`   — visible when the caller is the subject owner (Firebase ID token required)
+ * - `'admin'`   — visible to admin callers only
+ */
+export type AttestationVisibility = 'public' | 'owner' | 'admin';
+/**
+ * Resolved audience tier returned by public endpoints.
+ * Tells the client which data zones are populated in the response.
+ */
+export type AttestationAudience = 'public' | 'owner' | 'admin';
+/** Granularity used by the time-series summary endpoints. */
+export type AttestationGroupBy = 'hour' | 'day' | 'week' | 'month';
+/**
+ * A single Postgres-backed attestation record.
+ *
+ * Records are **append-only** — they must never be updated or deleted.
+ * The `contentHash` / `prevHash` pair forms a tamper-evident chain keyed on
+ * `(subjectType, subjectId, attestationType)`.  Use `/verify` to confirm
+ * integrity of an entire chain.
+ */
+export interface Attestation {
+    /** UUID primary key */
+    id: string;
+    orgId: string;
+    collectionId: string;
+    /** Kind of entity this attestation describes */
+    subjectType: AttestationSubjectType;
+    /** UUID or identifier of the subject */
+    subjectId: string;
+    /** Domain-specific label, e.g. `'temperature'`, `'abv'`, `'angel_share'` */
+    attestationType: string;
+    /** ISO 8601 — the real-world time when the recorded fact was true */
+    recordedAt: string;
+    /** Per-record visibility; governs which audience tiers can read this record */
+    visibility: AttestationVisibility;
+    /** Public data zone — visible at all audience tiers */
+    value?: Record<string, any>;
+    /** Owner-tier data zone — stripped unless `audience >= 'owner'` */
+    ownerData?: Record<string, any>;
+    /** Admin-tier data zone — stripped unless `audience === 'admin'` */
+    adminData?: Record<string, any>;
+    /** Measurement unit, e.g. `'°C'`, `'%rh'`, `'L'`, `'ABV%'` */
+    unit?: string;
+    /** Source system or sensor identifier */
+    source?: string;
+    /** User ID or service account that recorded the fact */
+    authorId?: string;
+    /** Arbitrary extra metadata */
+    metadata?: Record<string, any>;
+    /** SHA-256 digest of this record (includes `prevHash`) */
+    contentHash: string;
+    /** `contentHash` of the preceding record in this chain, if any */
+    prevHash?: string;
+    /** ISO 8601 — database insertion timestamp */
+    createdAt: string;
+}
+/**
+ * Returned by `/latest` — one entry per `attestationType`, containing the
+ * single most-recent record for that type.
+ */
+export interface LatestAttestation {
+    attestationType: string;
+    latest: Attestation;
+}
+/**
+ * One time-bucket returned by `/summary`.
+ * `period` format depends on `groupBy`:
+ * - `'hour'`  → `"2025-04-15T14:00:00Z"`
+ * - `'day'`   → `"2025-04-15"`
+ * - `'week'`  → `"2025-W16"`
+ * - `'month'` → `"2025-04"`
+ */
+export interface AttestationSummaryBucket {
+    period: string;
+    count: number;
+    /** Aggregated value fields for this bucket (present when `valueField` is requested) */
+    values?: Record<string, any>;
+}
+/**
+ * Returned by `/verify` — result of re-computing and validating the full
+ * hash chain for a `(subjectType, subjectId, attestationType)` tuple.
+ */
+export interface ChainVerifyResult {
+    valid: boolean;
+    checkedCount: number;
+    /** ID of the first broken link; present only when `valid` is `false` */
+    failedAt?: string;
+    message: string;
+}
+/**
+ * Request body for creating a single attestation (admin endpoint).
+ *
+ * Required: `subjectType`, `subjectId`, `attestationType`.
+ */
+export interface CreateAttestationInput {
+    /** Required — type of entity this attestation describes */
+    subjectType: AttestationSubjectType;
+    /** Required — UUID or identifier of the subject */
+    subjectId: string;
+    /** Required — domain label for this measurement/fact */
+    attestationType: string;
+    /** ISO 8601; defaults to `now()` when omitted */
+    recordedAt?: string;
+    /** Default `'public'` */
+    visibility?: AttestationVisibility;
+    /** Public data zone */
+    value?: Record<string, any>;
+    /** Owner-tier data zone */
+    ownerData?: Record<string, any>;
+    /** Admin-tier data zone */
+    adminData?: Record<string, any>;
+    unit?: string;
+    source?: string;
+    authorId?: string;
+    metadata?: Record<string, any>;
+}
+export interface ListAttestationsResponse {
+    attestations: Attestation[];
+}
+export interface PublicListAttestationsResponse {
+    attestations: Attestation[];
+    /** Resolved audience tier; governs which data zones are populated */
+    audience: AttestationAudience;
+}
+export interface AttestationSummaryResponse {
+    summary: AttestationSummaryBucket[];
+}
+export interface PublicAttestationSummaryResponse {
+    summary: AttestationSummaryBucket[];
+    audience: 'public';
+}
+export interface AttestationLatestResponse {
+    latest: LatestAttestation[];
+}
+export interface PublicAttestationLatestResponse {
+    latest: LatestAttestation[];
+    audience: AttestationAudience;
+}
+export interface AttestationTreeSummaryResponse {
+    summary: AttestationSummaryBucket[];
+    /** Number of distinct subjects aggregated in this response */
+    subjectCount: number;
+}
+export interface PublicAttestationTreeSummaryResponse {
+    summary: AttestationSummaryBucket[];
+    audience: 'public';
+    subjectCount: number;
+}
+export interface AttestationTreeLatestResponse {
+    latest: LatestAttestation[];
+    subjectCount: number;
+}
+export interface PublicAttestationTreeLatestResponse {
+    latest: LatestAttestation[];
+    audience: 'public';
+    subjectCount: number;
+}
+export interface ListAttestationsParams {
+    /** Required */
+    subjectType: AttestationSubjectType;
+    /** Required */
+    subjectId: string;
+    attestationType?: string;
+    /** ISO 8601 lower bound (inclusive) */
+    recordedAfter?: string;
+    /** ISO 8601 upper bound (inclusive) */
+    recordedBefore?: string;
+    /** Default 100 */
+    limit?: number;
+    /** Default 0 */
+    offset?: number;
+}
+export interface AttestationSummaryParams {
+    /** Required */
+    subjectType: AttestationSubjectType;
+    /** Required */
+    subjectId: string;
+    /** Required */
+    attestationType: string;
+    /** Dot-path inside `value` to aggregate, e.g. `'celsius'` */
+    valueField?: string;
+    /** Default `'day'` */
+    groupBy?: AttestationGroupBy;
+    recordedAfter?: string;
+    recordedBefore?: string;
+    /** Max number of buckets; default 200 */
+    limit?: number;
+}
+export interface AttestationLatestParams {
+    /** Required */
+    subjectType: AttestationSubjectType;
+    /** Required */
+    subjectId: string;
+}
+export interface AttestationVerifyParams {
+    /** Required */
+    subjectType: AttestationSubjectType;
+    /** Required */
+    subjectId: string;
+    /** Required */
+    attestationType: string;
+}
+export interface AttestationTreeSummaryParams {
+    /** Required — root container UUID */
+    subjectId: string;
+    /** Required */
+    attestationType: string;
+    valueField?: string;
+    /** Default `'day'` */
+    groupBy?: AttestationGroupBy;
+    recordedAfter?: string;
+    recordedBefore?: string;
+    /** Max number of buckets; default 200 */
+    limit?: number;
+    /** Include container items in BFS traversal; default `true` */
+    includeItems?: boolean;
+}
+export interface AttestationTreeLatestParams {
+    /** Required — root container UUID */
+    subjectId: string;
+    /** Include container items in BFS traversal; default `true` */
+    includeItems?: boolean;
+}

package/dist/types/attestations.js

@@ -0,0 +1,11 @@
+/**
+ * Attestations API Types — Postgres-backed (v2)
+ *
+ * These types support the new append-only, tamper-evident attestation system
+ * which is polymorphic over subject types (container, proof, product, tag, etc.),
+ * exposes three data-visibility zones, and maintains a SHA-256 hash chain for
+ * cryptographic integrity verification.
+ *
+ * @see docs/attestations.md
+ */
+export {};

package/dist/types/containers.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Container Tracking Types
+ *
+ * Physical or logical grouping entities (pallets, casks, fridges, shipping
+ * containers, warehouses, etc.) with support for hierarchical nesting and
+ * item membership tracking.
+ *
+ * @see docs/container-tracking.md
+ */
+/** Lifecycle status of a container. Custom strings are permitted. */
+export type ContainerStatus = 'active' | 'archived' | string;
+/**
+ * Types of items that can be placed inside a container.
+ * A `container` item type allows containers to nest inside other containers.
+ */
+export type ContainerItemType = 'tag' | 'proof' | 'serial' | 'order_item' | 'container';
+/**
+ * A physical or logical container entity.
+ *
+ * Containers can nest arbitrarily via `parentContainerId`.  The `children`
+ * field is only populated when `?tree=true` is included in the request.
+ * The `items` field is only populated when `?includeContents=true` is set.
+ */
+export interface Container {
+    /** UUID primary key */
+    id: string;
+    orgId: string;
+    collectionId: string;
+    /**
+     * Domain label describing what kind of container this is.
+     * Examples: `'pallet'`, `'fridge'`, `'cask'`, `'warehouse'`, `'shipping_container'`
+     */
+    containerType: string;
+    /** Human-readable identifier, e.g. a barcode, reference number, or QR code value */
+    ref?: string;
+    name?: string;
+    description?: string;
+    /** Default `'active'` */
+    status: ContainerStatus;
+    /** Arbitrary key/value store for application-specific data */
+    metadata?: Record<string, any>;
+    /** UUID of the parent container; `undefined` / `null` for top-level containers */
+    parentContainerId?: string;
+    /** Recursively nested children — populated only when `?tree=true` */
+    children?: Container[];
+    /** Current (or historical) items — populated only when `?includeContents=true` */
+    items?: ContainerItem[];
+    /** ISO 8601 */
+    createdAt: string;
+    /** ISO 8601 */
+    updatedAt: string;
+    /** ISO 8601 soft-delete timestamp; present only for deleted containers */
+    deletedAt?: string;
+}
+/**
+ * A membership record linking a single item to a container.
+ *
+ * `removedAt` being `null` / `undefined` means the item is currently inside
+ * the container.  When non-null the item has been removed; the record is
+ * preserved in the history log.
+ */
+export interface ContainerItem {
+    id: string;
+    orgId: string;
+    containerId: string;
+    collectionId?: string;
+    itemType: ContainerItemType;
+    /** UUID or physical identifier of the item (tag ID, proof ID, serial, etc.) */
+    itemId: string;
+    /** Convenience denormalisation — product UUID if applicable */
+    productId?: string;
+    /** Convenience denormalisation — proof / serial UUID if applicable */
+    proofId?: string;
+    /** ISO 8601 — when the item was placed into the container */
+    addedAt: string;
+    /** ISO 8601 — when the item was removed; `null` / `undefined` = still inside */
+    removedAt?: string;
+    /** Arbitrary extra metadata */
+    metadata?: Record<string, any>;
+}
+/** Request body for `POST /containers` — creates a new container. */
+export interface CreateContainerInput {
+    /** Required — domain label for this container */
+    containerType: string;
+    /** Human-readable reference / barcode */
+    ref?: string;
+    name?: string;
+    description?: string;
+    /** Default `'active'` */
+    status?: ContainerStatus;
+    metadata?: Record<string, any>;
+    /** UUID of the parent container; omit to create a top-level container */
+    parentContainerId?: string;
+}
+/**
+ * Request body for `PATCH /containers/:id`.
+ * Only provided fields are updated; all are optional.
+ */
+export interface UpdateContainerInput {
+    containerType?: string;
+    ref?: string;
+    name?: string;
+    description?: string;
+    status?: ContainerStatus;
+    metadata?: Record<string, any>;
+    /** Pass `null` to promote the container to top-level. */
+    parentContainerId?: string | null;
+}
+/** Request body for `POST /containers/:id/items` — adds items to a container. */
+export interface AddContainerItemsInput {
+    items: Array<{
+        /** Required */
+        itemType: ContainerItemType;
+        /** Required — UUID or physical identifier of the item */
+        itemId: string;
+        productId?: string;
+        proofId?: string;
+        metadata?: Record<string, any>;
+    }>;
+}
+/** Request body for `DELETE /containers/:id/items` — soft-removes items. */
+export interface RemoveContainerItemsInput {
+    /** `ContainerItem` UUIDs to mark as removed */
+    ids: string[];
+}
+export interface ListContainersResponse {
+    containers: Container[];
+    limit: number;
+    offset: number;
+}
+export interface PublicListContainersResponse {
+    containers: Container[];
+}
+export interface FindContainersForItemResponse {
+    containers: Container[];
+}
+export interface ContainerItemsResponse {
+    items: ContainerItem[];
+    limit: number;
+    offset: number;
+}
+export interface AddContainerItemsResponse {
+    items: ContainerItem[];
+}
+export interface RemoveContainerItemsResponse {
+    success: true;
+    removedCount: number;
+}
+export interface ListContainersParams {
+    /** Filter by container type label */
+    containerType?: string;
+    /** Filter by status */
+    status?: ContainerStatus;
+    /** Filter by human-readable reference */
+    ref?: string;
+    /** Filter by parent container UUID */
+    parentContainerId?: string;
+    /** When `true`, return only top-level containers (no `parentContainerId`) */
+    topLevel?: boolean;
+    /** Default 100 */
+    limit?: number;
+    /** Default 0 */
+    offset?: number;
+}
+export interface GetContainerParams {
+    /** When `true`, recursively embed child containers up to `treeDepth` levels */
+    tree?: boolean;
+    /** Max nesting depth for the tree; default unlimited */
+    treeDepth?: number;
+    /** When `true`, embed the current `items` array */
+    includeContents?: boolean;
+}
+export interface ListContainerItemsParams {
+    /** When `true`, include removed items (full membership log); default `false` */
+    history?: boolean;
+    /** Default 100 */
+    limit?: number;
+    /** Default 0 */
+    offset?: number;
+}
+export interface FindContainersForItemParams {
+    /** Required */
+    itemType: ContainerItemType;
+    /** Required */
+    itemId: string;
+}

package/dist/types/containers.js

@@ -0,0 +1,10 @@
+/**
+ * Container Tracking Types
+ *
+ * Physical or logical grouping entities (pallets, casks, fridges, shipping
+ * containers, warehouses, etc.) with support for hierarchical nesting and
+ * item membership tracking.
+ *
+ * @see docs/container-tracking.md
+ */
+export {};