@aifeatures/backend 0.3.0 → 0.3.1

package/dist/index.d.cts

@@ -462,6 +462,10 @@ type Option = {
          * Images shown when this value is selected; empty = fall back to the product gallery.
          */
         images: Array<string>;
+        /**
+         * Colour chip for this value — a hex colour or an image URL — shown instead of the text label on the storefront. null when unset; set it with setProductVariants.
+         */
+        swatch: string | null;
     }>;
 };
 type VariantOptionValue = {
@@ -538,6 +542,9 @@ type InventoryInput = {
 };
 type NestedVariantInput = {
     title?: string | null;
+    /**
+     * Merchant SKU for this variant. Omitted or null = the server generates a stable opaque one (every variant always carries a SKU — it is the identifier fulfillment systems key on).
+     */
     sku?: string | null;
     unit_amount?: number;
     compare_at_amount?: number | null;
@@ -679,6 +686,9 @@ type CreateMultiItemTestOrder = {
 };
 type CreateVariant = {
     title?: string | null;
+    /**
+     * Merchant SKU for this variant. Omitted or null = the server generates a stable opaque one (every variant always carries a SKU — it is the identifier fulfillment systems key on).
+     */
     sku?: string | null;
     unit_amount?: number;
     compare_at_amount?: number | null;
@@ -721,6 +731,10 @@ type ReconcileOptionValueInput = {
      * Images shown when this value is selected (e.g. model shots of the Black colorway), in display order. REPLACES the value's whole gallery when present — to add an image, resend the existing URLs plus the new one. Omitted = keep the value's current images unchanged; [] = remove them all. Values without images fall back to the product-level gallery.
      */
     images?: Array<string>;
+    /**
+     * The colour chip shown for this value instead of its text label: a hex colour ("#6B7A4F") or an image URL for a pattern/finish. NOTE the clear token differs from `images` above because this is a single value, not a list: omitted = keep the current swatch unchanged; null = remove it. Values without a swatch keep rendering as their text label, which is how a merchant sees which colours still need one. Never send product photography here — that is what `images` is for.
+     */
+    swatch?: string | null;
 };
 type ReconcileOptionInput = {
     /**
@@ -771,7 +785,10 @@ type SetProductVariants = {
 };
 type UpdateVariant = {
     title?: string | null;
-    sku?: string | null;
+    /**
+     * New SKU for this variant. Cannot be cleared to null — every variant carries one. Omit the field to keep the current value.
+     */
+    sku?: string;
     unit_amount?: number | null;
     compare_at_amount?: number | null;
     allow_custom_amount?: boolean;
@@ -1512,6 +1529,10 @@ type PublicOption = {
          * Images to show when this value is selected; empty = fall back to product.images.
          */
         images: Array<string>;
+        /**
+         * Colour chip for this value — a hex colour or an image URL — rendered instead of the text label. null when the merchant hasn't set one, in which case the value renders as its text.
+         */
+        swatch: string | null;
     }>;
 };
 type PublicVariant = {
@@ -3148,6 +3169,10 @@ type CreateFormWithSiteTokenData = {
     url: "/api/v1/forms";
 };
 type CreateFormWithSiteTokenErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized - requires site token
      */
@@ -3441,6 +3466,10 @@ type CreateFormData = {
     url: "/api/v1/sites/{siteId}/forms";
 };
 type CreateFormErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized
      */
@@ -3519,6 +3548,10 @@ type UpdateFormData = {
     url: "/api/v1/forms/{formId}";
 };
 type UpdateFormErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized
      */
@@ -3961,7 +3994,7 @@ declare const createVariant: <ThrowOnError extends boolean = false>(options: Opt
 /**
  * Reconcile the product's option/variant matrix
  *
- * Declarative full-desired-state reconcile of a product's options and variants in ONE atomic operation — the only supported way to grow or drop an option axis on a product that already has variants. `options` and `variants` are the complete post-state: variants with an id survive (coordinates, price, title may change; inventory, order references, and open checkout sessions stay attached), entries without an id are created, and every currently-active variant must appear (kept, changed, or active: false) or the request is rejected naming the missing ids. An existing option omitted from `options` is REMOVED, taking its values and every variant's coordinate on that axis with it; the removal is refused only when it would collapse two ACTIVE variants onto the same combination (deactivate one first). Variants are never hard-deleted — active: false is the removal. Requires `matrix_version` from getProduct; a stale version is a 409 carrying the current matrix. Coordinate changes on surviving axes additionally require `allow_coordinate_changes: true`. Option values carry per-value `images` (the gallery shown when that value is selected, e.g. the Black colorway's model shots): omitted = keep current, [] = clear — storefronts fall back to product.images for values without any.
+ * Declarative full-desired-state reconcile of a product's options and variants in ONE atomic operation — the only supported way to grow or drop an option axis on a product that already has variants. `options` and `variants` are the complete post-state: variants with an id survive (coordinates, price, title may change; inventory, order references, and open checkout sessions stay attached), entries without an id are created, and every currently-active variant must appear (kept, changed, or active: false) or the request is rejected naming the missing ids. An existing option omitted from `options` is REMOVED, taking its values and every variant's coordinate on that axis with it; the removal is refused only when it would collapse two ACTIVE variants onto the same combination (deactivate one first). Variants are never hard-deleted — active: false is the removal. Requires `matrix_version` from getProduct; a stale version is a 409 carrying the current matrix. Coordinate changes on surviving axes additionally require `allow_coordinate_changes: true`. Option values carry per-value `images` (the gallery shown when that value is selected, e.g. the Black colorway's model shots): omitted = keep current, [] = clear — storefronts fall back to product.images for values without any. Values also carry an optional `swatch` (a hex colour like `#4A5D23`, or an image URL for a pattern/texture) which renders the value as a colour chip instead of its text: omitted = keep current, null = clear. Note the divergence from `images` — swatch is a single nullable value, so `null` is its clear token, not `[]`.
  */
 declare const setProductVariants: <ThrowOnError extends boolean = false>(options: Options<SetProductVariantsData, ThrowOnError>) => RequestResult<SetProductVariantsResponses, SetProductVariantsErrors, ThrowOnError, "fields">;
 /**

package/dist/index.d.ts

@@ -462,6 +462,10 @@ type Option = {
          * Images shown when this value is selected; empty = fall back to the product gallery.
          */
         images: Array<string>;
+        /**
+         * Colour chip for this value — a hex colour or an image URL — shown instead of the text label on the storefront. null when unset; set it with setProductVariants.
+         */
+        swatch: string | null;
     }>;
 };
 type VariantOptionValue = {
@@ -538,6 +542,9 @@ type InventoryInput = {
 };
 type NestedVariantInput = {
     title?: string | null;
+    /**
+     * Merchant SKU for this variant. Omitted or null = the server generates a stable opaque one (every variant always carries a SKU — it is the identifier fulfillment systems key on).
+     */
     sku?: string | null;
     unit_amount?: number;
     compare_at_amount?: number | null;
@@ -679,6 +686,9 @@ type CreateMultiItemTestOrder = {
 };
 type CreateVariant = {
     title?: string | null;
+    /**
+     * Merchant SKU for this variant. Omitted or null = the server generates a stable opaque one (every variant always carries a SKU — it is the identifier fulfillment systems key on).
+     */
     sku?: string | null;
     unit_amount?: number;
     compare_at_amount?: number | null;
@@ -721,6 +731,10 @@ type ReconcileOptionValueInput = {
      * Images shown when this value is selected (e.g. model shots of the Black colorway), in display order. REPLACES the value's whole gallery when present — to add an image, resend the existing URLs plus the new one. Omitted = keep the value's current images unchanged; [] = remove them all. Values without images fall back to the product-level gallery.
      */
     images?: Array<string>;
+    /**
+     * The colour chip shown for this value instead of its text label: a hex colour ("#6B7A4F") or an image URL for a pattern/finish. NOTE the clear token differs from `images` above because this is a single value, not a list: omitted = keep the current swatch unchanged; null = remove it. Values without a swatch keep rendering as their text label, which is how a merchant sees which colours still need one. Never send product photography here — that is what `images` is for.
+     */
+    swatch?: string | null;
 };
 type ReconcileOptionInput = {
     /**
@@ -771,7 +785,10 @@ type SetProductVariants = {
 };
 type UpdateVariant = {
     title?: string | null;
-    sku?: string | null;
+    /**
+     * New SKU for this variant. Cannot be cleared to null — every variant carries one. Omit the field to keep the current value.
+     */
+    sku?: string;
     unit_amount?: number | null;
     compare_at_amount?: number | null;
     allow_custom_amount?: boolean;
@@ -1512,6 +1529,10 @@ type PublicOption = {
          * Images to show when this value is selected; empty = fall back to product.images.
          */
         images: Array<string>;
+        /**
+         * Colour chip for this value — a hex colour or an image URL — rendered instead of the text label. null when the merchant hasn't set one, in which case the value renders as its text.
+         */
+        swatch: string | null;
     }>;
 };
 type PublicVariant = {
@@ -3148,6 +3169,10 @@ type CreateFormWithSiteTokenData = {
     url: "/api/v1/forms";
 };
 type CreateFormWithSiteTokenErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized - requires site token
      */
@@ -3441,6 +3466,10 @@ type CreateFormData = {
     url: "/api/v1/sites/{siteId}/forms";
 };
 type CreateFormErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized
      */
@@ -3519,6 +3548,10 @@ type UpdateFormData = {
     url: "/api/v1/forms/{formId}";
 };
 type UpdateFormErrors = {
+    /**
+     * Form name indicates credential/payment collection, which is not supported
+     */
+    400: Error;
     /**
      * Unauthorized
      */
@@ -3961,7 +3994,7 @@ declare const createVariant: <ThrowOnError extends boolean = false>(options: Opt
 /**
  * Reconcile the product's option/variant matrix
  *
- * Declarative full-desired-state reconcile of a product's options and variants in ONE atomic operation — the only supported way to grow or drop an option axis on a product that already has variants. `options` and `variants` are the complete post-state: variants with an id survive (coordinates, price, title may change; inventory, order references, and open checkout sessions stay attached), entries without an id are created, and every currently-active variant must appear (kept, changed, or active: false) or the request is rejected naming the missing ids. An existing option omitted from `options` is REMOVED, taking its values and every variant's coordinate on that axis with it; the removal is refused only when it would collapse two ACTIVE variants onto the same combination (deactivate one first). Variants are never hard-deleted — active: false is the removal. Requires `matrix_version` from getProduct; a stale version is a 409 carrying the current matrix. Coordinate changes on surviving axes additionally require `allow_coordinate_changes: true`. Option values carry per-value `images` (the gallery shown when that value is selected, e.g. the Black colorway's model shots): omitted = keep current, [] = clear — storefronts fall back to product.images for values without any.
+ * Declarative full-desired-state reconcile of a product's options and variants in ONE atomic operation — the only supported way to grow or drop an option axis on a product that already has variants. `options` and `variants` are the complete post-state: variants with an id survive (coordinates, price, title may change; inventory, order references, and open checkout sessions stay attached), entries without an id are created, and every currently-active variant must appear (kept, changed, or active: false) or the request is rejected naming the missing ids. An existing option omitted from `options` is REMOVED, taking its values and every variant's coordinate on that axis with it; the removal is refused only when it would collapse two ACTIVE variants onto the same combination (deactivate one first). Variants are never hard-deleted — active: false is the removal. Requires `matrix_version` from getProduct; a stale version is a 409 carrying the current matrix. Coordinate changes on surviving axes additionally require `allow_coordinate_changes: true`. Option values carry per-value `images` (the gallery shown when that value is selected, e.g. the Black colorway's model shots): omitted = keep current, [] = clear — storefronts fall back to product.images for values without any. Values also carry an optional `swatch` (a hex colour like `#4A5D23`, or an image URL for a pattern/texture) which renders the value as a colour chip instead of its text: omitted = keep current, null = clear. Note the divergence from `images` — swatch is a single nullable value, so `null` is its clear token, not `[]`.
  */
 declare const setProductVariants: <ThrowOnError extends boolean = false>(options: Options<SetProductVariantsData, ThrowOnError>) => RequestResult<SetProductVariantsResponses, SetProductVariantsErrors, ThrowOnError, "fields">;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifeatures/backend",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "TypeScript API client for aifeatures backend",
   "type": "module",
   "main": "./dist/index.cjs",