@proveanything/smartlinks 1.8.12 → 1.9.1

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/docs/utils.md

@@ -280,6 +280,8 @@ const path = utils.buildPortalPath(params)
 
 The `validateCondition` function helps determine if content should be shown or hidden based on various criteria like geography, device type, user status, dates, and more.
 
+Enable verbose tracing per invocation with `debugConditions`, or set `globalThis.SMARTLINKS_CONDITION_DEBUG = true` in a browser/devtools session to trace every evaluation.
+
 ### Basic Usage
 
 ```typescript
@@ -291,7 +293,6 @@ const canShow = await utils.validateCondition({
     type: 'and',
     conditions: [{
       type: 'country',
-      useRegions: true,
       regions: ['eu'],
       contains: true
     }]
@@ -328,7 +329,6 @@ await utils.validateCondition({
     type: 'and',
     conditions: [{
       type: 'country',
-      useRegions: true,
       regions: ['eu', 'uk'],
       contains: true  // true = show IN these regions, false = hide IN these regions
     }]
@@ -336,6 +336,20 @@ await utils.validateCondition({
   user: { valid: true, location: { country: 'FR' } }
 })
 
+// Regions and explicit countries can be combined
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{
+      type: 'country',
+      regions: ['eu'],
+      countries: ['CH'],
+      contains: true
+    }]
+  },
+  user: { valid: true, location: { country: 'CH' } }
+})
+
 // Or specific countries
 await utils.validateCondition({
   condition: {
@@ -582,7 +596,7 @@ await utils.validateCondition({
     conditions: [
       { type: 'user', userType: 'valid' },
       { type: 'device', displays: ['mobile'], contains: true },
-      { type: 'country', useRegions: true, regions: ['eu'], contains: true }
+      { type: 'country', regions: ['eu'], contains: true }
     ]
   },
   user: { valid: true, location: { country: 'FR' } },
@@ -630,12 +644,49 @@ const showNewFeature = await utils.validateCondition({
   condition: {
     type: 'and',
     conditions: [
-      { type: 'country', useRegions: true, regions: ['northamerica'], contains: true },
+      { type: 'country', regions: ['northamerica'], contains: true },
       { type: 'date', dateTest: 'after', afterDate: '2026-03-01' }
     ]
   },
   user: { valid: true, location: { country: 'US' } }
 })
+
+### Debug Logging
+
+Trace which condition is being evaluated, whether it passed, and why:
+
+```typescript
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [
+      { type: 'user', userType: 'valid' },
+      { type: 'country', regions: ['eu'], contains: true }
+    ]
+  },
+  user: { valid: true, location: { country: 'DE' } },
+  debugConditions: true
+})
+
+// Or enable globally in the browser console/devtools
+globalThis.SMARTLINKS_CONDITION_DEBUG = true
+```
+
+If you want to route logs somewhere specific, pass a logger:
+
+```typescript
+await utils.validateCondition({
+  condition: {
+    type: 'and',
+    conditions: [{ type: 'user', userType: 'valid' }]
+  },
+  user: { valid: true },
+  debugConditions: {
+    label: 'checkout-gate',
+    logger: (...args) => console.log(...args)
+  }
+})
+```
 ```
 
 #### Mobile-Only Features

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

@@ -5,7 +5,7 @@ export { iframe } from "./iframe";
 export * as cache from './cache';
 export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder';
 export * as utils from './utils';
-export type { PortalPathParams, ConditionParams, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils';
+export type { PortalPathParams, ConditionParams, ConditionDebugOptions, ConditionDebugLogger, ConditionSet, Condition, UserInfo, ProductInfo, ProofInfo, CollectionInfo, } from './utils';
 export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, AuthLocation, } from "./api/auth";
 export type { UserAccountRegistrationRequest, } from "./types/auth";
 export type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, CommsSettings, TopicConfig, CommsSettingsGetResponse, CommsSettingsPatchBody, CommsPublicTopicsResponse, UnsubscribeQuery, UnsubscribeResponse, CommsConsentUpsertRequest, CommsPreferencesUpsertRequest, CommsSubscribeRequest, CommsSubscribeResponse, CommsSubscriptionCheckQuery, CommsSubscriptionCheckResponse, CommsListMethodsQuery, CommsListMethodsResponse, RegisterEmailMethodRequest, RegisterSmsMethodRequest, RegisterMethodResponse, SubscriptionsResolveRequest, SubscriptionsResolveResponse, } from "./types/comms";
@@ -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";