@proveanything/smartlinks 1.8.12 → 1.9.0

package/dist/docs/PRODUCT_FACETS_SDK.md

@@ -0,0 +1,347 @@
+# Product Facets SDK Reference
+
+Simple SDK-facing reference for the facet API.
+
+This document covers:
+
+- admin facet endpoints
+- public facet endpoints
+- collection-level facet routes
+- TypeScript interfaces for facet definitions, values, and aggregation queries
+
+## Current route model
+
+The facet API stays under `/api/v1`.
+
+Facets are mounted directly under the collection.
+
+### Admin base
+
+```ts
+/api/v1/admin/collection/:collectionId/facets
+```
+
+### Public base
+
+```ts
+/api/v1/public/collection/:collectionId/facets
+```
+
+## Admin endpoints
+
+### List facet definitions
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets
+```
+
+Optional query params:
+
+```ts
+includeValues?: boolean
+includeDeleted?: boolean
+kind?: 'system' | 'custom'
+reserved?: boolean
+```
+
+### Create facet definition
+
+```ts
+POST /api/v1/admin/collection/:collectionId/facets
+```
+
+### Get facet definition
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/:facetKey
+```
+
+Optional query params:
+
+```ts
+includeValues?: boolean
+includeDeleted?: boolean
+```
+
+### Update facet definition
+
+```ts
+PUT /api/v1/admin/collection/:collectionId/facets/:facetKey
+```
+
+### Delete facet definition
+
+```ts
+DELETE /api/v1/admin/collection/:collectionId/facets/:facetKey
+```
+
+Current behavior:
+
+- reserved facet definitions cannot be deleted
+- facet definitions with product assignments cannot be deleted
+
+### List facet values
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/:facetKey/values
+```
+
+Optional query params:
+
+```ts
+includeDeleted?: boolean
+```
+
+### Create facet value
+
+```ts
+POST /api/v1/admin/collection/:collectionId/facets/:facetKey/values
+```
+
+### Get facet value
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/:facetKey/values/:valueKey
+```
+
+Optional query params:
+
+```ts
+includeDeleted?: boolean
+```
+
+### Update facet value
+
+```ts
+PUT /api/v1/admin/collection/:collectionId/facets/:facetKey/values/:valueKey
+```
+
+### Delete facet value
+
+```ts
+DELETE /api/v1/admin/collection/:collectionId/facets/:facetKey/values/:valueKey
+```
+
+Current behavior:
+
+- deleting a facet value removes its product assignments
+- affected product `facets` summaries are synchronized after the delete
+
+### Query facet counts
+
+```ts
+POST /api/v1/admin/collection/:collectionId/facets/query
+```
+
+Supported query filters now:
+
+- `search`
+- `status`
+- `schemaType`
+- `type`
+- `productIds`
+- `sku`
+- `gtin`
+- `category`
+- `tags`
+- `facetEquals`
+
+## Public endpoints
+
+### List facet definitions
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets
+```
+
+Optional query params:
+
+```ts
+includeValues?: boolean
+```
+
+### Get facet definition
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/:facetKey
+```
+
+Optional query params:
+
+```ts
+includeValues?: boolean
+```
+
+### List facet values
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/:facetKey/values
+```
+
+### Get facet value
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/:facetKey/values/:valueKey
+```
+
+### Query facet counts
+
+```ts
+POST /api/v1/public/collection/:collectionId/facets/query
+```
+
+Public endpoints are read-only.
+
+## TypeScript interfaces
+
+## Core JSON types
+
+```ts
+export type JsonPrimitive = string | number | boolean | null
+
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+```
+
+## Facet definition types
+
+```ts
+export interface FacetDefinition {
+  id: string
+  orgId: string
+  collectionId: string
+  key: string
+  name: string
+  description?: string | null
+  cardinality: 'single' | 'multi'
+  kind: 'system' | 'custom'
+  hierarchical: boolean
+  reserved: boolean
+  config: Record<string, JsonValue>
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+  values?: FacetValue[]
+}
+
+export interface FacetDefinitionWriteInput {
+  key?: string
+  name: string
+  description?: string | null
+  cardinality?: 'single' | 'multi'
+  kind?: 'system' | 'custom'
+  hierarchical?: boolean
+  reserved?: boolean
+  config?: Record<string, JsonValue>
+}
+```
+
+## Facet value types
+
+```ts
+export interface FacetValue {
+  id: string
+  orgId: string
+  collectionId: string
+  facetDefinitionId: string
+  facetKey?: string
+  key: string
+  slug?: string | null
+  name: string
+  shortName?: string | null
+  description?: string | null
+  color?: string | null
+  icon?: string | null
+  image?: Record<string, JsonValue> | null
+  metadata: Record<string, JsonValue>
+  sortOrder: number
+  parentValueId?: string | null
+  parentValueKey?: string | null
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+  count?: number
+}
+
+export interface FacetValueWriteInput {
+  key?: string
+  slug?: string | null
+  name: string
+  shortName?: string | null
+  description?: string | null
+  color?: string | null
+  icon?: string | null
+  image?: Record<string, JsonValue> | null
+  metadata?: Record<string, JsonValue>
+  sortOrder?: number
+  parentValueKey?: string | null
+}
+```
+
+## List response types
+
+```ts
+export interface FacetListResponse {
+  items: FacetDefinition[]
+}
+
+export interface FacetValueListResponse {
+  facet: FacetDefinition
+  items: FacetValue[]
+}
+
+export interface FacetValueResponse {
+  facet: FacetDefinition
+  item: FacetValue
+}
+```
+
+## Query types
+
+```ts
+export interface FacetQueryRequest {
+  facetKeys?: string[]
+  includeEmpty?: boolean
+  includeDeleted?: boolean
+  query?: {
+    search?: string
+    status?: string[]
+    schemaType?: string[]
+    type?: string[]
+    productIds?: string[]
+    sku?: string
+    gtin?: string
+    category?: string[]
+    tags?: string[]
+    facetEquals?: Record<string, JsonValue | JsonValue[]>
+  }
+}
+
+export interface FacetBucket {
+  facetKey: string
+  valueKey: string
+  name?: string
+  count: number
+}
+
+export interface FacetQueryResponse {
+  items: Array<{
+    facet: FacetDefinition
+    values: FacetValue[]
+  }>
+  buckets: FacetBucket[]
+  meta?: {
+    source?: 'postgres'
+    matchedProducts?: number
+  }
+}
+```
+
+## Notes for SDK implementers
+
+- treat facet definitions and facet values as collection-scoped resources
+- use the facet API to manage definitions and values
+- use product read/write routes to assign facet data onto products
+- treat `label` and `category` as reserved system facets when present

package/dist/http.d.ts

@@ -117,7 +117,8 @@ export declare function configureSdkCache(options: {
  * ```ts
  * invalidateCache()                     // clear everything
  * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all product responses
+ * invalidateCache('/product/')          // all legacy singular product responses
+ * invalidateCache('/products/')         // all canonical plural product responses
  * ```
  */
 export declare function invalidateCache(urlPattern?: string): void;

package/dist/http.js

@@ -83,7 +83,7 @@ const CACHE_TTL_RULES = [
     { pattern: /\/proof\/[^/]*(\?.*)?$/i, ttlMs: 30000 },
     { pattern: /\/attestation\/[^/]*(\?.*)?$/i, ttlMs: 2 * 60000 },
     // Slow-changing top-level resources — long TTLs, matched only when path ends at the ID
-    { pattern: /\/product\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 },
+    { pattern: /\/products?\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 },
     { pattern: /\/variant\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 },
     { pattern: /\/collection\/[^/]*(\?.*)?$/i, ttlMs: 60 * 60000 }, // 1 hour
 ];
@@ -507,7 +507,8 @@ export function configureSdkCache(options) {
  * ```ts
  * invalidateCache()                     // clear everything
  * invalidateCache('/collection/abc123') // one specific collection
- * invalidateCache('/product/')          // all product responses
+ * invalidateCache('/product/')          // all legacy singular product responses
+ * invalidateCache('/products/')         // all canonical plural product responses
  * ```
  */
 export function invalidateCache(urlPattern) {

package/dist/iframeResponder.js

@@ -593,7 +593,7 @@ export class IframeResponder {
         }
         // Product request - ONLY match direct product endpoint, not app config endpoints
         if (this.cache.product && this.options.productId) {
-            const productMatch = path.match(/^public\/collection\/[^/]+\/product\/([^/]+)$/);
+            const productMatch = path.match(/^public\/collection\/[^/]+\/products?\/([^/]+)$/);
             if (productMatch && productMatch[1] === this.options.productId) {
                 return JSON.parse(JSON.stringify(this.cache.product));
             }

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export type { BatchResponse, BatchCreateRequest, BatchUpdateRequest, } from "./t
 export type { VariantResponse, VariantCreateRequest, VariantUpdateRequest, } from "./types/variant";
 export type { BroadcastSendRequest } from "./types/broadcasts";
 export type { AppConfigOptions } from "./api/appConfiguration";
-export type { ProductCreateRequest, ProductUpdateRequest, Product, } from "./types/product";
+export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCreateRequest, ProductClaimCreateInput, ProductClaimCreateRequestBody, ProductClaimLookupInput, ProductFacetMap, ProductFacetValue, ProductImage, ProductImageThumbnails, ProductImageUrlInput, ProductKey, ProductQueryRequest, ProductQueryResponse, ProductUpdateRequest, Product, ProductWriteInput, PublicProduct, } from "./types/product";
+export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
 export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, } from "./types/collection";
 export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";