@sixtyninecommerce/admin 0.9.0 → 0.10.0

package/README.md

@@ -981,6 +981,32 @@ with the cancel and made right after it commits, so read the order again for the
 it cannot be made, the order's history says so and why. A cancel made with no merchant present (an
 integration's own path) refunds automatically.
 
+### Handing goods over before an order is paid
+
+A store can require full payment before goods leave: its `fulfillmentPaymentPolicy`
+(`{ requireFullPayment, exemptMethodCodes }`, a Channel setting, off by default). Then creating,
+extending or shipping a fulfilment of an order whose COLLECTED money (settled, or held by a payment
+provider — not a bank transfer, an invoice or cash on delivery still to be paid) does not cover what
+it bills is refused `ORDER_NOT_COVERED` (a `BusinessRuleError`), unless the order is on net terms,
+its latest payment is on an exempt method, or an override was recorded. A carrier or 3PL reporting
+goods that already left is recorded, never refused.
+
+```ts
+const coverage = await admin.fulfillments.coverage(orderId); // ReadOrder
+// { policyActive: true, covered: false, outstanding: 8100, currencyCode: 'EUR',
+//   exempt: false, exemptReason: null, allowed: false, override: null, … }
+const override = await admin.fulfillments.allowUncovered(
+  orderId,
+  'Customer pays on pickup', // required, at most 500 characters
+  { idempotencyKey }
+); // OverrideFulfillmentPaymentCoverage
+// { id, outstandingAtGrant: 8100, actorKind: 'user', active: true, … }
+```
+
+An override holds while the order owes no more than `outstandingAtGrant` (a refund after the grant
+ends it); a later grant supersedes an earlier one. Each grant is kept for good and writes a private
+entry on the order's history.
+
 ### Product feeds
 
 A feed turns the catalogue into the XML a channel hands Google, Meta, TikTok or Pinterest. The
@@ -1190,6 +1216,52 @@ const result = await admin.catalog.products.setCollections(productId, selectedId
   collection with such filters, until its membership job has run). Requires a platform
   release that serves `setProductCollections`.
 
+#### Saving a product page in one call
+
+```ts
+const { product, collections, warnings } = await admin.catalog.products.save(
+  {
+    id: productId,
+    languageCode: 'nl', // names, slugs, descriptions and text values are written in it
+    product: { name: 'Linnen hemd', brand: 'Acme' },
+    variants: [
+      { id: smallId, price: 5495, prices: [{ currencyCode: 'EUR', price: 5495 }], priceBasis: 'gross' },
+      { id: mediumId, facetValueIds: [blueId, linenId], gtin: '4006381333931' },
+    ],
+    collectionIds: selectedIds,
+    fromCollectionIds: loadedIds,
+    propertyValues: [{ propertyId: originId, value: [portugalItemId] }],
+  },
+  { idempotencyKey }
+);
+for (const warning of warnings) console.warn(warning.code, warning.message);
+```
+
+- **All or nothing.** One engine transaction, in this order: the variants, the hand-picked
+  collections (as `setCollections`), the property values (with each filterable product property's
+  label sync), the product. Every step's check runs before the first write, so a refusal of any
+  step leaves nothing written.
+- **Send the whole form if you like.** The input is a PATCH and the engine writes only what
+  differs from what it holds: a value sent back unchanged is not a write. It never counts as a
+  change of its field group (no "Managed by" badge moves, no `FIELD_GROUP_LOCKED`), and a product
+  the store's organization shares is not refused for a shared field sent back unchanged.
+- **Prices** state the store's basis (`priceBasis`), checked before sending, as for
+  `variants.update`; `price` and the default-currency entry of `prices` must agree. A currency
+  left out of `prices` keeps its stored price: the list removes nothing.
+- **Content labels** of content-item values are read from the content system first. When it does
+  not answer, the save still goes through, and `warnings` (`CONTENT_LABELS_NOT_SYNCED`) names the
+  properties whose filter values were saved without their titles; run
+  `catalog.syncContentFacets(propertyId)` on them later.
+- **Refusals**: `PRODUCT_SAVE_INPUT_INVALID` (400, `error.details` names each field),
+  `PRODUCT_COLLECTIONS_INPUT_INVALID`, `FEED_IDENTIFIER_INVALID`, `ENTITY_NOT_FOUND` (a variant of
+  another product included), `FORBIDDEN` (a step's own permission: `UpdateCatalog` or
+  `UpdateCollection` to change collections, `UpdateCatalog` for property values),
+  `SHARED_*_NOT_ALLOWED`, `MANAGED_BY_ORGANIZATION` (a CHANGED field the organization holds; the
+  store's own price, facet values, collections and property values pass), `FIELD_GROUP_LOCKED`,
+  `PRODUCT_COLLECTION_FILTER_INVALID`, `EXTERNAL_LINE_CARRIER_PROTECTED`.
+- `idempotencyKey`: a repeat answers the first call's result. Requires a platform release that
+  serves `saveProduct`: deploy the engine before shipping a head that calls it.
+
 #### Many products at once
 
 ```ts
@@ -2062,6 +2134,128 @@ An order this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`), the
 id. This is a root query of its own, never a field on an order list. It needs an engine that serves
 `orderStatus`; on an older one only this call fails.
 
+### Many orders at once
+
+```ts
+const handle = await admin.orders.bulk(
+  { action: 'MARK_PAID', orderIds: selectedIds }, // TRANSITION (with toState) | CANCEL (reason?) | DELETE | MARK_PAID
+  { idempotencyKey } // minted when omitted
+);
+const run = await handle.wait(); // or later: admin.orders.bulkRun(handle.runId)
+for (const item of run.items) {
+  if (item.status !== 'FAILED') continue;
+  // ORDER_ACTION_UNAVAILABLE: the order's own status did not offer it; reasonCode says why
+  console.log(item.id, item.code, item.reasonCode, item.message);
+  for (const payment of item.captured ?? []) console.log(payment.paymentId, payment.state, payment.code);
+}
+
+await admin.orders.delete(orderId); // one draft or cart, as the order page's Delete
+```
+
+- **A job, answered at once**, read with `ReadOrder`; `run.items` holds one outcome per order, in
+  the order you named them, and the run's `status` is the run's (a `SUCCEEDED` run can hold
+  `FAILED` orders).
+- **Each order as on its own page, and on its own.** Its status (`orders.status`) is asked first:
+  an action it does not offer, or a `toState` outside its own `nextStates`, is
+  `ORDER_ACTION_UNAVAILABLE` with `reasonCode` (`STATE`, `INVOICE_LOCKED`, `SHOPPER_CART`,
+  `HAS_RECORDS`, `UNITS_SHIPPED`, …), before anything is written. Then its door, under the door's
+  lock and with its own code (`ORDER_STATE_TRANSITION_ERROR`, `ORDER_CART_NOT_CANCELLABLE`,
+  `ORDER_INVOICE_LOCKED`, `ORDER_HAS_RECORDS`, `ORDER_NOT_DELETED`, …). Another store's order is
+  `ENTITY_NOT_FOUND`.
+- **`CANCEL` moves no money.** A paid order keeps its payment; refund it with `payments.refund`.
+- **`MARK_PAID` captures** every payment of the order that is `Authorized` when the run reaches it
+  (read by the engine, never your list), each as `settlePayment` and on its own; `captured` lists
+  them. A decline is the order's result (`SETTLE_PAYMENT_ERROR`), never retried.
+  `IDEMPOTENCY_OUTCOME_UNKNOWN` means the provider was asked and its answer was lost: reconcile
+  with the provider, never retry blind. An order with no authorized payment is
+  `NOTHING_TO_CAPTURE`: it is never marked paid without money. Use `TRANSITION` for any other
+  status; `PaymentSettled`, `Cancelled`, `Modifying` and `AddingItems` are refused there.
+- **One key, one run, one capture.** The same key with the same input answers the same run;
+  another input under it is `IDEMPOTENCY_CONFLICT`. Each order and each capture is keyed within
+  the run, so a run the platform processes again never asks a provider twice.
+- **No dry run**, and **at most `MAX_BULK_ORDERS` (50) per run** (`BULK_ACTION_INPUT_INVALID`,
+  refused before sending too). Needs `UpdateOrder` (`DeleteOrder` for `DELETE`).
+- `delete(orderId)` removes one draft or cart that holds no payment or stock movement; anything
+  else is kept (`ORDER_INVOICE_LOCKED`, `ORDER_HAS_RECORDS`, or `ORDER_NOT_DELETED`, a
+  `ConflictError` like every `*_NOT_DELETED`, with the
+  engine's reason).
+
+Both need an engine that serves `bulkOrderAction`; on an older one only these calls fail
+(`GRAPHQL_VALIDATION_FAILED`).
+
+### Returns
+
+```ts
+const rma = await admin.returns.get(returnId);              // with its status log; null when absent
+const returns = await admin.returns.forOrder(orderId);      // newest first
+const eligibility = await admin.returns.eligibility(orderId);
+
+const plan = await admin.returns.settlementOptions(returnId);
+// plan.settleable / plan.blockedBy → true / null, or false / 'RECEIPT_REQUIRED'
+// plan.refund     → { available: true, reasonCode: null, payments: [{ paymentId, method, refundable }] }
+// plan.creditNote → { available: true, ledger: 'RETAIL', reasonCode: null, invoiceNumber: '00042' }
+// plan.initialMethod → 'refund' | 'store_credit'; plan.defaultAmount → the approved line total
+```
+
+The single-return reads need `ReadOrderReturn`. `eligibility` reports the return window and never
+enforces it: an admin may return outside it, and the quantity caps always apply.
+
+`settlementOptions` is the plan for settling one return, so a head does not re-derive it. It needs
+`ReadOrderReturn` and `ReadOrder`, because it names the order's payments. A return this store does
+not hold is a `NotFoundError`.
+
+- `settleable` and `blockedBy`: `OUTCOME_UNKNOWN` (the refund it waits on was never confirmed;
+  record the provider's answer first, then it either completes or opens again), `ALREADY_SETTLED`,
+  `IN_PROGRESS` (a refund is on its way), `RECEIPT_REQUIRED` or `STATE`.
+- `refund`: the settled payments a refund may name, each with what the platform's refund position
+  says it can still give back. That figure holds back a refund whose outcome is unknown and money
+  moved to the customer's account. `NO_REFUNDABLE_PAYMENT` when there is none (net terms, among
+  others).
+- `creditNote`: `ledger: 'AR'` on a store with an accounts-receivable ledger, where the credit note
+  credits the customer's account; `RETAIL` elsewhere, where it credits the order's invoice and
+  moves no money. Unavailable reasons: `ISSUER_UNAVAILABLE`, `CURRENCY_MISMATCH` (AR),
+  `NO_CREDITABLE_INVOICE` (invoice).
+- `REFUND_ORPHAN_EXISTS` withholds the refund and an AR credit note while a refund of the invoiced
+  order stands that no credit note names: another payout could give the same money back twice.
+  The invoice credit note stays open.
+- `initialMethod` preselects the credit note when it was asked for or when no refund is possible,
+  as long as it is available.
+
+It is a plan: the write (`settleReturn`, not in the SDK yet) loads its own facts and judges again.
+Against an engine that does not serve `returnSettlementOptions` the call fails validation and
+nothing else does: deploy vendure-server before relying on it.
+
+### Deposit policy
+
+```ts
+const policy = await admin.orders.depositPolicy.get();
+// { enabled: false, minimum: 0, allowZeroDepositPark: false, showParkReasonToCustomer: false,
+//   autoCancelAfterDays: null, storefront: { enabled: false, methods: [], minimumPercent: 0 } }
+
+await admin.orders.depositPolicy.set({ ...policy, enabled: true, minimum: 2_500 }); // €25.00
+await admin.orders.depositPolicy.set({
+  ...policy,
+  enabled: true,
+  storefront: { enabled: true, methods: ['bank-transfer'], minimumPercent: 30 },
+});
+```
+
+Whether the **active** store takes deposits and parks orders (`orders.park`), and whether a shopper
+may pay a deposit at checkout. Off unless a merchant turns it on: a store that never set one, and a
+stored value the engine cannot read, answer the defaults above, because `get` reads the policy as
+the engine applies it. `minimum` is in minor units of the store's DEFAULT currency (an order in
+another currency is held to it converted at the checkout's rate); `autoCancelAfterDays` is saved
+but not yet honoured; `storefront` applies only while `enabled` is on too.
+
+`set` replaces the whole policy: read it, change what you mean to, send it back. Every field is
+required, only the schema's fields are stored, and a value outside the meta catalog's
+`order_deposit_policy` bounds is refused before any request with `DEPOSIT_POLICY_INVALID`
+(`ValidationError`, one `details[]` entry per failing field, such as `storefront.minimumPercent`).
+The engine does not validate the column, so this check is what keeps a malformed value from
+silently reading as "deposits off". An absent policy and one set to the defaults mean the same to
+the engine and the column is never backfilled: write it when a merchant changed it. Writing needs
+`UpdateChannel`.
+
 ### Payment providers
 
 Onboard the PSP account a store is paid through, place its card terminals, and ask whether it can
@@ -2114,6 +2308,23 @@ response carries a link that can be single-use, an idempotency store keeps a res
 and re-serves it, and retrying is safe anyway — a repeat replaces the pending attempt and answers
 with a fresh url and state, which is what a merchant who lost the first link needs.
 
+### Payment methods
+
+```ts
+const page = await admin.payments.methods.list();
+page.items;   // [{ id, code: 'bank-transfer', name: 'Bank transfer', enabled: true, handlerCode: 'manual-payment' }, …]
+
+for await (const method of await admin.payments.methods.list()) {
+  if (method.enabled) offer(method.code);       // the `method` payments.record takes
+}
+```
+
+The **active** store's payment methods, enabled or not, as staff choose one: `code` is what
+`payments.record` takes as `method` and what a deposit policy names in `storefront.methods`, and
+`handlerCode` says what kind of method it is. A page of 100 by default (at most 1,000, or
+`INVALID_PAGE_SIZE`), walked with `.next()` or `for await`. Needs `ReadSettings` or
+`ReadPaymentMethod`.
+
 ### Unapplied cash: an overpayment on the customer's account
 
 A customer who paid more than an order bills (a second transfer, an edit that lowered a paid
@@ -3239,6 +3450,89 @@ does not hold on the product, names one twice, repeats a SKU, or has a blank or
 `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422 — called in the workspace) and `ENTITY_NOT_FOUND` (404).
 Requires a platform release that serves `makeLocalCopy`.
 
+### Data pipeline set-ups (drafts)
+
+An import or export set-up is kept on the server while the merchant works through it, so it can be
+continued later, from another device, by any admin of the store with pipeline rights
+(`UpdateCatalog`). A draft lives **7 days after its last change**; after that it answers
+`PIPELINE_DRAFT_NOT_FOUND` and the platform deletes it, together with the connection it created and
+that connection's stored password, unless a pipeline or another draft uses the connection.
+
+```ts
+const drafts = admin.integrations.pipelines.drafts;
+
+let draft = await drafts.create({ direction: 'import' });          // step 'connector', the store's zone
+draft = await drafts.update(draft.id, { version: draft.version, connectorType: 'woocommerce' });
+draft = await drafts.update(draft.id, { version: draft.version, sourceUrl: 'https://shop.example.com' });
+
+// The ONE call that takes credentials: probed, then stored encrypted on the connection.
+draft = await drafts.connect(draft.id, {
+  version: draft.version,
+  credentials: { consumerKey, consumerSecret },
+});
+draft = await drafts.discover(draft.id, { version: draft.version });
+while (draft.discovery?.status === 'pending' || draft.discovery?.status === 'running') {
+  await sleep(2_000);
+  draft = await drafts.get(draft.id);
+}
+draft.dependencyWarnings; // [{ entityType: 'orders', missing: ['shipping_methods'] }]
+
+draft = await drafts.update(draft.id, { version: draft.version, step: 'configure' }); // gets its name
+const { pipeline, run, runError } = await drafts.commit(
+  draft.id,
+  { version: draft.version, startRun: true },
+  { idempotencyKey: crypto.randomUUID() }
+);
+```
+
+- **A draft never holds a secret.** Credentials go only to `connect`; a `credentials` key anywhere
+  else is refused. A set-up resumed before its connection exists asks for them again.
+- **Every change names `version`** and answers the next one. A change made on an older version is a
+  `ConflictError` (`PIPELINE_DRAFT_CONFLICT`, 409) that changed nothing: read the draft again.
+- `connectorType` starts the connection over (even the same connector), `connect` and
+  `useConnection` let go of the previous connection and its discovery, and what a draft lets go of
+  is deleted when a draft created it and nothing else uses it. `useConnection` never deletes a
+  connection that existed before any draft; one another draft created and still holds becomes
+  this draft's too (`connection.createdByDraft`), and the last draft to let go of it unused
+  deletes it.
+- The default name and the schedule's zone are the **store's** (`storeTimeZone`), DST-safe.
+- `dependencies` and `importDependencies()` come from the import writers themselves;
+  `dependencyWarnings` names each enabled entity type whose discovered dependencies are switched
+  off. The words are yours.
+- What a step still needs is a `BusinessRuleError` (`PIPELINE_DRAFT_INCOMPLETE`, 422) with one
+  `details[]` entry per field; a refused change is a `ValidationError` (`PIPELINE_DRAFT_INVALID`).
+- A commit with `startRun` whose run does not start keeps the pipeline and answers `runError`.
+- `triggerFilter`, `siteAnalysis`, `publicCredentials` and a schema map's `sourceSchema`,
+  `targetSchema` and `subCounts` are stored data and keep their keys exactly
+  (`PIPELINE_DRAFT_PRESERVE_KEYS`).
+- Discovery progress: `discovery.status` is read from the draft; the per-phase progress messages
+  are only on the discovery's event stream.
+
+### Searching the store
+
+One call finds products, orders, customers and content items matching a term: each type's best
+matches, **most relevant first**, every one already loaded in the store you act on.
+
+```ts
+const found = await admin.search.entities('W4-00087');
+found.orders[0]; // { id, code, state, orderPlacedAt, totalWithTax, currencyCode, lifecycleStatus }
+
+const some = await admin.search.entities('serum', { types: ['PRODUCTS', 'CONTENT'], take: 3 });
+for (const skip of some.skipped) console.log(`${skip.type} not searched: ${skip.reason}`);
+```
+
+- **A type you may not read is skipped and named**, never a refusal: its list is empty and
+  `skipped` says why. `PERMISSION` (no `ReadCatalog`/`ReadProduct`, `ReadOrder` or `ReadCustomer`
+  in the store), `CUSTOMER_DATA_NOT_GRANTED` (an app reading customer data below `full` is never
+  searched for orders or customers, which match customers' names and emails), `UNAVAILABLE` (the
+  search service, or the content system, did not answer).
+- **Content may be missing when the content system is down**: the other types still answer.
+  Content is published items, plus drafts and archived items for a `ReadCmsContent` holder.
+- A match the store no longer holds is left out, so a list can be shorter than `take`.
+- `take` is per type, 1 to 10 (`SEARCH_ENTITIES_MAX_TAKE`), 5 when omitted. A term under 2
+  characters (`SEARCH_ENTITIES_MIN_TERM_LENGTH`) or over 500 once trimmed, a `take` out of range or
+  an empty `types` list is refused with `SEARCH_INPUT_INVALID` (`ValidationError`).
+
 ### Errors
 
 One hierarchy, all re-exported from this package so you need no direct dependency on

package/dist/catalog/products.d.ts

@@ -2,7 +2,8 @@ import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { JobHandle } from '../jobs/index.js';
 import type { Call, ListOptions } from '../types.js';
 import { type ProductBulkInput, type ProductBulkRun } from './products-bulk.js';
-import { type AssetRef, type Availability, type AvailabilityInput, type CatalogueOwnership, type FacetValueRef, type LanguageCode, type ProductAvailabilityState, type TranslationInput } from './types.js';
+import { type AssetRef, type Availability, type AvailabilityInput, type CatalogueOwnership, type FacetValueRef, type LanguageCode, type PriceBasis, type ProductAvailabilityState, type TranslationInput, type VariantAvailabilityState } from './types.js';
+import { type ParcelPacking, type VariantBackorderPolicy, type VariantPriceInput } from './variants.js';
 export interface ProductOptionRef {
     id: string;
     code: string;
@@ -67,7 +68,15 @@ export interface CreateProductInput extends AvailabilityInput<ProductAvailabilit
     assetIds?: string[];
     /** Replaces the product's facet values on update — send the whole set. */
     facetValueIds?: string[];
+    /**
+     * The brand feeds name; at most 70 characters when new or changed (`FEED_IDENTIFIER_INVALID`
+     * otherwise). Null or blank clears it. A stored value sent back unchanged is never judged.
+     */
+    brand?: string | null;
+    condition?: ProductCondition;
 }
+/** A product's condition, as feeds state it. */
+export type ProductCondition = 'new' | 'refurbished' | 'used';
 /** A PATCH: omitted fields are left alone. */
 export interface UpdateProductInput extends Partial<CreateProductInput> {
     id: string;
@@ -195,6 +204,109 @@ export interface ProductCollectionsResult {
         reason: ProductCollectionNotRemovedReason | (string & {});
     }>;
 }
+/** The product's own fields in a {@link ProductsModule.save}; a PATCH. */
+export interface SaveProductFieldsInput extends AvailabilityInput<ProductAvailabilityState> {
+    /** In the save's `languageCode`. */
+    name?: string;
+    slug?: string;
+    description?: string;
+    enabled?: boolean;
+    /** Null: no featured image. */
+    featuredAssetId?: string | null;
+    /** The product's images, in display order; replaces the list. */
+    assetIds?: string[];
+    /** At most 70 characters when new or changed; null or blank clears it. */
+    brand?: string | null;
+    condition?: ProductCondition;
+}
+/**
+ * One variant in a {@link ProductsModule.save}; a PATCH. A price (`price` or `prices`) travels
+ * with `priceBasis`, the store's basis, exactly as for `catalog.variants.update`.
+ */
+export interface SaveProductVariantInput extends AvailabilityInput<VariantAvailabilityState> {
+    id: string;
+    /** In the save's `languageCode`; trimmed. */
+    name?: string;
+    sku?: string;
+    enabled?: boolean;
+    /** Integer minor units of the store's default currency. */
+    price?: number;
+    /**
+     * The price in each named currency. A currency left out keeps its stored price (the list
+     * removes nothing), and one equal to what is stored is no change. Its default-currency entry
+     * must equal `price` when both are sent.
+     */
+    prices?: VariantPriceInput[];
+    priceBasis?: PriceBasis;
+    taxCategoryId?: string;
+    /** Compared as a set. */
+    facetValueIds?: string[];
+    /** Null: no featured image. */
+    featuredAssetId?: string | null;
+    assetIds?: string[];
+    minOrderQuantity?: number | null;
+    salesUnit?: number | null;
+    /** Integer minor units of the store's default currency. */
+    cost?: number | null;
+    packageWeightGrams?: number | null;
+    packageLengthCm?: number | null;
+    packageWidthCm?: number | null;
+    packageHeightCm?: number | null;
+    /** 1 to 10,000; null: the store's items per parcel. */
+    parcelCapacity?: number | null;
+    /** Null: `shared`. */
+    parcelPacking?: ParcelPacking | null;
+    /** Null: `inherit`. */
+    backorderPolicy?: VariantBackorderPolicy | null;
+    backorderLimit?: number | null;
+    /** 8, 12, 13 or 14 digits when new or changed; null or blank clears it. */
+    gtin?: string | null;
+    mpn?: string | null;
+}
+/** One property value in a {@link ProductsModule.save}. */
+export interface SaveProductPropertyValueInput {
+    propertyId: string;
+    /** A translatable property's language; the save's `languageCode` when left out. */
+    languageCode?: LanguageCode;
+    /** Null, `''` or `[]` clears it; a content-item or product property takes a list of ids. */
+    value: unknown;
+}
+/** A product page's whole change, for {@link ProductsModule.save}. */
+export interface SaveProductInput {
+    id: string;
+    /** The editing language: names, slugs, descriptions and text values are written in it. */
+    languageCode: LanguageCode;
+    product?: SaveProductFieldsInput;
+    variants?: SaveProductVariantInput[];
+    /** The collections the product is in by hand: the whole wanted list. */
+    collectionIds?: string[];
+    /**
+     * The collections the caller last read the product in: only the difference is applied, so a
+     * change someone else made meanwhile stands (as `setCollections`' `from`). Needs `collectionIds`.
+     */
+    fromCollectionIds?: string[];
+    /** An absent property keeps its value. */
+    propertyValues?: SaveProductPropertyValueInput[];
+}
+/**
+ * Something a save did not do although everything it wrote is saved. A string on the wire: a
+ * newer engine may add a code.
+ * - `CONTENT_LABELS_NOT_SYNCED`: the content system did not answer, so the filter values of the
+ *   properties in `propertyIds` were saved without their titles; run
+ *   `catalog.syncContentFacets(propertyId)` on them once it is back.
+ */
+export interface SaveProductWarning {
+    code: 'CONTENT_LABELS_NOT_SYNCED' | (string & {});
+    message: string;
+    propertyIds: string[];
+}
+export interface SaveProductResult {
+    /** The product as saved. */
+    product: Product;
+    /** What the collection step did; null when the save changed no collection. */
+    collections: ProductCollectionsResult | null;
+    warnings: SaveProductWarning[];
+}
 /**
  * Product-level catalog writes. Reading needs `ReadCatalog` (or `ReadProduct`),
  * creating `CreateCatalog`, updating `UpdateCatalog`, deleting `DeleteCatalog`.
@@ -403,6 +515,54 @@ export interface ProductsModule {
     setCollections(productId: string, collectionIds: readonly string[], options?: Call & {
         from?: readonly string[];
     }): Promise<ProductCollectionsResult>;
+    /**
+     * Save a product page's whole change in ONE engine transaction: all of it, or none of it
+     * (headless spec §7 `products.save`). In this order: the variants, the hand-picked collections
+     * (as {@link setCollections}), the property values (and the filter-label sync of each
+     * filterable product property), the product. Every step's check runs before the first write.
+     *
+     * A PATCH with an echo rule: only what the input names is compared, and only what differs from
+     * what the store holds is written. A head may send the whole form: an unchanged value is not a
+     * write, so it never records a change of its field group, and a product the store's
+     * organization shares is not refused for a shared field sent back unchanged.
+     *
+     * Labels of content-item values are read from the content system before the transaction. When
+     * it does not answer, the save still goes through and `warnings` names the properties whose
+     * filter values were saved without their titles.
+     *
+     * Needs `UpdateCatalog` or `UpdateProduct`, plus `UpdateCatalog` or `UpdateCollection` when it
+     * changes collections and `UpdateCatalog` when it changes property values. `idempotencyKey`: a
+     * repeat answers the first call's result. Platform releases before this method do not have the
+     * mutation and refuse it as `ValidationError` `GRAPHQL_VALIDATION_FAILED` (400): deploy the
+     * engine first.
+     *
+     * Refusals (nothing is written), GraphQL errors mapped by `core`:
+     * - `PRICE_BASIS_REQUIRED` / `PRICE_BASIS_MISMATCH` / `INVALID_PRICE` → `ValidationError`
+     *   (400): a variant price without the store's basis; refused before sending.
+     * - `PRODUCT_SAVE_INPUT_INVALID` → `ValidationError` (400): the input names nothing, names a
+     *   variant, currency or property value twice, uses a language the store does not offer, gives
+     *   a value outside its field's range, or `price` and the default-currency entry of `prices`
+     *   differ. `error.details` names each (`field` is a pointer into the call).
+     * - `PRODUCT_COLLECTIONS_INPUT_INVALID` → `ValidationError` (400): a collection list names one
+     *   twice, or more than {@link MAX_PRODUCT_COLLECTION_IDS}; refused before sending too.
+     * - `FEED_IDENTIFIER_INVALID` → `ValidationError` (400): a new or changed brand over 70
+     *   characters, or a GTIN of another shape.
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): a product, variant (of another product
+     *   included), collection or property this store does not hold.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): a step's permission above is missing.
+     * - `SHARED_PRODUCT_NOT_ALLOWED`, `SHARED_PRODUCT_VARIANT_NOT_ALLOWED`,
+     *   `SHARED_COLLECTION_NOT_ALLOWED` → `PermissionDeniedError` (403): a row another store also
+     *   holds, which you cannot change there.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a CHANGED field of a product, variant,
+     *   collection or property value the store's organization holds. The store's own price, its own
+     *   facet values, its own collections and its own property values pass.
+     * - `FIELD_GROUP_LOCKED` → `BusinessRuleError` (422): a field group an app or API token owns.
+     * - `PRODUCT_COLLECTION_FILTER_INVALID` → `ValidationError` (400): a collection whose
+     *   hand-picked list cannot be read.
+     * - `EXTERNAL_LINE_CARRIER_PROTECTED` → `BusinessRuleError` (422): the platform's carrier.
+     * - `INVALID_TAX_CATEGORY_FOR_CLASS` → `ValidationError` (400).
+     */
+    save(input: SaveProductInput, options?: Call): Promise<SaveProductResult>;
     /**
      * Enable, disable, delete or clone up to `MAX_BULK_PRODUCTS` (50) products of the store in ONE
      * call (headless spec §7 `products.bulkClone`; §6.11).
@@ -472,6 +632,7 @@ export declare const SET_ORGANIZATION_PRODUCT_AVAILABILITY_MUTATION = "\n  mutat
 export declare const ORGANIZATION_PRODUCT_AVAILABILITY_QUERY = "\n  query CatalogOrganizationProductAvailability($productIds: [ID!]!, $channelIds: [ID!]!) {\n    organizationProductAvailability(productIds: $productIds, channelIds: $channelIds) {\n      productId\n      channelId\n      state\n      localCopyId\n    }\n  }\n";
 export declare const MAKE_LOCAL_COPY_MUTATION = "\n  mutation CatalogMakeLocalCopy($productId: ID!, $skus: [LocalCopySkuInput!]) {\n    makeLocalCopy(productId: $productId, skus: $skus) {\n      product { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      originalProductId\n      original\n      droppedOrganizationPropertyCount\n    }\n  }\n";
 export declare const SET_PRODUCT_COLLECTIONS_MUTATION = "\n  mutation CatalogSetProductCollections(\n    $productId: ID!\n    $collectionIds: [ID!]!\n    $fromCollectionIds: [ID!]\n  ) {\n    setProductCollections(\n      productId: $productId\n      collectionIds: $collectionIds\n      fromCollectionIds: $fromCollectionIds\n    ) {\n      added\n      removed\n      unchanged\n      notRemoved {\n        collectionId\n        reason\n      }\n    }\n  }\n";
+export declare const SAVE_PRODUCT_MUTATION = "\n  mutation CatalogSaveProduct($input: SaveProductInput!, $idempotencyKey: String) {\n    saveProduct(input: $input, idempotencyKey: $idempotencyKey) {\n      product { \n  id\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n  createdAt\n  updatedAt\n  languageCode\n  name\n  slug\n  description\n  enabled\n  featuredAsset { \n  id\n  name\n  preview\n  source\n }\n  assets { \n  id\n  name\n  preview\n  source\n }\n  facetValues { \n  id\n  code\n  name\n  facet {\n    id\n    code\n    name\n  }\n }\n  optionGroups {\n    id\n    code\n    name\n    options {\n      id\n      code\n      name\n    }\n  }\n  translations {\n    id\n    languageCode\n    name\n    slug\n    description\n  }\n  excludedFromStore\n  variantList(options: { take: 1 }) {\n    totalItems\n  }\n  customFields {\n    availabilityState\n    availableFrom\n    preorderLimit\n  }\n }\n      collections {\n        added\n        removed\n        unchanged\n        notRemoved {\n          collectionId\n          reason\n        }\n      }\n      warnings {\n        code\n        message\n        propertyIds\n      }\n    }\n  }\n";
 /** The product as the Admin API answers it, before `toProduct`. */
 export interface WireProduct extends Omit<Product, keyof Availability<string> | 'variantCount'> {
     variantList: {

package/dist/catalog/products.js

@@ -1,6 +1,7 @@
 import { ValidationError } from '@sixtyninecommerce/core';
 import { bulkProducts, readProductBulkRun, } from './products-bulk.js';
 import { ASSET_REF_FIELDS, assertDeleted, availabilityCustomFields, CATALOGUE_OWNERSHIP_FIELDS, DELETION_FIELDS, FACET_VALUE_REF_FIELDS, fieldOf, unwrapResult, vendureListPage, } from './types.js';
+import { assertPricesStateBasis, } from './variants.js';
 /** The engine's bound on one `exclude` or `include` call (`STORE_EXCLUSION_BATCH_LIMIT`). */
 export const MAX_STORE_EXCLUSION_PRODUCTS = 500;
 /**
@@ -168,6 +169,27 @@ export const SET_PRODUCT_COLLECTIONS_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const SAVE_PRODUCT_MUTATION = /* GraphQL */ `
+  mutation CatalogSaveProduct($input: SaveProductInput!, $idempotencyKey: String) {
+    saveProduct(input: $input, idempotencyKey: $idempotencyKey) {
+      product { ${PRODUCT_FIELDS} }
+      collections {
+        added
+        removed
+        unchanged
+        notRemoved {
+          collectionId
+          reason
+        }
+      }
+      warnings {
+        code
+        message
+        propertyIds
+      }
+    }
+  }
+`;
 /**
  * Lift the availability custom fields to first-class fields. A server older
  * than the pre-order engine has no such fields and would refuse the document
@@ -184,12 +206,16 @@ export function toProduct(wire) {
     };
 }
 function toWireInput(input) {
-    const { availabilityState, availableFrom, preorderLimit, ...rest } = input;
+    const { availabilityState, availableFrom, preorderLimit, brand, condition, ...rest } = input;
     const customFields = availabilityCustomFields({
         availabilityState,
         availableFrom,
         preorderLimit,
     });
+    if (brand !== undefined)
+        customFields.brand = brand;
+    if (condition !== undefined)
+        customFields.condition = condition;
     return Object.keys(customFields).length > 0 ? { ...rest, customFields } : rest;
 }
 export function productFilter(filter) {
@@ -355,6 +381,15 @@ export function createProductsModule(transport) {
                 fromCollectionIds: from === undefined ? null : [...from],
             }, call);
         },
+        async save(input, options) {
+            assertCollectionLists({
+                collectionIds: input.collectionIds,
+                fromCollectionIds: input.fromCollectionIds,
+            });
+            await assertPricesStateBasis(transport, input.variants ?? [], options);
+            const result = await fieldOf(transport, SAVE_PRODUCT_MUTATION, 'saveProduct', { input: toWireSaveInput(input), idempotencyKey: options?.idempotencyKey ?? null }, options);
+            return { ...result, product: toProduct(result.product) };
+        },
         bulk(input, options) {
             return bulkProducts(transport, input, options);
         },
@@ -363,3 +398,61 @@ export function createProductsModule(transport) {
         },
     };
 }
+/** The variant fields a save writes as custom fields on the wire. */
+const SAVE_VARIANT_CUSTOM_FIELDS = [
+    'minOrderQuantity',
+    'salesUnit',
+    'cost',
+    'packageWeightGrams',
+    'packageLengthCm',
+    'packageWidthCm',
+    'packageHeightCm',
+    'parcelCapacity',
+    'parcelPacking',
+    'backorderPolicy',
+    'backorderLimit',
+    'gtin',
+    'mpn',
+];
+/** The SDK's flat save as the engine's `SaveProductInput`: custom fields nested, no basis. */
+function toWireSaveInput(input) {
+    const wire = { id: input.id, languageCode: input.languageCode };
+    if (input.product) {
+        const { availabilityState, availableFrom, preorderLimit, brand, condition, ...rest } = input.product;
+        const customFields = availabilityCustomFields({
+            availabilityState,
+            availableFrom,
+            preorderLimit,
+        });
+        if (brand !== undefined)
+            customFields.brand = brand;
+        if (condition !== undefined)
+            customFields.condition = condition;
+        wire.product = Object.keys(customFields).length > 0 ? { ...rest, customFields } : rest;
+    }
+    if (input.variants) {
+        wire.variants = input.variants.map((variant) => {
+            const { availabilityState, availableFrom, preorderLimit, priceBasis, ...rest } = variant;
+            void priceBasis;
+            const customFields = availabilityCustomFields({
+                availabilityState,
+                availableFrom,
+                preorderLimit,
+            });
+            const out = { ...rest };
+            for (const key of SAVE_VARIANT_CUSTOM_FIELDS) {
+                if (key in out) {
+                    if (out[key] !== undefined)
+                        customFields[key] = out[key];
+                    delete out[key];
+                }
+            }
+            return Object.keys(customFields).length > 0 ? { ...out, customFields } : out;
+        });
+    }
+    for (const key of ['collectionIds', 'fromCollectionIds', 'propertyValues']) {
+        if (input[key] !== undefined)
+            wire[key] = input[key];
+    }
+    return wire;
+}