commerce-kit 0.65.0 → 0.66.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