@revenexx/node 0.1.1 → 0.2.0

package/dist/services/products.d.mts

@@ -1,8 +1,11 @@
 import { Client } from '../client.mjs';
 import { Models } from '../models.mjs';
-import { Kind } from '../enums/kind.mjs';
+import { ProductsListKind } from '../enums/products-list-kind.mjs';
 import { ProductsKind } from '../enums/products-kind.mjs';
 import '../query.mjs';
+import '../enums/accept-line-decision.mjs';
+import '../enums/accept-result-origin.mjs';
+import '../enums/accept-result-status.mjs';
 import '../enums/address-type-row-tone.mjs';
 import '../enums/address-type-row-create-request-tone.mjs';
 import '../enums/address-type-row-update-request-tone.mjs';
@@ -16,12 +19,23 @@ import '../enums/approval-rule-update-request-approver-type.mjs';
 import '../enums/approval-rule-update-request-condition.mjs';
 import '../enums/approval-rule-update-request-effect.mjs';
 import '../enums/assets-source.mjs';
+import '../enums/assignment-role-tone.mjs';
+import '../enums/assignment-role-create-request-tone.mjs';
+import '../enums/assignment-role-update-request-tone.mjs';
+import '../enums/attach-request-direction.mjs';
+import '../enums/attach-request-visibility.mjs';
 import '../enums/attribute-value-bucket.mjs';
 import '../enums/auth-mail-source.mjs';
+import '../enums/auth-mfa-challenge-request-factor.mjs';
 import '../enums/recovery-mail-source.mjs';
 import '../enums/registration-status.mjs';
+import '../enums/availability-state-tone.mjs';
+import '../enums/banner-draft-layout.mjs';
+import '../enums/banner-draft-update-request-layout.mjs';
 import '../enums/budget-change-reason.mjs';
 import '../enums/budget-movement-result-status.mjs';
+import '../enums/budget-release-scope.mjs';
+import '../enums/budget-release-status.mjs';
 import '../enums/cart-status.mjs';
 import '../enums/cart-merge-strategy.mjs';
 import '../enums/cart-price-snapshot-mode.mjs';
@@ -49,18 +63,44 @@ import '../enums/channel-vocabulary-tone.mjs';
 import '../enums/channel-vocabulary-name.mjs';
 import '../enums/channel-vocabulary-source.mjs';
 import '../enums/channel-vocabulary-ref-name.mjs';
+import '../enums/consent-record-action.mjs';
+import '../enums/consent-record-surface.mjs';
+import '../enums/consent-record-create-request-action.mjs';
+import '../enums/consent-record-create-request-surface.mjs';
+import '../enums/consent-vocabulary-source.mjs';
+import '../enums/contact-order-approval-mode.mjs';
 import '../enums/contact-registration-status.mjs';
 import '../enums/contact-status.mjs';
 import '../enums/contact-activity-kind.mjs';
+import '../enums/order-approval-mode.mjs';
 import '../enums/contact-create-request-registration-status.mjs';
 import '../enums/contact-event-kind-tone.mjs';
 import '../enums/contact-event-kind-create-request-tone.mjs';
 import '../enums/contact-event-kind-update-request-tone.mjs';
-import '../enums/contact-update-request-registration-status.mjs';
+import '../enums/contact-point-kind-tone.mjs';
+import '../enums/contact-point-kind-create-request-tone.mjs';
+import '../enums/contact-point-kind-update-request-tone.mjs';
+import '../enums/cookie-kind.mjs';
+import '../enums/cookie-create-request-kind.mjs';
+import '../enums/cookie-update-request-kind.mjs';
 import '../enums/cost-center-budget-type.mjs';
+import '../enums/cost-center-create-request-budget-type.mjs';
 import '../enums/cost-center-restriction-type.mjs';
 import '../enums/cost-center-restriction-create-request-type.mjs';
 import '../enums/cost-center-restriction-update-request-type.mjs';
+import '../enums/cost-center-update-request-budget-type.mjs';
+import '../enums/cost-centers-vocabulary-tone.mjs';
+import '../enums/cost-centers-vocabulary-name.mjs';
+import '../enums/cost-centers-vocabulary-source.mjs';
+import '../enums/cost-centers-vocabulary-summary-name.mjs';
+import '../enums/direct-order-status.mjs';
+import '../enums/document-source.mjs';
+import '../enums/document-visibility.mjs';
+import '../enums/document-kind-tone.mjs';
+import '../enums/document-vocabulary-default-tone.mjs';
+import '../enums/document-vocabulary-name.mjs';
+import '../enums/document-vocabulary-source.mjs';
+import '../enums/document-vocabulary-tone.mjs';
 import '../enums/payment-fee-type.mjs';
 import '../enums/payment-method-kind.mjs';
 import '../enums/form-status.mjs';
@@ -70,6 +110,7 @@ import '../enums/form-submission-prune-request-status.mjs';
 import '../enums/forms-vocabulary-tone.mjs';
 import '../enums/forms-vocabulary-name.mjs';
 import '../enums/forms-vocabulary-summary-name.mjs';
+import '../enums/inventory-receive-warning-code.mjs';
 import '../enums/inventory-vocabulary-default-tone.mjs';
 import '../enums/inventory-vocabulary-source.mjs';
 import '../enums/cart-io-apply-mode.mjs';
@@ -77,6 +118,7 @@ import '../enums/cart-io-direction.mjs';
 import '../enums/cart-io-entity.mjs';
 import '../enums/io-profile-resource-apply-mode.mjs';
 import '../enums/io-profile-resource-direction.mjs';
+import '../enums/inventory-unorderable-reason.mjs';
 import '../enums/lifecycle-stage-tone.mjs';
 import '../enums/lifecycle-stage-create-request-tone.mjs';
 import '../enums/lifecycle-stage-update-request-tone.mjs';
@@ -93,28 +135,40 @@ import '../enums/markets-vocabulary-tone.mjs';
 import '../enums/markets-vocabulary-name.mjs';
 import '../enums/markets-vocabulary-source.mjs';
 import '../enums/markets-vocabulary-summary-name.mjs';
+import '../enums/note-request-visibility.mjs';
 import '../enums/order-fulfillment-status.mjs';
 import '../enums/order-payment-status.mjs';
 import '../enums/order-status.mjs';
 import '../enums/order-cancellation-scope.mjs';
 import '../enums/order-comment-visibility.mjs';
+import '../enums/order-discount-target.mjs';
+import '../enums/order-discount-effect-kind.mjs';
+import '../enums/order-discount-placement.mjs';
+import '../enums/order-discount-source.mjs';
+import '../enums/order-discount-value-type.mjs';
 import '../enums/order-item-type.mjs';
 import '../enums/order-list-kind-tone.mjs';
 import '../enums/order-list-kind-row-tone.mjs';
+import '../enums/order-list-skip-reason.mjs';
 import '../enums/order-list-cart-mode.mjs';
 import '../enums/order-list-vocabulary-default-tone.mjs';
 import '../enums/order-list-vocabulary-name.mjs';
 import '../enums/order-list-vocabulary-source.mjs';
 import '../enums/order-list-vocabulary-tone.mjs';
+import '../enums/order-return-refund-mode.mjs';
 import '../enums/order-return-status.mjs';
 import '../enums/order-return-settlement.mjs';
-import '../enums/order-return-refusal.mjs';
 import '../enums/order-vocabulary-tone.mjs';
+import '../enums/order-return-refusal.mjs';
 import '../enums/order-vocabulary-name.mjs';
 import '../enums/order-vocabulary-source.mjs';
 import '../enums/order-vocabulary-summary-name.mjs';
 import '../enums/order-resolution-stage.mjs';
+import '../enums/organization-credit-limit-mode.mjs';
+import '../enums/organization-shipping-advice.mjs';
 import '../enums/organization-status.mjs';
+import '../enums/credit-limit-mode.mjs';
+import '../enums/shipping-advice.mjs';
 import '../enums/page-status.mjs';
 import '../enums/pages-vocabulary-app.mjs';
 import '../enums/pages-vocabulary-tone.mjs';
@@ -136,6 +190,7 @@ import '../enums/price-entries-adjust-response-rounding-mode.mjs';
 import '../enums/price-entries-bulk-mode.mjs';
 import '../enums/price-rounding-mode.mjs';
 import '../enums/price-entry-type.mjs';
+import '../enums/price-line-price-reason.mjs';
 import '../enums/price-list-status.mjs';
 import '../enums/price-list-tax-basis.mjs';
 import '../enums/price-currency-source.mjs';
@@ -147,21 +202,85 @@ import '../enums/price-vocabulary-tone.mjs';
 import '../enums/price-vocabulary-name.mjs';
 import '../enums/price-vocabulary-source.mjs';
 import '../enums/price-vocabulary-ref-name.mjs';
+import '../enums/procurement-vocabulary-default-tone.mjs';
+import '../enums/procurement-vocabulary-name.mjs';
+import '../enums/procurement-vocabulary-source.mjs';
+import '../enums/procurement-vocabulary-summary-name.mjs';
+import '../enums/procurement-vocabulary-value-tone.mjs';
 import '../enums/product-categories-source.mjs';
 import '../enums/product-grid-column-source.mjs';
 import '../enums/product-label-source.mjs';
 import '../enums/product-label-attribute-source.mjs';
+import '../enums/promotion-condition-match.mjs';
+import '../enums/promotion-reach.mjs';
+import '../enums/promotion-recurrence-kind.mjs';
+import '../enums/promotion-return-behaviour.mjs';
+import '../enums/promotion-status.mjs';
+import '../enums/promotion-bundle-allocation.mjs';
+import '../enums/promotion-bundle-patch-allocation.mjs';
+import '../enums/promotion-bundle-write-allocation.mjs';
+import '../enums/promotion-condition-kind.mjs';
+import '../enums/promotion-condition-match-mode.mjs';
+import '../enums/promotion-condition-patch-kind.mjs';
+import '../enums/promotion-condition-patch-match-mode.mjs';
+import '../enums/promotion-condition-write-kind.mjs';
+import '../enums/promotion-condition-write-match-mode.mjs';
+import '../enums/promotion-effect-kind.mjs';
+import '../enums/promotion-effect-target-scope.mjs';
+import '../enums/promotion-effect-unit-choice.mjs';
+import '../enums/promotion-effect-value-type.mjs';
+import '../enums/promotion-effect-patch-kind.mjs';
+import '../enums/promotion-effect-patch-target-scope.mjs';
+import '../enums/promotion-effect-patch-unit-choice.mjs';
+import '../enums/promotion-effect-patch-value-type.mjs';
+import '../enums/promotion-effect-write-kind.mjs';
+import '../enums/promotion-effect-write-target-scope.mjs';
+import '../enums/promotion-effect-write-unit-choice.mjs';
+import '../enums/promotion-effect-write-value-type.mjs';
+import '../enums/promotion-patch-condition-match.mjs';
+import '../enums/promotion-patch-reach.mjs';
+import '../enums/promotion-patch-recurrence-kind.mjs';
+import '../enums/promotion-patch-return-behaviour.mjs';
+import '../enums/promotion-patch-status.mjs';
+import '../enums/promotion-release-request-reason.mjs';
+import '../enums/promotion-write-condition-match.mjs';
+import '../enums/promotion-write-reach.mjs';
+import '../enums/promotion-write-recurrence-kind.mjs';
+import '../enums/promotion-write-return-behaviour.mjs';
+import '../enums/promotion-write-status.mjs';
+import '../enums/punchout-entry-probe-result-entry-probe-status.mjs';
+import '../enums/punchout-entry-test-result-protocol.mjs';
+import '../enums/punchout-field-mapping-import-request-protocol.mjs';
+import '../enums/punchout-return-preview-protocol.mjs';
 import '../enums/purchase-request-status.mjs';
 import '../enums/purchase-request-event-name.mjs';
 import '../enums/purchase-request-item-type.mjs';
 import '../enums/purchase-request-item-create-request-type.mjs';
 import '../enums/purchase-request-item-update-request-type.mjs';
+import '../enums/purpose-legal-basis.mjs';
+import '../enums/purpose-create-request-legal-basis.mjs';
+import '../enums/purpose-update-request-legal-basis.mjs';
+import '../enums/quote-origin.mjs';
+import '../enums/quote-status.mjs';
+import '../enums/quote-attachment-direction.mjs';
+import '../enums/quote-attachment-visibility.mjs';
+import '../enums/quote-detail-origin.mjs';
+import '../enums/quote-detail-status.mjs';
+import '../enums/quote-event-visibility.mjs';
+import '../enums/quote-item-decision.mjs';
+import '../enums/quote-item-price-reason.mjs';
+import '../enums/quote-line-input-price-reason.mjs';
+import '../enums/redemption-state.mjs';
 import '../enums/reorder-point-source.mjs';
 import '../enums/reservation-status.mjs';
 import '../enums/price-on-request-reason.mjs';
 import '../enums/price-tax-basis.mjs';
 import '../enums/price-tax-basis-source.mjs';
 import '../enums/role-catalog-response-source.mjs';
+import '../enums/sales-rep-vocabulary-default-tone.mjs';
+import '../enums/sales-rep-vocabulary-source.mjs';
+import '../enums/seed-request-mode.mjs';
+import '../enums/seed-result-mode.mjs';
 import '../enums/segment-rule-match.mjs';
 import '../enums/segment-member-source.mjs';
 import '../enums/segment-rule-operator.mjs';
@@ -191,14 +310,35 @@ import '../enums/shipping-vocabulary-tone.mjs';
 import '../enums/shipping-weight-unit-create-request-tone.mjs';
 import '../enums/shipping-weight-unit-row-tone.mjs';
 import '../enums/shipping-weight-unit-update-request-tone.mjs';
+import '../enums/stacking-group-mode.mjs';
+import '../enums/stacking-group-patch-mode.mjs';
+import '../enums/stacking-group-write-mode.mjs';
 import '../enums/stock-movement-type.mjs';
 import '../enums/store-asset-request-visibility.mjs';
 import '../enums/submit-item-type.mjs';
 import '../enums/submit-result-outcome.mjs';
+import '../enums/tag-manager-container-check-reason.mjs';
+import '../enums/tag-manager-marketing-tag-kind.mjs';
+import '../enums/tag-manager-marketing-tag-load.mjs';
+import '../enums/tag-manager-marketing-tag-input-kind.mjs';
+import '../enums/tag-manager-marketing-tag-input-load.mjs';
+import '../enums/tag-manager-trigger-kind.mjs';
+import '../enums/tag-manager-trigger-input-kind.mjs';
+import '../enums/tag-manager-variable-kind.mjs';
+import '../enums/tag-manager-variable-input-kind.mjs';
 import '../enums/validation-failed-response-status.mjs';
+import '../enums/vendor-legal-basis-override.mjs';
+import '../enums/vendor-create-request-legal-basis-override.mjs';
+import '../enums/vendor-update-request-legal-basis-override.mjs';
 import '../enums/vocabulary-default-tone.mjs';
 import '../enums/vocabulary-source.mjs';
 import '../enums/vocabulary-tone.mjs';
+import '../enums/voucher-status.mjs';
+import '../enums/voucher-batch-status.mjs';
+import '../enums/voucher-batch-patch-status.mjs';
+import '../enums/voucher-batch-write-status.mjs';
+import '../enums/voucher-patch-status.mjs';
+import '../enums/voucher-write-status.mjs';
 import '../enums/attribute-boolean-status.mjs';
 import '../enums/attribute-datetime-status.mjs';
 import '../enums/attribute-email-status.mjs';
@@ -255,7 +395,7 @@ declare class Products {
      * @param {string} params.order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
      * @param {string} params.id - Exact match on `id`. The row's own id, generated by the database. A client never sends one; it reads one back and uses it in the path of every later call.
      * @param {string} params.sku - Exact match on `sku`. The merchant's own article number — unique per tenant, and the value every integration (ERP, shop, feed, price list) joins on. The one identifier a person types, and the fallback this app shows when the catalog holds no name.
-     * @param {Kind} params.kind - Exact match on `kind`. Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
+     * @param {ProductsListKind} params.kind - Exact match on `kind`. Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
      * @param {string} params.parentId - Exact match on `parent_id`. The product MODEL this variant belongs to. Only a `variant` carries one. Deleting the model leaves its variants behind with a null parent rather than deleting them.
      * @param {string} params.familyId - Exact match on `family_id`. The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} params.familyVariantId - Exact match on `family_variant_id`. Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
@@ -265,6 +405,10 @@ declare class Products {
      * @param {string} params.label - Exact match on `label`. The display name, maintained by the DATABASE so a grid of twenty thousand rows can sort and filter on a name with no join. It is the first of `attribute_values.common.name`, `…common.label`, the `de`/`en`/`de_DE`/`en_US` locale buckets, `…common.manufacturer_aid`, and finally the SKU — so a value is ALWAYS present, and a label equal to the SKU means the catalog holds no name for this product. A generated column: it cannot be written, and a create or update that names it has it dropped rather than refused. The family-aware answer, which can consult `families.label_attribute` and report where the name came from, is `POST /products/labels`.
      * @param {string} params.quantifiedAssociations - Exact match on `quantified_associations`. The import-side mirror of associations that carry a quantity — a bundle, a bill of materials, a spare-parts set. NOTHING IN THIS APP READS OR WRITES IT: no route produces it, no route consumes it, and it is null on every product this app has created. The surface that IS served is relational — `product_associations`, whose `quantity` column holds the number, guarded by `association_types.is_quantified`. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
      * @param {string} params.completeness - Exact match on `completeness`. How much of what this product's family REQUIRES it actually carries — the number a merchandiser works down. `required` counts the attributes the family marks `is_required`, `filled` how many of those carry a value in ANY bucket, `ratio` is filled/required between 0 and 1 (a family that requires nothing is 1, not undefined), `missing` lists the codes with no value anywhere, sorted, and `computed_at` is when it was measured. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
+     * @param {string} params.externalId - Exact match on `external_id`. The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {string} params.externalRefs - Exact match on `external_refs`. Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
+     * @param {string} params.sourceSyncedAt - Exact match on `source_synced_at`. When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
+     * @param {string} params.sourceData - Exact match on `source_data`. What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
      * @param {string} params.createdAt - Exact match on `created_at`. When the row was created. Server-set — it is not part of any request body.
      * @param {string} params.updatedAt - Exact match on `updated_at`. When the row was last written. Server-set — it is not part of any request body.
      * @param {string} params.deletedAt - Exact match on `deleted_at`. When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
@@ -277,7 +421,7 @@ declare class Products {
         order?: string;
         id?: string;
         sku?: string;
-        kind?: Kind;
+        kind?: ProductsListKind;
         parentId?: string;
         familyId?: string;
         familyVariantId?: string;
@@ -287,6 +431,10 @@ declare class Products {
         label?: string;
         quantifiedAssociations?: string;
         completeness?: string;
+        externalId?: string;
+        externalRefs?: string;
+        sourceSyncedAt?: string;
+        sourceData?: string;
         createdAt?: string;
         updatedAt?: string;
         deletedAt?: string;
@@ -301,7 +449,7 @@ declare class Products {
      * @param {string} order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
      * @param {string} id - Exact match on `id`. The row's own id, generated by the database. A client never sends one; it reads one back and uses it in the path of every later call.
      * @param {string} sku - Exact match on `sku`. The merchant's own article number — unique per tenant, and the value every integration (ERP, shop, feed, price list) joins on. The one identifier a person types, and the fallback this app shows when the catalog holds no name.
-     * @param {Kind} kind - Exact match on `kind`. Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
+     * @param {ProductsListKind} kind - Exact match on `kind`. Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
      * @param {string} parentId - Exact match on `parent_id`. The product MODEL this variant belongs to. Only a `variant` carries one. Deleting the model leaves its variants behind with a null parent rather than deleting them.
      * @param {string} familyId - Exact match on `family_id`. The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} familyVariantId - Exact match on `family_variant_id`. Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
@@ -311,6 +459,10 @@ declare class Products {
      * @param {string} label - Exact match on `label`. The display name, maintained by the DATABASE so a grid of twenty thousand rows can sort and filter on a name with no join. It is the first of `attribute_values.common.name`, `…common.label`, the `de`/`en`/`de_DE`/`en_US` locale buckets, `…common.manufacturer_aid`, and finally the SKU — so a value is ALWAYS present, and a label equal to the SKU means the catalog holds no name for this product. A generated column: it cannot be written, and a create or update that names it has it dropped rather than refused. The family-aware answer, which can consult `families.label_attribute` and report where the name came from, is `POST /products/labels`.
      * @param {string} quantifiedAssociations - Exact match on `quantified_associations`. The import-side mirror of associations that carry a quantity — a bundle, a bill of materials, a spare-parts set. NOTHING IN THIS APP READS OR WRITES IT: no route produces it, no route consumes it, and it is null on every product this app has created. The surface that IS served is relational — `product_associations`, whose `quantity` column holds the number, guarded by `association_types.is_quantified`. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
      * @param {string} completeness - Exact match on `completeness`. How much of what this product's family REQUIRES it actually carries — the number a merchandiser works down. `required` counts the attributes the family marks `is_required`, `filled` how many of those carry a value in ANY bucket, `ratio` is filled/required between 0 and 1 (a family that requires nothing is 1, not undefined), `missing` lists the codes with no value anywhere, sorted, and `computed_at` is when it was measured. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
+     * @param {string} externalId - Exact match on `external_id`. The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {string} externalRefs - Exact match on `external_refs`. Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
+     * @param {string} sourceSyncedAt - Exact match on `source_synced_at`. When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
+     * @param {string} sourceData - Exact match on `source_data`. What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it. The whole jsonb document is compared, serialized as JSON — this is equality, not a path or containment query, and `null` cannot be matched this way. A value that does not parse as JSON is refused with 400 `invalid_value`, naming this filter, before the request reaches the data plane.
      * @param {string} createdAt - Exact match on `created_at`. When the row was created. Server-set — it is not part of any request body.
      * @param {string} updatedAt - Exact match on `updated_at`. When the row was last written. Server-set — it is not part of any request body.
      * @param {string} deletedAt - Exact match on `deleted_at`. When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
@@ -318,7 +470,7 @@ declare class Products {
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsList(limit?: number, offset?: number, order?: string, id?: string, sku?: string, kind?: Kind, parentId?: string, familyId?: string, familyVariantId?: string, enabled?: boolean, taxClass?: string, attributeValues?: string, label?: string, quantifiedAssociations?: string, completeness?: string, createdAt?: string, updatedAt?: string, deletedAt?: string): Promise<{}>;
+    productsList(limit?: number, offset?: number, order?: string, id?: string, sku?: string, kind?: ProductsListKind, parentId?: string, familyId?: string, familyVariantId?: string, enabled?: boolean, taxClass?: string, attributeValues?: string, label?: string, quantifiedAssociations?: string, completeness?: string, externalId?: string, externalRefs?: string, sourceSyncedAt?: string, sourceData?: string, createdAt?: string, updatedAt?: string, deletedAt?: string): Promise<{}>;
     /**
      * Creates one product and answers 201 with the stored row, including the id and the timestamps the database filled in — a client never sends an id, it reads one back and uses it in the path of every later call.
      *
@@ -350,6 +502,8 @@ Defaults to `{}`, and an empty object is a normal state — a record nobody has
 Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/family`; a plain create or update never touches it, so it is null until one of the two has run. It also stays null for a product with no family — there is nothing to measure it against, and 0 % would be a lie.
      * @param {string} params.deletedAt - When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
      * @param {boolean} params.enabled - Whether the product is offered. A create defaults it from the `new_products_enabled_by_default` tenant setting rather than blindly to true, so an import does not publish twenty thousand unfinished products the moment it lands. An explicit value in the body always wins.
+     * @param {string} params.externalId - The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {object} params.externalRefs - Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer.
      * @param {string} params.familyId - The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} params.familyVariantId - Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
      * @param {ProductsKind} params.kind - Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
@@ -357,6 +511,8 @@ Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/f
      * @param {object} params.quantifiedAssociations - The import-side mirror of associations that carry a quantity — a bundle, a bill of materials, a spare-parts set. NOTHING IN THIS APP READS OR WRITES IT: no route produces it, no route consumes it, and it is null on every product this app has created. The surface that IS served is relational — `product_associations`, whose `quantity` column holds the number, guarded by `association_types.is_quantified`.
 
 It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed by association type code, and the column lets that document round-trip instead of being dropped. The database enforces no shape on it, so what a reader finds is whatever the importer wrote; the example is the conventional form.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it.
+     * @param {string} params.sourceSyncedAt - When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
      * @param {string} params.taxClass - The tax class key the prices app resolves a VAT rate from. Free text here — the vocabulary belongs to the app that prices, and `POST /products/batch` exists to hand exactly this column to it in bulk.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Products>}
@@ -367,11 +523,15 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
         completeness?: object;
         deletedAt?: string;
         enabled?: boolean;
+        externalId?: string;
+        externalRefs?: object;
         familyId?: string;
         familyVariantId?: string;
         kind?: ProductsKind;
         parentId?: string;
         quantifiedAssociations?: object;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         taxClass?: string;
     }): Promise<Models.Products>;
     /**
@@ -405,6 +565,8 @@ Defaults to `{}`, and an empty object is a normal state — a record nobody has
 Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/family`; a plain create or update never touches it, so it is null until one of the two has run. It also stays null for a product with no family — there is nothing to measure it against, and 0 % would be a lie.
      * @param {string} deletedAt - When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
      * @param {boolean} enabled - Whether the product is offered. A create defaults it from the `new_products_enabled_by_default` tenant setting rather than blindly to true, so an import does not publish twenty thousand unfinished products the moment it lands. An explicit value in the body always wins.
+     * @param {string} externalId - The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {object} externalRefs - Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer.
      * @param {string} familyId - The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} familyVariantId - Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
      * @param {ProductsKind} kind - Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
@@ -412,38 +574,47 @@ Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/f
      * @param {object} quantifiedAssociations - The import-side mirror of associations that carry a quantity — a bundle, a bill of materials, a spare-parts set. NOTHING IN THIS APP READS OR WRITES IT: no route produces it, no route consumes it, and it is null on every product this app has created. The surface that IS served is relational — `product_associations`, whose `quantity` column holds the number, guarded by `association_types.is_quantified`.
 
 It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed by association type code, and the column lets that document round-trip instead of being dropped. The database enforces no shape on it, so what a reader finds is whatever the importer wrote; the example is the conventional form.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it.
+     * @param {string} sourceSyncedAt - When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
      * @param {string} taxClass - The tax class key the prices app resolves a VAT rate from. Free text here — the vocabulary belongs to the app that prices, and `POST /products/batch` exists to hand exactly this column to it in bulk.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Products>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsCreate(sku: string, attributeValues?: object, completeness?: object, deletedAt?: string, enabled?: boolean, familyId?: string, familyVariantId?: string, kind?: ProductsKind, parentId?: string, quantifiedAssociations?: object, taxClass?: string): Promise<Models.Products>;
+    productsCreate(sku: string, attributeValues?: object, completeness?: object, deletedAt?: string, enabled?: boolean, externalId?: string, externalRefs?: object, familyId?: string, familyVariantId?: string, kind?: ProductsKind, parentId?: string, quantifiedAssociations?: object, sourceData?: object, sourceSyncedAt?: string, taxClass?: string): Promise<Models.Products>;
     /**
-     * Answers four fields — id, sku, tax_class and the resolved display name — for a list of ids and/or SKUs in ONE call. It exists for the app on the other side of a product reference: the prices app holds SKUs and needs a tax class, a feed builder holds ids and needs names, and neither should page through the catalog or fire a request per line. Ask by either identifier or both; the two are unioned and a product named twice comes back once.
+     * Answers four fields — id, sku, tax_class and the resolved display name — for a list of ids and/or SKUs in ONE call. It exists for the app on the other side of a product reference: the prices app holds SKUs and needs a tax class, a feed builder holds ids and needs names, and neither should page through the catalog or fire a request per line. Ask by either identifier or both; the two are unioned and a product named twice comes back once. At most 500 of each per call; more is refused with 400 rather than cut short.
      *
-     * It answers what it FOUND: an id or SKU that names nothing is simply absent from `items` rather than an error, so compare the length of what you sent with what came back if a miss matters. It is not a general product read — for the whole row use `GET /products/{id}`, and for a scannable list use `GET /products/grid`.
+     * With `full: true` each item is the whole row instead — what `GET /products/{id}` answers, every column and the complete `attribute_values` document, with `label` still the resolved name. That mode is for a caller that has to hand a product on and cannot know in advance which fields it will need: punchout's hand-back writes whatever columns and attribute codes a merchant's field mappings name, for every line of a cart, and needs them in one read. Leave it off when four fields will do; the short shape is unchanged by it.
      *
-     * @param {string[]} params.ids - Product ids, when the caller already holds them.
-     * @param {string[]} params.skus - Product SKUs — the identifier a foreign system carries, which is why this route exists at all.
+     * Either way it answers what it FOUND: an id or SKU that names nothing is simply absent from `items` rather than an error, so compare the length of what you sent with what came back if a miss matters. For a scannable list use `GET /products/grid`.
+     *
+     * @param {boolean} params.full - True answers each product as its whole row (`ProductBatchRow`) instead of the four-field reference (`ProductTaxRef`). For a caller that must hand a whole product on — every column and attribute value — without a read per line.
+     * @param {string[]} params.ids - Product ids, when the caller already holds them. At most 500.
+     * @param {string[]} params.skus - Product SKUs — the identifier a foreign system carries, which is why this route exists at all. At most 500.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      */
     productsBatch(params?: {
+        full?: boolean;
         ids?: string[];
         skus?: string[];
     }): Promise<{}>;
     /**
-     * Answers four fields — id, sku, tax_class and the resolved display name — for a list of ids and/or SKUs in ONE call. It exists for the app on the other side of a product reference: the prices app holds SKUs and needs a tax class, a feed builder holds ids and needs names, and neither should page through the catalog or fire a request per line. Ask by either identifier or both; the two are unioned and a product named twice comes back once.
+     * Answers four fields — id, sku, tax_class and the resolved display name — for a list of ids and/or SKUs in ONE call. It exists for the app on the other side of a product reference: the prices app holds SKUs and needs a tax class, a feed builder holds ids and needs names, and neither should page through the catalog or fire a request per line. Ask by either identifier or both; the two are unioned and a product named twice comes back once. At most 500 of each per call; more is refused with 400 rather than cut short.
+     *
+     * With `full: true` each item is the whole row instead — what `GET /products/{id}` answers, every column and the complete `attribute_values` document, with `label` still the resolved name. That mode is for a caller that has to hand a product on and cannot know in advance which fields it will need: punchout's hand-back writes whatever columns and attribute codes a merchant's field mappings name, for every line of a cart, and needs them in one read. Leave it off when four fields will do; the short shape is unchanged by it.
      *
-     * It answers what it FOUND: an id or SKU that names nothing is simply absent from `items` rather than an error, so compare the length of what you sent with what came back if a miss matters. It is not a general product read — for the whole row use `GET /products/{id}`, and for a scannable list use `GET /products/grid`.
+     * Either way it answers what it FOUND: an id or SKU that names nothing is simply absent from `items` rather than an error, so compare the length of what you sent with what came back if a miss matters. For a scannable list use `GET /products/grid`.
      *
-     * @param {string[]} ids - Product ids, when the caller already holds them.
-     * @param {string[]} skus - Product SKUs — the identifier a foreign system carries, which is why this route exists at all.
+     * @param {boolean} full - True answers each product as its whole row (`ProductBatchRow`) instead of the four-field reference (`ProductTaxRef`). For a caller that must hand a whole product on — every column and attribute value — without a read per line.
+     * @param {string[]} ids - Product ids, when the caller already holds them. At most 500.
+     * @param {string[]} skus - Product SKUs — the identifier a foreign system carries, which is why this route exists at all. At most 500.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsBatch(ids?: string[], skus?: string[]): Promise<{}>;
+    productsBatch(full?: boolean, ids?: string[], skus?: string[]): Promise<{}>;
     /**
      * The list a merchant can actually scan, as opposed to `GET /products`, which answers SKUs and a jsonb blob. Every row arrives already flattened: its resolved display name and where that name came from, its family code, its stored completeness, and the value of every attribute the catalog marks `usable_in_grid` — no join, no second call. `q` is a case-insensitive substring of the stored `label` column, which falls back to the SKU, so one box finds a product by either. Soft-deleted products are excluded here, unlike `GET /products`.
      *
@@ -453,7 +624,7 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
      * @param {number} params.offset - Row offset for pagination (default 0). Page with `page.total` and `page.hasMore`.
      * @param {string} params.order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
      * @param {string} params.q - Case-insensitive substring of the display name (or the SKU, when there is no name).
-     * @param {Kind} params.kind - Restrict to one product kind.
+     * @param {ProductsListKind} params.kind - Restrict to one product kind.
      * @param {boolean} params.enabled - Restrict to enabled or disabled products.
      * @param {string} params.familyId - Restrict to one family. A family id that does not exist is not an error here — it simply matches nothing.
      * @throws {RevenexxException}
@@ -464,7 +635,7 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
         offset?: number;
         order?: string;
         q?: string;
-        kind?: Kind;
+        kind?: ProductsListKind;
         enabled?: boolean;
         familyId?: string;
     }): Promise<{}>;
@@ -477,14 +648,14 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
      * @param {number} offset - Row offset for pagination (default 0). Page with `page.total` and `page.hasMore`.
      * @param {string} order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
      * @param {string} q - Case-insensitive substring of the display name (or the SKU, when there is no name).
-     * @param {Kind} kind - Restrict to one product kind.
+     * @param {ProductsListKind} kind - Restrict to one product kind.
      * @param {boolean} enabled - Restrict to enabled or disabled products.
      * @param {string} familyId - Restrict to one family. A family id that does not exist is not an error here — it simply matches nothing.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsGrid(limit?: number, offset?: number, order?: string, q?: string, kind?: Kind, enabled?: boolean, familyId?: string): Promise<{}>;
+    productsGrid(limit?: number, offset?: number, order?: string, q?: string, kind?: ProductsListKind, enabled?: boolean, familyId?: string): Promise<{}>;
     /**
      * What is this product CALLED? A product's name is an attribute rather than a column, and which attribute it is, is per family — so no plain read can answer it. This resolves up to 500 products at once, by id and/or SKU: it reads families.label_attribute (falling back to the default_label_attribute setting, then to the conventional `name`) and looks the value up through the scoped attribute_values document — common, then locale_specific in the label_locales order, then the channel buckets.
      *
@@ -528,6 +699,7 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
      * @param {number} params.quantity - Exact match on `quantity`. How many of the target belong to the source — the 4 in "this bundle contains 4 casters". Only meaningful when the association type carries `is_quantified`; null on an ordinary cross-sell.
      * @param {number} params.position - Exact match on `position`. Order in which the targets are shown, ascending.
      * @param {string} params.createdAt - Exact match on `created_at`. When the row was created. Server-set — it is not part of any request body.
+     * @param {string} params.updatedAt - Exact match on `updated_at`. When the row was last written. Server-set — it is not part of any request body.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      */
@@ -542,6 +714,7 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
         quantity?: number;
         position?: number;
         createdAt?: string;
+        updatedAt?: string;
     }): Promise<{}>;
     /**
      * One relation from one product to another, of a declared type: this drill's accessories, this bundle's parts, this article's cross-sells. `quantity` is the number in "this bundle contains 4 casters" and is meaningful only when the association type carries `is_quantified`. This relational surface is the one this app serves; the `products.quantified_associations` column is an importer's blob that no route here reads or writes.
@@ -560,11 +733,12 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
      * @param {number} quantity - Exact match on `quantity`. How many of the target belong to the source — the 4 in "this bundle contains 4 casters". Only meaningful when the association type carries `is_quantified`; null on an ordinary cross-sell.
      * @param {number} position - Exact match on `position`. Order in which the targets are shown, ascending.
      * @param {string} createdAt - Exact match on `created_at`. When the row was created. Server-set — it is not part of any request body.
+     * @param {string} updatedAt - Exact match on `updated_at`. When the row was last written. Server-set — it is not part of any request body.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsProductAssociationsList(limit?: number, offset?: number, order?: string, id?: string, productId?: string, associationTypeId?: string, targetProductId?: string, quantity?: number, position?: number, createdAt?: string): Promise<{}>;
+    productsProductAssociationsList(limit?: number, offset?: number, order?: string, id?: string, productId?: string, associationTypeId?: string, targetProductId?: string, quantity?: number, position?: number, createdAt?: string, updatedAt?: string): Promise<{}>;
     /**
      * Creates one product association and answers 201 with the stored row, including the id and the timestamps the database filled in — a client never sends an id, it reads one back and uses it in the path of every later call.
      *
@@ -817,6 +991,8 @@ Defaults to `{}`, and an empty object is a normal state — a record nobody has
 Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/family`; a plain create or update never touches it, so it is null until one of the two has run. It also stays null for a product with no family — there is nothing to measure it against, and 0 % would be a lie.
      * @param {string} params.deletedAt - When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
      * @param {boolean} params.enabled - Whether the product is offered. A create defaults it from the `new_products_enabled_by_default` tenant setting rather than blindly to true, so an import does not publish twenty thousand unfinished products the moment it lands. An explicit value in the body always wins.
+     * @param {string} params.externalId - The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {object} params.externalRefs - Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer.
      * @param {string} params.familyId - The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} params.familyVariantId - Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
      * @param {ProductsKind} params.kind - Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
@@ -825,6 +1001,8 @@ Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/f
 
 It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed by association type code, and the column lets that document round-trip instead of being dropped. The database enforces no shape on it, so what a reader finds is whatever the importer wrote; the example is the conventional form.
      * @param {string} params.sku - The merchant's own article number — unique per tenant, and the value every integration (ERP, shop, feed, price list) joins on. The one identifier a person types, and the fallback this app shows when the catalog holds no name.
+     * @param {object} params.sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it.
+     * @param {string} params.sourceSyncedAt - When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
      * @param {string} params.taxClass - The tax class key the prices app resolves a VAT rate from. Free text here — the vocabulary belongs to the app that prices, and `POST /products/batch` exists to hand exactly this column to it in bulk.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Products>}
@@ -835,12 +1013,16 @@ It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed
         completeness?: object;
         deletedAt?: string;
         enabled?: boolean;
+        externalId?: string;
+        externalRefs?: object;
         familyId?: string;
         familyVariantId?: string;
         kind?: ProductsKind;
         parentId?: string;
         quantifiedAssociations?: object;
         sku?: string;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         taxClass?: string;
     }): Promise<Models.Products>;
     /**
@@ -874,6 +1056,8 @@ Defaults to `{}`, and an empty object is a normal state — a record nobody has
 Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/family`; a plain create or update never touches it, so it is null until one of the two has run. It also stays null for a product with no family — there is nothing to measure it against, and 0 % would be a lie.
      * @param {string} deletedAt - When the product was soft-deleted. `GET /products/grid` and every category-rule evaluation exclude a row that carries one; `GET /products` does NOT — filter on it to read the live catalog.
      * @param {boolean} enabled - Whether the product is offered. A create defaults it from the `new_products_enabled_by_default` tenant setting rather than blindly to true, so an import does not publish twenty thousand unfinished products the moment it lands. An explicit value in the body always wins.
+     * @param {string} externalId - The key this article has in the system that OWNS it — for a catalog fed by BMEcat, the PIM's own id for the row. It is NOT the `sku`: the SKU is the merchant's article number, typed by people and printed on paper, while this is whatever the feeding system calls the same article, often a number nobody outside it sees. Unique per tenant where set, so a repeated import upserts on it instead of matching on SKU and founding a second product. Null for a product created here.
+     * @param {object} externalRefs - Every OTHER system that knows this row, keyed by system name — a second PIM, a supplier's feed, a GTIN register. `external_id` is the system that OWNS the row; this is the rest, so the next identifier standard costs a key in here rather than a column and a migration. It filters the way every jsonb column of this app filters: the WHOLE document is compared, so there is no asking for one key — read the row by `external_id` and take this off the answer.
      * @param {string} familyId - The family that decides which attributes this product HAS. Without one nothing is required, completeness cannot be computed and the display name never resolves — `POST /products/{id}/family` is the call that sets it and computes completeness in the same step.
      * @param {string} familyVariantId - Which variant structure of the family this product follows — the axes it splits on. Null on a simple product.
      * @param {ProductsKind} kind - Where the product sits in the variant hierarchy. 'simple' stands on its own. 'model' carries the values its variants share and is never sold itself. 'variant' carries the axis values and points at its model through `parent_id`.
@@ -882,12 +1066,14 @@ Written only by `POST /products/{id}/completeness` and by `POST /products/{id}/f
 
 It exists because a PIM import (Akeneo, BMEcat) carries these in one blob keyed by association type code, and the column lets that document round-trip instead of being dropped. The database enforces no shape on it, so what a reader finds is whatever the importer wrote; the example is the conventional form.
      * @param {string} sku - The merchant's own article number — unique per tenant, and the value every integration (ERP, shop, feed, price list) joins on. The one identifier a person types, and the fallback this app shows when the catalog holds no name.
+     * @param {object} sourceData - What the source said about this row, kept as it said it: `{"system": …, "etag": …, "raw": {…}}`. The `etag` is what a write-back has to hand back in `If-Match`, and between two runs there is nowhere else to keep it. `raw` carries the source fields this app does not model, so they survive a round trip instead of being lost the first time somebody edits here. Written by whatever imports the row; nothing in this app reads or maintains it.
+     * @param {string} sourceSyncedAt - When this row was last CONFIRMED against its source — not when it last changed. A delta run asks for everything it has not seen since its last pass, and over 25 000 products that is the difference between an index scan and reading the whole catalog, which is the reason the column is indexed. An edit made here leaves it alone, so a value that has stopped moving says the feed has gone quiet, not that nobody works the record. Null for a row no source owns.
      * @param {string} taxClass - The tax class key the prices app resolves a VAT rate from. Free text here — the vocabulary belongs to the app that prices, and `POST /products/batch` exists to hand exactly this column to it in bulk.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Products>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    productsUpdate(id: string, attributeValues?: object, completeness?: object, deletedAt?: string, enabled?: boolean, familyId?: string, familyVariantId?: string, kind?: ProductsKind, parentId?: string, quantifiedAssociations?: object, sku?: string, taxClass?: string): Promise<Models.Products>;
+    productsUpdate(id: string, attributeValues?: object, completeness?: object, deletedAt?: string, enabled?: boolean, externalId?: string, externalRefs?: object, familyId?: string, familyVariantId?: string, kind?: ProductsKind, parentId?: string, quantifiedAssociations?: object, sku?: string, sourceData?: object, sourceSyncedAt?: string, taxClass?: string): Promise<Models.Products>;
     /**
      * How much of what its family REQUIRES does this product actually carry — the number a merchandiser works down. products.completeness is jsonb that nothing had ever written. This computes it from family_attributes (is_required) against the product's own scoped attribute_values and stores the result. A product with no family answers 400 rather than an invented 0 % — it has nothing to be measured against.
      *