@proveanything/smartlinks 1.7.1 → 1.7.3

package/dist/api/tags.d.ts

@@ -1,139 +1,141 @@
-import { CreateTagRequest, CreateTagResponse, CreateTagsBatchRequest, CreateTagsBatchResponse, UpdateTagRequest, UpdateTagResponse, DeleteTagResponse, GetTagResponse, ListTagsRequest, ListTagsResponse, PublicGetTagRequest, PublicGetTagResponse, PublicBatchLookupRequest, PublicBatchLookupResponse, PublicBatchLookupQueryRequest, PublicBatchLookupQueryResponse, ReverseTagLookupParams, ReverseTagLookupResponse } from "../types/tags";
+import type { TagIndexEntry, CreateTagRequest, CreateTagResponse, BatchCreateTagRequest, BatchCreateResult, UpdateTagRequest, UpdateTagResponse, DeleteTagResponse, GetTagResponse, ListTagsRequest, ListTagsResponse, LookupTagsRequest, LookupTagsQueryRequest, TagLookupResponse, PublicGetTagResponse, ByRefRequest, ByRefResponse, ReverseTagLookupParams, ReverseTagLookupResponse } from "../types/tags";
 /**
  * Tag Management API
  *
- * Create mappings between physical tags (NFC tags, QR codes, etc.) and digital proofs.
- * Supports automatic serial number generation, batch operations, and public lookups.
+ * Manages mappings between physical tag identifiers (NFC UIDs, QR codes, barcodes,
+ * etc.) and products, proofs, or any polymorphic object in the platform.
+ *
+ * ### Two-tier architecture
+ * - **Per-org shard** (`tags` table) — full tag data; used for all collection-scoped
+ *   queries.
+ * - **Shared shard** (`tag_index` table) — `tagId → collectionId` routing only; used
+ *   when the collection is not yet known.
+ *
+ * 99% of callers will know the collection and should use collection-scoped endpoints
+ * directly.  Use `resolveTag` only when you have a raw `tagId` and no collection context.
  */
 export declare namespace tags {
     /**
-     * Create a single tag mapping.
-     * If proofId is not provided, automatically generates a serial number.
+     * Create a single tag mapping (admin).
+     *
+     * If `productId` is set without `proofId`, a serial number is auto-generated
+     * unless `useSerialNumber: true` is explicitly passed.
+     * `refType` and `refId` can be set independently of or alongside product/proof.
      *
-     * @param collectionId - Identifier of the parent collection
-     * @param data - Tag creation data
-     * @returns Promise resolving to a CreateTagResponse object
-     * @throws ErrorResponse if the request fails
+     * @param collectionId - Collection context
+     * @param data - Tag creation payload; `tagId` is required
+     * @returns The created tag (`wasUpdated: true` when `force=true` triggered an update)
      *
      * @example
      * ```typescript
      * // Auto-generate serial number
      * const tag = await tags.create('coll_123', {
-     *   tagId: 'TAG001',
+     *   tagId:     'NFC-001',
      *   productId: 'prod_456',
-     *   variantId: 'var_789'
+     *   batchId:   'batch_2026_01',
      * })
      *
-     * // Use explicit proof ID
+     * // Explicit proof + polymorphic ref
      * const tag2 = await tags.create('coll_123', {
-     *   tagId: 'TAG002',
-     *   productId: 'prod_456',
-     *   proofId: 'proof_explicit_123'
+     *   tagId:   'NFC-002',
+     *   refType: 'container',
+     *   refId:   'container-uuid',
      * })
      * ```
      */
     function create(collectionId: string, data: CreateTagRequest): Promise<CreateTagResponse>;
     /**
-     * Create multiple tag mappings efficiently in a batch operation.
-     * By default, auto-generates serial numbers for all tags without explicit proofId.
-     * Tags are grouped by product/variant/batch and serial numbers are generated in
-     * a single transaction per group for optimal performance.
+     * Batch-create tags (admin).
      *
-     * @param collectionId - Identifier of the parent collection
-     * @param data - Batch creation data
-     * @returns Promise resolving to a CreateTagsBatchResponse with summary and results
-     * @throws ErrorResponse if the request fails
+     * Tags with `productId` but no `proofId` automatically get serial numbers.
+     * Serial number generation is grouped by `(productId, variantId, batchId)` for
+     * efficiency.  Partial success is possible — check `results` for individual outcomes.
+     *
+     * @param collectionId - Collection context
+     * @param data - Batch payload; `force` applies to all tags in the batch
+     * @returns `BatchCreateResult` with summary and per-tag outcomes
      *
      * @example
      * ```typescript
      * const result = await tags.createBatch('coll_123', {
      *   tags: [
-     *     { tagId: 'TAG001', productId: 'prod_456', variantId: 'var_789' },
-     *     { tagId: 'TAG002', productId: 'prod_456', variantId: 'var_789' },
-     *     { tagId: 'TAG003', productId: 'prod_456', batchId: 'batch_100' }
-     *   ]
+     *     { tagId: 'NFC-001', productId: 'prod_456', batchId: 'batch_2026_01' },
+     *     { tagId: 'NFC-002', productId: 'prod_456', batchId: 'batch_2026_01' },
+     *   ],
      * })
-     *
-     * console.log(`Created: ${result.summary.created}, Failed: ${result.summary.failed}`)
+     * console.log(`Created: ${result.summary.created}, Conflicts: ${result.summary.conflicts}`)
      * ```
      */
-    function createBatch(collectionId: string, data: CreateTagsBatchRequest): Promise<CreateTagsBatchResponse>;
+    function createBatch(collectionId: string, data: BatchCreateTagRequest): Promise<BatchCreateResult>;
     /**
-     * Update an existing tag mapping.
-     *
-     * @param collectionId - Identifier of the parent collection
-     * @param tagId - Unique tag identifier
-     * @param data - Update data (only include fields to update)
-     * @returns Promise resolving to an UpdateTagResponse object
-     * @throws ErrorResponse if the request fails
+     * Get a single tag by `tagId` (admin).
      *
-     * @example
-     * ```typescript
-     * const updated = await tags.update('coll_123', 'TAG001', {
-     *   variantId: 'var_999',
-     *   metadata: { notes: 'Updated variant' }
-     * })
-     * ```
+     * @param collectionId - Collection context
+     * @param tagId - Physical tag identifier
+     * @returns Full `Tag` record
      */
-    function update(collectionId: string, tagId: string, data: UpdateTagRequest): Promise<UpdateTagResponse>;
+    function get(collectionId: string, tagId: string): Promise<GetTagResponse>;
     /**
-     * Delete a tag mapping.
+     * Update a tag (admin).
      *
-     * @param collectionId - Identifier of the parent collection
-     * @param tagId - Unique tag identifier
-     * @returns Promise resolving to a DeleteTagResponse object
-     * @throws ErrorResponse if the request fails
+     * Partial update — only provided fields are changed.  `metadata` is
+     * deep-merged with the existing value.  Pass `refType: null, refId: null`
+     * to clear the polymorphic ref.
+     *
+     * @param collectionId - Collection context
+     * @param tagId - Physical tag identifier
+     * @param data - Fields to update
+     * @returns Updated `Tag`
      *
      * @example
      * ```typescript
-     * await tags.remove('coll_123', 'TAG001')
+     * const updated = await tags.update('coll_123', 'NFC-001', {
+     *   variantId: 'var_premium',
+     *   metadata:  { notes: 'Updated to premium variant' },
+     * })
+     *
+     * // Clear polymorphic ref
+     * await tags.update('coll_123', 'NFC-001', { refType: null, refId: null })
      * ```
      */
-    function remove(collectionId: string, tagId: string): Promise<DeleteTagResponse>;
+    function update(collectionId: string, tagId: string, data: UpdateTagRequest): Promise<UpdateTagResponse>;
     /**
-     * Get a single tag mapping by tagId.
+     * Delete a tag (admin).
      *
-     * @param collectionId - Identifier of the parent collection
-     * @param tagId - Unique tag identifier
-     * @returns Promise resolving to a GetTagResponse object
-     * @throws ErrorResponse if the request fails
+     * Permanently removes the tag from the per-org shard and the shared index.
      *
-     * @example
-     * ```typescript
-     * const tag = await tags.get('coll_123', 'TAG001')
-     * ```
+     * @param collectionId - Collection context
+     * @param tagId - Physical tag identifier
+     * @returns `{ success: true }`
      */
-    function get(collectionId: string, tagId: string): Promise<GetTagResponse>;
+    function remove(collectionId: string, tagId: string): Promise<DeleteTagResponse>;
     /**
-     * List all tags for a collection with optional filters and pagination.
+     * List tags with optional filters and pagination (admin).
      *
-     * @param collectionId - Identifier of the parent collection
-     * @param params - Optional query parameters for filtering and pagination
-     * @returns Promise resolving to a ListTagsResponse object
-     * @throws ErrorResponse if the request fails
+     * @param collectionId - Collection context
+     * @param params - Optional filter and pagination params
+     * @returns `{ tags: Tag[], limit: number, offset: number }`
      *
      * @example
      * ```typescript
-     * // List all tags
-     * const all = await tags.list('coll_123')
+     * // All tags for a product
+     * const { tags: list } = await tags.list('coll_123', { productId: 'prod_456' })
      *
-     * // List with filters
-     * const filtered = await tags.list('coll_123', {
-     *   productId: 'prod_456',
-     *   variantId: 'var_789',
-     *   limit: 50,
-     *   offset: 0
+     * // All tags linked to a container
+     * const { tags: linked } = await tags.list('coll_123', {
+     *   refType: 'container',
+     *   refId:   'container-uuid',
      * })
      * ```
      */
     function list(collectionId: string, params?: ListTagsRequest): Promise<ListTagsResponse>;
     /**
-     * Reverse lookup — find all tags linked to a given app object (admin).
+     * Reverse lookup — find all tags linked to a given object (admin).
      *
-     * Uses a global cross-shard index keyed on `(orgId, refType, refId)`, so it
-     * is safe to call without knowing which collection the object belongs to.
+     * Uses a compound index on `(orgId, refType, refId)` on the per-org shard.
+     * No embed support on the admin side.
      *
-     * @param collectionId - Collection context (used for auth scope)
+     * @param collectionId - Collection context
      * @param params - `refType` and `refId` are required
      * @returns `{ tags: Tag[] }`
      *
@@ -147,86 +149,112 @@ export declare namespace tags {
      */
     function byRef(collectionId: string, params: ReverseTagLookupParams): Promise<ReverseTagLookupResponse>;
     /**
-     * Public lookup of a single tag by tagId (global).
-     * Optionally embed related collection, product, or proof data.
-     * No authentication required.
+     * Global tag resolve — returns `{ tagId, collectionId }` only.
+     *
+     * Use this **only** when you have a raw `tagId` and do not yet know which
+     * collection it belongs to.  Queries the shared `tag_index` shard.
+     * Once `collectionId` is resolved, call `publicGetByCollection` for full data.
+     *
+     * > The global `/public/tags/by-ref` endpoint has been removed.
+     * > Use the collection-scoped `publicByRef` instead.
      *
-     * @param tagId - Unique tag identifier (globally unique)
-     * @param params - Optional parameters (embed)
-     * @returns Promise resolving to a PublicGetTagResponse with optional embedded data
-     * @throws ErrorResponse if the request fails
+     * @param tagId - Physical tag identifier
+     * @returns `{ tagId, collectionId }` — routing info only, no full tag data
      *
      * @example
      * ```typescript
-     * // Simple lookup
-     * const result = await tags.getTag('TAG001')
+     * // Step 1: resolve collection
+     * const { collectionId } = await tags.resolveTag('NFC-001')
      *
-     * // With embedded data
-     * const withData = await tags.getTag('TAG001', {
-     *   embed: 'collection,product,proof'
-     * })
-     * console.log(withData.tag, withData.collection, withData.product, withData.proof)
+     * // Step 2: full lookup with embedded data
+     * const { tag, embedded } = await tags.publicGetByCollection(
+     *   collectionId, 'NFC-001', 'product,proof'
+     * )
      * ```
      */
-    function getTag(tagId: string, params?: PublicGetTagRequest): Promise<PublicGetTagResponse>;
+    function resolveTag(tagId: string): Promise<TagIndexEntry>;
     /**
-     * Backward-compat: Public lookup with collectionId parameter (ignored).
-     * Calls global route under /public/tags/:tagId.
+     * Single tag lookup with optional embedded data (public).
+     *
+     * `GET /public/collection/:collectionId/tags/:tagId?embed=product,proof,container,ref`
+     *
+     * Supported `embed` values: `'product'`, `'proof'`, `'container'`, `'ref'`
+     * (`'collection'` is not supported — the collection is already known from the URL).
+     *
+     * @param collectionId - Collection context
+     * @param tagId - Physical tag identifier
+     * @param embed - Optional comma-separated embed string
+     * @returns `{ tag: Tag, embedded: TagEmbedded }`
+     *
+     * @example
+     * ```typescript
+     * const { tag, embedded } = await tags.publicGetByCollection(
+     *   'coll_123', 'NFC-001', 'product,proof'
+     * )
+     * const product = embedded.products?.[tag.productId!]
+     * const proof   = embedded.proofs?.[tag.proofId!]
+     * ```
      */
-    function publicGet(_collectionId: string, tagId: string, params?: PublicGetTagRequest): Promise<PublicGetTagResponse>;
+    function publicGetByCollection(collectionId: string, tagId: string, embed?: string): Promise<PublicGetTagResponse>;
     /**
-     * Public batch lookup of multiple tags in a single request (POST).
-     * Only returns tags from the specified collection.
-     * Optionally embed related data. Related data is deduplicated and batch-fetched.
-     * No authentication required.
+     * Batch tag lookup via POST (public).
+     *
+     * `POST /public/collection/:collectionId/tags/lookup`
      *
-     * @param collectionId - Identifier of the collection to search within
-     * @param data - Request containing array of tagIds and optional embed parameter
-     * @returns Promise resolving to PublicBatchLookupResponse with deduplicated related data
-     * @throws ErrorResponse if the request fails
+     * Tags not belonging to this collection are filtered out silently.
+     * Returns deduplicated embedded objects alongside the tag array.
+     *
+     * @param collectionId - Collection context
+     * @param data - `{ tagIds: string[], embed?: string }`
+     * @returns `{ count: number, tags: Tag[], embedded: TagEmbedded }`
      *
      * @example
      * ```typescript
-     * const result = await tags.publicBatchLookup('coll_123', {
-     *   tagIds: ['TAG001', 'TAG002', 'TAG003'],
-     *   embed: 'collection,product'
+     * const { count, tags: list, embedded } = await tags.lookupTags('coll_123', {
+     *   tagIds: ['NFC-001', 'NFC-002', 'NFC-003'],
+     *   embed:  'product,proof',
      * })
-     *
-     * // Access tags and deduplicated collections/products
-     * console.log(result.tags['TAG001'])
-     * console.log(result.collections)
-     * console.log(result.products)
      * ```
      */
-    function lookupTags(data: PublicBatchLookupRequest): Promise<PublicBatchLookupResponse>;
+    function lookupTags(collectionId: string, data: LookupTagsRequest): Promise<TagLookupResponse>;
     /**
-     * Backward-compat: Public batch lookup with collectionId parameter (ignored).
-     * Calls global route under /public/tags/lookup.
+     * Batch tag lookup via GET (public).
+     *
+     * `GET /public/collection/:collectionId/tags/lookup?tagIds=NFC-001,NFC-002&embed=product`
+     *
+     * @param collectionId - Collection context
+     * @param params - `tagIds` is comma-separated; `embed` is optional
+     * @returns `{ count: number, tags: Tag[], embedded: TagEmbedded }`
      */
-    function publicBatchLookup(_collectionId: string, data: PublicBatchLookupRequest): Promise<PublicBatchLookupResponse>;
+    function lookupTagsQuery(collectionId: string, params: LookupTagsQueryRequest): Promise<TagLookupResponse>;
     /**
-     * Public batch lookup of multiple tags using query parameters (GET).
-     * Only returns tags from the specified collection.
-     * Alternative to publicBatchLookup for simple GET requests.
-     * No authentication required.
+     * Reverse lookup by ref via GET (public).
+     *
+     * `GET /public/collection/:collectionId/tags/by-ref?refType=container&refId=<uuid>&embed=ref`
      *
-     * @param collectionId - Identifier of the collection to search within
-     * @param params - Query parameters with comma-separated tagIds and optional embed
-     * @returns Promise resolving to PublicBatchLookupQueryResponse
-     * @throws ErrorResponse if the request fails
+     * @param collectionId - Collection context
+     * @param params - `refType` and `refId` are required; `embed` is optional
+     * @returns `{ tags: Tag[], embedded: TagEmbedded }`
      *
      * @example
      * ```typescript
-     * const result = await tags.publicBatchLookupQuery('coll_123', {
-     *   tagIds: 'TAG001,TAG002,TAG003',
-     *   embed: 'collection'
+     * const { tags: linked, embedded } = await tags.publicByRef('coll_123', {
+     *   refType: 'container',
+     *   refId:   'container-uuid',
+     *   embed:   'container',
      * })
+     * const container = embedded.containers?.[containerId]
      * ```
      */
-    function lookupTagsQuery(params: PublicBatchLookupQueryRequest): Promise<PublicBatchLookupQueryResponse>;
+    function publicByRef(collectionId: string, params: ReverseTagLookupParams): Promise<ByRefResponse>;
     /**
-     * Backward-compat: Public batch lookup (GET) with collectionId parameter (ignored).
-     * Calls global route under /public/tags/lookup.
+     * Reverse lookup by ref via POST (public).
+     *
+     * `POST /public/collection/:collectionId/tags/by-ref`
+     *
+     * @param collectionId - Collection context
+     * @param data - `{ refType, refId, embed? }`
+     * @returns `{ tags: Tag[], embedded: TagEmbedded }`
      */
-    function publicBatchLookupQuery(_collectionId: string, params: PublicBatchLookupQueryRequest): Promise<PublicBatchLookupQueryResponse>;
+    function publicByRefPost(collectionId: string, data: ByRefRequest): Promise<ByRefResponse>;
 }