commerce-kit 0.65.0 → 0.67.0

package/README.md

@@ -38,6 +38,70 @@ const { data, meta } = await commerce.productBrowse({
 const product = await commerce.productGet({ idOrSlug: 'running-shoes' });
 ```
 
+## Custom fields
+
+Merchant-defined fields on products and variants: material, scent notes, lens width. A field
+is defined once per store; every product or variant then holds its own value under
+`metafields`. Variant `attributes` keep coming back, derived from the variant's fields.
+
+```typescript
+// Define a field, then write values with the product or variant
+await commerce.metafieldDefinitionCreate({
+  ownerType: 'product',
+  name: 'Material',
+  type: 'choice',
+  options: [{ label: 'Wool' }, { label: 'Silk' }],
+  storefrontVisible: true,
+  filterable: true,
+});
+await commerce.productUpdate({ idOrSlug: 'classic-tee' }, { metafields: [{ key: 'material', value: 'wool' }] });
+
+// Read: a product carries its fields and its variants' fields
+const product = await commerce.productGet({ idOrSlug: 'classic-tee' });
+product?.metafields; // [{ key: 'material', name: 'Material', type: 'choice', value: 'wool', options: [{ key: 'wool', label: 'Wool' }, …], hidden: false }]
+
+// Lists carry values only when asked, and can be narrowed by filterable fields
+const { data } = await commerce.productBrowse({
+  active: true,
+  include: 'metafields',
+  filter: 'product.custom.material:wool,silk;variant.custom.weight:100..300',
+});
+
+// Filter facets list the filterable fields with their options or number range
+const { metafields } = await commerce.productFilters({ lang: 'de-DE' });
+
+// Private fields need a key with `catalog:write`
+const full = await commerce.productGet({ idOrSlug: 'classic-tee', metafields: 'all' });
+
+// Manage fields: archive keeps every value, delete is for archived fields only
+const { data: fields } = await commerce.metafieldDefinitionBrowse({ ownerType: 'variant' });
+await commerce.metafieldDefinitionUpdate({ idOrKey: 'product.custom.material' }, { filterable: false });
+await commerce.metafieldDefinitionArchive({ idOrKey: 'material' });
+await commerce.metafieldDefinitionRestore({ idOrKey: 'material' });
+await commerce.metafieldDefinitionDelete({ idOrKey: 'material' }, { confirm: 'material', expectedValueCount: 12 });
+
+// Turn a text field into a choice, in place: preview, then confirm the grouping
+const preview = await commerce.metafieldDefinitionConversionPreview({ idOrKey: 'variant.custom.scent' });
+await commerce.metafieldDefinitionConvertToChoice(
+  { idOrKey: 'variant.custom.scent' },
+  { groups: preview.suggestedGroups, planHash: preview.planHash },
+);
+
+// Translations: field names and option labels, then the values of a product or variant
+await commerce.metafieldDefinitionTranslationPut(
+  { idOrKey: 'product.custom.material', locale: 'de-DE' },
+  { name: 'Material', optionLabels: { wool: 'Wolle', silk: 'Seide' } },
+);
+await commerce.productMetafieldTranslationsPut(
+  { idOrSlug: 'classic-tee', locale: 'de-DE' },
+  { values: [{ key: 'care', value: 'Nur Handwäsche' }] },
+);
+await commerce.metafieldsTranslateMissing({ locales: ['de-DE'] }); // machine, never over a person's text
+```
+
+Addressing a field: its id, or `<ownerType>.<namespace>.<key>` such as `product.custom.material`.
+The deprecated variant `attributes` input is still accepted on writes and stored as custom fields.
+
 ## Cart
 
 ```typescript
@@ -51,13 +115,46 @@ const cart = await commerce.cartUpsert({
 // Get cart
 const cart = await commerce.cartGet({ cartId: 'cart_123' });
 
-// Remove item from cart
+// Remove item from cart (pass lineItemId to remove one personalised line of the variant)
 await commerce.cartRemoveItem({
   cartId: 'cart_123',
   variantId: 'variant_456',
 });
 ```
 
+### Personalised lines and shopper uploads
+
+A line can carry `properties`: text (an engraving) or an uploaded file (a photo for a portrait).
+The same variant with different properties becomes its own line.
+
+```typescript
+await commerce.cartUpsert({
+  variantId: 'variant_456',
+  quantity: 1,
+  properties: [{ key: 'engraving', label: 'Engraving', type: 'text', value: 'For Ana' }],
+});
+```
+
+Files are uploaded from the browser with `commerce-kit/uploads` (needs the store's Customer Uploads
+module). The platform endpoint is reached through the storefront's own `/checkout/api/**` proxy, so no
+route or API key is needed in the storefront. Images (JPEG, PNG, WebP, GIF, HEIC, AVIF, TIFF) and PDF,
+up to 20 MB, stored privately.
+
+```typescript
+'use client';
+import { ACCEPTED_LINE_ITEM_UPLOAD_TYPES, lineItemFileProperty, uploadLineItemFile } from 'commerce-kit/uploads';
+
+// <input type="file" accept={ACCEPTED_LINE_ITEM_UPLOAD_TYPES} onChange={...} />
+const { uploadId } = await uploadLineItemFile(file, { variantId });
+// then, on the server (server action):
+await commerce.cartUpsert({
+  cartId,
+  variantId,
+  quantity: 1,
+  properties: [lineItemFileProperty({ key: 'photo', label: 'Photo', uploadId })],
+});
+```
+
 ## Orders
 
 ```typescript