@proveanything/smartlinks 1.9.19 → 1.9.20

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.19  |  Generated: 2026-04-16T12:41:11.180Z
+Version: 1.9.20  |  Generated: 2026-04-17T10:13:30.466Z
 
 This is a concise summary of all available API functions and types.
 
@@ -6847,6 +6847,18 @@ interface UserInfo {
 interface ProductInfo {
   id: string
   tags?: Record<string, any>
+  * Facet values assigned to this product.
+  * Shape mirrors `ProductFacetMap`: a map of facet key → array of value objects.
+  * Each value object must have at minimum a `key` string property.
+  *
+  * @example
+  * ```ts
+  * {
+  *   material: [{ key: 'cotton', name: 'Cotton' }],
+  *   certifications: [{ key: 'organic', name: 'Organic' }, { key: 'recycled', name: 'Recycled' }]
+  * }
+  * ```
+  facets?: Record<string, Array<{ key: string; [k: string]: unknown }>>
 }
 ```
 

package/dist/utils/conditions.d.ts

@@ -114,10 +114,62 @@ export interface ItemStatusCondition extends BaseCondition {
     type: 'itemStatus';
     statusType: 'isClaimable' | 'notClaimable' | 'noProof' | 'hasProof' | 'isVirtual' | 'notVirtual';
 }
+/**
+ * Facet-based condition — gates on the facet values assigned to the current product.
+ *
+ * The `facetKey` identifies which facet dimension to inspect (e.g. `'material'`, `'region'`,
+ * `'certifications'`).  The optional `values` array lists the value `key`s to test.
+ *
+ * ### Match modes (`matchMode`)
+ *
+ * | Mode | Passes when |
+ * |------|-------------|
+ * | `'any'` (default) | The product has **at least one** of the listed values on this facet |
+ * | `'all'` | The product has **every** listed value (multi-value facets only) |
+ * | `'none'` | The product has **none** of the listed values |
+ * | `'hasFacet'` | The product has **any** value on this facet (ignores `values`) |
+ * | `'notHasFacet'` | The product has **no** values on this facet (ignores `values`) |
+ *
+ * ### Examples
+ *
+ * ```typescript
+ * // Must carry the 'cotton' or 'linen' value on the 'material' facet
+ * { type: 'facet', facetKey: 'material', matchMode: 'any', values: ['cotton', 'linen'] }
+ *
+ * // Must carry BOTH 'organic' and 'recycled' on the 'certifications' facet
+ * { type: 'facet', facetKey: 'certifications', matchMode: 'all', values: ['organic', 'recycled'] }
+ *
+ * // Must NOT carry 'discontinued' on the 'status' facet
+ * { type: 'facet', facetKey: 'status', matchMode: 'none', values: ['discontinued'] }
+ *
+ * // Product must have at least one value on the 'region' facet
+ * { type: 'facet', facetKey: 'region', matchMode: 'hasFacet' }
+ * ```
+ */
+export interface FacetCondition extends BaseCondition {
+    type: 'facet';
+    /** The facet dimension key to inspect (e.g. `'material'`, `'region'`) */
+    facetKey: string;
+    /**
+     * How to match against `values`.
+     * - `'any'` — pass if the product has at least one of the listed values (default)
+     * - `'all'` — pass if the product has every listed value
+     * - `'none'` — pass if the product has none of the listed values
+     * - `'hasFacet'` — pass if the product has any value on this facet (ignores `values`)
+     * - `'notHasFacet'` — pass if the product has no values on this facet (ignores `values`)
+     */
+    matchMode?: 'any' | 'all' | 'none' | 'hasFacet' | 'notHasFacet';
+    /**
+     * Facet value keys to test against.
+     * Required for `'any'`, `'all'`, and `'none'` match modes.
+     * Ignored for `'hasFacet'` and `'notHasFacet'`.
+     */
+    values?: string[];
+}
 /**
  * Union of all condition types
  */
-export type Condition = CountryCondition | VersionCondition | DeviceCondition | NestedCondition | UserCondition | ProductCondition | TagCondition | DateCondition | GeofenceCondition | ValueCondition | ItemStatusCondition;
+export type Condition = CountryCondition | VersionCondition | DeviceCondition | NestedCondition | UserCondition | ProductCondition | TagCondition | FacetCondition | DateCondition | GeofenceCondition | ValueCondition | ItemStatusCondition;
 /**
  * Condition set that combines multiple conditions
  */
@@ -166,6 +218,23 @@ export interface UserInfo {
 export interface ProductInfo {
     id: string;
     tags?: Record<string, any>;
+    /**
+     * Facet values assigned to this product.
+     * Shape mirrors `ProductFacetMap`: a map of facet key → array of value objects.
+     * Each value object must have at minimum a `key` string property.
+     *
+     * @example
+     * ```ts
+     * {
+     *   material: [{ key: 'cotton', name: 'Cotton' }],
+     *   certifications: [{ key: 'organic', name: 'Organic' }, { key: 'recycled', name: 'Recycled' }]
+     * }
+     * ```
+     */
+    facets?: Record<string, Array<{
+        key: string;
+        [k: string]: unknown;
+    }>>;
 }
 /**
  * Proof information for condition validation
@@ -234,6 +303,7 @@ export interface ConditionDebugOptions {
  * - **user** - User authentication status (logged in, owner, admin)
  * - **product** - Product-specific conditions
  * - **tag** - Product tag-based conditions
+ * - **facet** - Product facet-based conditions (any/all/none of specific facet values)
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons

package/dist/utils/conditions.js

@@ -93,7 +93,7 @@ function summarizeConditionSet(condition) {
     return `${(_a = condition.type) !== null && _a !== void 0 ? _a : 'and'} (${(_c = (_b = condition.conditions) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0} conditions)`;
 }
 function summarizeCondition(condition) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e;
     switch (condition.type) {
         case 'country':
             return `country regions=${((_a = condition.regions) === null || _a === void 0 ? void 0 : _a.join(',')) || 'none'} countries=${((_b = condition.countries) === null || _b === void 0 ? void 0 : _b.join(',')) || 'none'} contains=${condition.contains}`;
@@ -115,6 +115,11 @@ function summarizeCondition(condition) {
             return `geofence contains=${condition.contains}`;
         case 'value':
             return `value field=${condition.field} ${condition.validationType} ${String(condition.value)}`;
+        case 'facet': {
+            const mode = (_c = condition.matchMode) !== null && _c !== void 0 ? _c : 'any';
+            const vals = (_e = (_d = condition.values) === null || _d === void 0 ? void 0 : _d.join(', ')) !== null && _e !== void 0 ? _e : '—';
+            return `facet key=${condition.facetKey} mode=${mode} values=[${vals}]`;
+        }
         case 'itemStatus':
             return `itemStatus ${condition.statusType}`;
         default:
@@ -143,6 +148,8 @@ async function evaluateConditionEntry(condition, params) {
             return validateGeofence(condition, params);
         case 'value':
             return validateValue(condition, params);
+        case 'facet':
+            return validateFacet(condition, params);
         case 'itemStatus':
             return validateItemStatus(condition, params);
         default:
@@ -162,6 +169,7 @@ async function evaluateConditionEntry(condition, params) {
  * - **user** - User authentication status (logged in, owner, admin)
  * - **product** - Product-specific conditions
  * - **tag** - Product tag-based conditions
+ * - **facet** - Product facet-based conditions (any/all/none of specific facet values)
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons
@@ -730,6 +738,82 @@ async function validateValue(condition, params) {
         },
     };
 }
+/**
+ * Validate facet-based condition
+ */
+async function validateFacet(condition, params) {
+    var _a, _b, _c;
+    const { facetKey, matchMode = 'any', values = [] } = condition;
+    const facets = (_a = params.product) === null || _a === void 0 ? void 0 : _a.facets;
+    // No product
+    if (!((_b = params.product) === null || _b === void 0 ? void 0 : _b.id)) {
+        return {
+            passed: false,
+            detail: 'Product ID was not available.',
+            context: { facetKey, matchMode },
+        };
+    }
+    const assigned = (_c = facets === null || facets === void 0 ? void 0 : facets[facetKey]) !== null && _c !== void 0 ? _c : [];
+    const assignedKeys = assigned.map(v => v.key);
+    // Presence-only modes — ignore `values`
+    if (matchMode === 'hasFacet') {
+        return {
+            passed: assignedKeys.length > 0,
+            detail: `Product ${assigned.length > 0 ? 'has' : 'does not have'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    if (matchMode === 'notHasFacet') {
+        return {
+            passed: assignedKeys.length === 0,
+            detail: `Product ${assigned.length === 0 ? 'has no' : 'has'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    // Value-matching modes require at least one value to test
+    if (values.length === 0) {
+        return {
+            passed: false,
+            detail: `Facet condition for '${facetKey}' with matchMode '${matchMode}' requires at least one value.`,
+            context: { facetKey, matchMode },
+        };
+    }
+    if (matchMode === 'any') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length > 0,
+            detail: matched.length > 0
+                ? `Product matched facet '${facetKey}' value(s): [${matched.join(', ')}].`
+                : `Product did not match any of [${values.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    if (matchMode === 'all') {
+        const missing = values.filter(v => !assignedKeys.includes(v));
+        return {
+            passed: missing.length === 0,
+            detail: missing.length === 0
+                ? `Product has all required values on facet '${facetKey}'.`
+                : `Product is missing [${missing.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, missing, assignedKeys },
+        };
+    }
+    if (matchMode === 'none') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length === 0,
+            detail: matched.length === 0
+                ? `Product correctly has none of [${values.join(', ')}] on facet '${facetKey}'.`
+                : `Product has forbidden value(s) [${matched.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    return {
+        passed: false,
+        detail: `Unsupported facet matchMode '${matchMode}'.`,
+        context: { facetKey, matchMode },
+    };
+}
 /**
  * Validate item status condition
  */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.19  |  Generated: 2026-04-16T12:41:11.180Z
+Version: 1.9.20  |  Generated: 2026-04-17T10:13:30.466Z
 
 This is a concise summary of all available API functions and types.
 
@@ -6847,6 +6847,18 @@ interface UserInfo {
 interface ProductInfo {
   id: string
   tags?: Record<string, any>
+  * Facet values assigned to this product.
+  * Shape mirrors `ProductFacetMap`: a map of facet key → array of value objects.
+  * Each value object must have at minimum a `key` string property.
+  *
+  * @example
+  * ```ts
+  * {
+  *   material: [{ key: 'cotton', name: 'Cotton' }],
+  *   certifications: [{ key: 'organic', name: 'Organic' }, { key: 'recycled', name: 'Recycled' }]
+  * }
+  * ```
+  facets?: Record<string, Array<{ key: string; [k: string]: unknown }>>
 }
 ```
 

package/package.json

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