@revenexx/node 0.1.1 → 0.2.0

package/dist/services/shipping-carriers.d.ts

@@ -3,6 +3,9 @@ import { Models } from '../models.js';
 import { ShippingCarriersListStatus } from '../enums/shipping-carriers-list-status.js';
 import { ShippingCarrierStatus } from '../enums/shipping-carrier-status.js';
 import '../query.js';
+import '../enums/accept-line-decision.js';
+import '../enums/accept-result-origin.js';
+import '../enums/accept-result-status.js';
 import '../enums/address-type-row-tone.js';
 import '../enums/address-type-row-create-request-tone.js';
 import '../enums/address-type-row-update-request-tone.js';
@@ -16,12 +19,23 @@ import '../enums/approval-rule-update-request-approver-type.js';
 import '../enums/approval-rule-update-request-condition.js';
 import '../enums/approval-rule-update-request-effect.js';
 import '../enums/assets-source.js';
+import '../enums/assignment-role-tone.js';
+import '../enums/assignment-role-create-request-tone.js';
+import '../enums/assignment-role-update-request-tone.js';
+import '../enums/attach-request-direction.js';
+import '../enums/attach-request-visibility.js';
 import '../enums/attribute-value-bucket.js';
 import '../enums/auth-mail-source.js';
+import '../enums/auth-mfa-challenge-request-factor.js';
 import '../enums/recovery-mail-source.js';
 import '../enums/registration-status.js';
+import '../enums/availability-state-tone.js';
+import '../enums/banner-draft-layout.js';
+import '../enums/banner-draft-update-request-layout.js';
 import '../enums/budget-change-reason.js';
 import '../enums/budget-movement-result-status.js';
+import '../enums/budget-release-scope.js';
+import '../enums/budget-release-status.js';
 import '../enums/cart-status.js';
 import '../enums/cart-merge-strategy.js';
 import '../enums/cart-price-snapshot-mode.js';
@@ -49,18 +63,44 @@ import '../enums/channel-vocabulary-tone.js';
 import '../enums/channel-vocabulary-name.js';
 import '../enums/channel-vocabulary-source.js';
 import '../enums/channel-vocabulary-ref-name.js';
+import '../enums/consent-record-action.js';
+import '../enums/consent-record-surface.js';
+import '../enums/consent-record-create-request-action.js';
+import '../enums/consent-record-create-request-surface.js';
+import '../enums/consent-vocabulary-source.js';
+import '../enums/contact-order-approval-mode.js';
 import '../enums/contact-registration-status.js';
 import '../enums/contact-status.js';
 import '../enums/contact-activity-kind.js';
+import '../enums/order-approval-mode.js';
 import '../enums/contact-create-request-registration-status.js';
 import '../enums/contact-event-kind-tone.js';
 import '../enums/contact-event-kind-create-request-tone.js';
 import '../enums/contact-event-kind-update-request-tone.js';
-import '../enums/contact-update-request-registration-status.js';
+import '../enums/contact-point-kind-tone.js';
+import '../enums/contact-point-kind-create-request-tone.js';
+import '../enums/contact-point-kind-update-request-tone.js';
+import '../enums/cookie-kind.js';
+import '../enums/cookie-create-request-kind.js';
+import '../enums/cookie-update-request-kind.js';
 import '../enums/cost-center-budget-type.js';
+import '../enums/cost-center-create-request-budget-type.js';
 import '../enums/cost-center-restriction-type.js';
 import '../enums/cost-center-restriction-create-request-type.js';
 import '../enums/cost-center-restriction-update-request-type.js';
+import '../enums/cost-center-update-request-budget-type.js';
+import '../enums/cost-centers-vocabulary-tone.js';
+import '../enums/cost-centers-vocabulary-name.js';
+import '../enums/cost-centers-vocabulary-source.js';
+import '../enums/cost-centers-vocabulary-summary-name.js';
+import '../enums/direct-order-status.js';
+import '../enums/document-source.js';
+import '../enums/document-visibility.js';
+import '../enums/document-kind-tone.js';
+import '../enums/document-vocabulary-default-tone.js';
+import '../enums/document-vocabulary-name.js';
+import '../enums/document-vocabulary-source.js';
+import '../enums/document-vocabulary-tone.js';
 import '../enums/payment-fee-type.js';
 import '../enums/payment-method-kind.js';
 import '../enums/form-status.js';
@@ -70,6 +110,7 @@ import '../enums/form-submission-prune-request-status.js';
 import '../enums/forms-vocabulary-tone.js';
 import '../enums/forms-vocabulary-name.js';
 import '../enums/forms-vocabulary-summary-name.js';
+import '../enums/inventory-receive-warning-code.js';
 import '../enums/inventory-vocabulary-default-tone.js';
 import '../enums/inventory-vocabulary-source.js';
 import '../enums/cart-io-apply-mode.js';
@@ -77,6 +118,7 @@ import '../enums/cart-io-direction.js';
 import '../enums/cart-io-entity.js';
 import '../enums/io-profile-resource-apply-mode.js';
 import '../enums/io-profile-resource-direction.js';
+import '../enums/inventory-unorderable-reason.js';
 import '../enums/lifecycle-stage-tone.js';
 import '../enums/lifecycle-stage-create-request-tone.js';
 import '../enums/lifecycle-stage-update-request-tone.js';
@@ -93,28 +135,40 @@ import '../enums/markets-vocabulary-tone.js';
 import '../enums/markets-vocabulary-name.js';
 import '../enums/markets-vocabulary-source.js';
 import '../enums/markets-vocabulary-summary-name.js';
+import '../enums/note-request-visibility.js';
 import '../enums/order-fulfillment-status.js';
 import '../enums/order-payment-status.js';
 import '../enums/order-status.js';
 import '../enums/order-cancellation-scope.js';
 import '../enums/order-comment-visibility.js';
+import '../enums/order-discount-target.js';
+import '../enums/order-discount-effect-kind.js';
+import '../enums/order-discount-placement.js';
+import '../enums/order-discount-source.js';
+import '../enums/order-discount-value-type.js';
 import '../enums/order-item-type.js';
 import '../enums/order-list-kind-tone.js';
 import '../enums/order-list-kind-row-tone.js';
+import '../enums/order-list-skip-reason.js';
 import '../enums/order-list-cart-mode.js';
 import '../enums/order-list-vocabulary-default-tone.js';
 import '../enums/order-list-vocabulary-name.js';
 import '../enums/order-list-vocabulary-source.js';
 import '../enums/order-list-vocabulary-tone.js';
+import '../enums/order-return-refund-mode.js';
 import '../enums/order-return-status.js';
 import '../enums/order-return-settlement.js';
-import '../enums/order-return-refusal.js';
 import '../enums/order-vocabulary-tone.js';
+import '../enums/order-return-refusal.js';
 import '../enums/order-vocabulary-name.js';
 import '../enums/order-vocabulary-source.js';
 import '../enums/order-vocabulary-summary-name.js';
 import '../enums/order-resolution-stage.js';
+import '../enums/organization-credit-limit-mode.js';
+import '../enums/organization-shipping-advice.js';
 import '../enums/organization-status.js';
+import '../enums/credit-limit-mode.js';
+import '../enums/shipping-advice.js';
 import '../enums/page-status.js';
 import '../enums/pages-vocabulary-app.js';
 import '../enums/pages-vocabulary-tone.js';
@@ -136,6 +190,7 @@ import '../enums/price-entries-adjust-response-rounding-mode.js';
 import '../enums/price-entries-bulk-mode.js';
 import '../enums/price-rounding-mode.js';
 import '../enums/price-entry-type.js';
+import '../enums/price-line-price-reason.js';
 import '../enums/price-list-status.js';
 import '../enums/price-list-tax-basis.js';
 import '../enums/price-currency-source.js';
@@ -147,22 +202,86 @@ import '../enums/price-vocabulary-tone.js';
 import '../enums/price-vocabulary-name.js';
 import '../enums/price-vocabulary-source.js';
 import '../enums/price-vocabulary-ref-name.js';
+import '../enums/procurement-vocabulary-default-tone.js';
+import '../enums/procurement-vocabulary-name.js';
+import '../enums/procurement-vocabulary-source.js';
+import '../enums/procurement-vocabulary-summary-name.js';
+import '../enums/procurement-vocabulary-value-tone.js';
 import '../enums/product-categories-source.js';
 import '../enums/product-grid-column-source.js';
 import '../enums/product-label-source.js';
 import '../enums/product-label-attribute-source.js';
 import '../enums/products-kind.js';
+import '../enums/promotion-condition-match.js';
+import '../enums/promotion-reach.js';
+import '../enums/promotion-recurrence-kind.js';
+import '../enums/promotion-return-behaviour.js';
+import '../enums/promotion-status.js';
+import '../enums/promotion-bundle-allocation.js';
+import '../enums/promotion-bundle-patch-allocation.js';
+import '../enums/promotion-bundle-write-allocation.js';
+import '../enums/promotion-condition-kind.js';
+import '../enums/promotion-condition-match-mode.js';
+import '../enums/promotion-condition-patch-kind.js';
+import '../enums/promotion-condition-patch-match-mode.js';
+import '../enums/promotion-condition-write-kind.js';
+import '../enums/promotion-condition-write-match-mode.js';
+import '../enums/promotion-effect-kind.js';
+import '../enums/promotion-effect-target-scope.js';
+import '../enums/promotion-effect-unit-choice.js';
+import '../enums/promotion-effect-value-type.js';
+import '../enums/promotion-effect-patch-kind.js';
+import '../enums/promotion-effect-patch-target-scope.js';
+import '../enums/promotion-effect-patch-unit-choice.js';
+import '../enums/promotion-effect-patch-value-type.js';
+import '../enums/promotion-effect-write-kind.js';
+import '../enums/promotion-effect-write-target-scope.js';
+import '../enums/promotion-effect-write-unit-choice.js';
+import '../enums/promotion-effect-write-value-type.js';
+import '../enums/promotion-patch-condition-match.js';
+import '../enums/promotion-patch-reach.js';
+import '../enums/promotion-patch-recurrence-kind.js';
+import '../enums/promotion-patch-return-behaviour.js';
+import '../enums/promotion-patch-status.js';
+import '../enums/promotion-release-request-reason.js';
+import '../enums/promotion-write-condition-match.js';
+import '../enums/promotion-write-reach.js';
+import '../enums/promotion-write-recurrence-kind.js';
+import '../enums/promotion-write-return-behaviour.js';
+import '../enums/promotion-write-status.js';
+import '../enums/punchout-entry-probe-result-entry-probe-status.js';
+import '../enums/punchout-entry-test-result-protocol.js';
+import '../enums/punchout-field-mapping-import-request-protocol.js';
+import '../enums/punchout-return-preview-protocol.js';
 import '../enums/purchase-request-status.js';
 import '../enums/purchase-request-event-name.js';
 import '../enums/purchase-request-item-type.js';
 import '../enums/purchase-request-item-create-request-type.js';
 import '../enums/purchase-request-item-update-request-type.js';
+import '../enums/purpose-legal-basis.js';
+import '../enums/purpose-create-request-legal-basis.js';
+import '../enums/purpose-update-request-legal-basis.js';
+import '../enums/quote-origin.js';
+import '../enums/quote-status.js';
+import '../enums/quote-attachment-direction.js';
+import '../enums/quote-attachment-visibility.js';
+import '../enums/quote-detail-origin.js';
+import '../enums/quote-detail-status.js';
+import '../enums/quote-event-visibility.js';
+import '../enums/quote-item-decision.js';
+import '../enums/quote-item-price-reason.js';
+import '../enums/quote-line-input-price-reason.js';
+import '../enums/redemption-state.js';
 import '../enums/reorder-point-source.js';
 import '../enums/reservation-status.js';
 import '../enums/price-on-request-reason.js';
 import '../enums/price-tax-basis.js';
 import '../enums/price-tax-basis-source.js';
 import '../enums/role-catalog-response-source.js';
+import '../enums/sales-rep-vocabulary-default-tone.js';
+import '../enums/sales-rep-vocabulary-source.js';
+import '../enums/seed-request-mode.js';
+import '../enums/seed-result-mode.js';
 import '../enums/segment-rule-match.js';
 import '../enums/segment-member-source.js';
 import '../enums/segment-rule-operator.js';
@@ -191,14 +310,35 @@ import '../enums/shipping-vocabulary-tone.js';
 import '../enums/shipping-weight-unit-create-request-tone.js';
 import '../enums/shipping-weight-unit-row-tone.js';
 import '../enums/shipping-weight-unit-update-request-tone.js';
+import '../enums/stacking-group-mode.js';
+import '../enums/stacking-group-patch-mode.js';
+import '../enums/stacking-group-write-mode.js';
 import '../enums/stock-movement-type.js';
 import '../enums/store-asset-request-visibility.js';
 import '../enums/submit-item-type.js';
 import '../enums/submit-result-outcome.js';
+import '../enums/tag-manager-container-check-reason.js';
+import '../enums/tag-manager-marketing-tag-kind.js';
+import '../enums/tag-manager-marketing-tag-load.js';
+import '../enums/tag-manager-marketing-tag-input-kind.js';
+import '../enums/tag-manager-marketing-tag-input-load.js';
+import '../enums/tag-manager-trigger-kind.js';
+import '../enums/tag-manager-trigger-input-kind.js';
+import '../enums/tag-manager-variable-kind.js';
+import '../enums/tag-manager-variable-input-kind.js';
 import '../enums/validation-failed-response-status.js';
+import '../enums/vendor-legal-basis-override.js';
+import '../enums/vendor-create-request-legal-basis-override.js';
+import '../enums/vendor-update-request-legal-basis-override.js';
 import '../enums/vocabulary-default-tone.js';
 import '../enums/vocabulary-source.js';
 import '../enums/vocabulary-tone.js';
+import '../enums/voucher-status.js';
+import '../enums/voucher-batch-status.js';
+import '../enums/voucher-batch-patch-status.js';
+import '../enums/voucher-batch-write-status.js';
+import '../enums/voucher-patch-status.js';
+import '../enums/voucher-write-status.js';
 import '../enums/attribute-boolean-status.js';
 import '../enums/attribute-datetime-status.js';
 import '../enums/attribute-email-status.js';
@@ -254,6 +394,7 @@ declare class ShippingCarriers {
      * @param {string} params.code - Exact-match filter on `code`. Unique per tenant, so this resolves a code an order shipment already stores without paging the whole list.
      * @param {ShippingCarriersListStatus} params.status - Exact-match filter on `status`. Quoting state — the cheap way to list only the carriers that may currently be quoted.
      * @param {string} params.serviceLevel - Exact-match filter on `service_level`. A code into the tenant's own service levels (GET /shipping/service-levels).
+     * @param {string} params.externalId - Exact-match filter on `external_id`. The carrier one foreign system owns, by the key that system knows it by — how an import finds the row it wrote last run instead of creating a second one. Unique per tenant, so this answers at most one carrier; a carrier nobody imported matches nothing.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      */
@@ -264,6 +405,7 @@ declare class ShippingCarriers {
         code?: string;
         status?: ShippingCarriersListStatus;
         serviceLevel?: string;
+        externalId?: string;
     }): Promise<{}>;
     /**
      * Filterable by exact column value — `?code=`, `?status=` and `?service_level=` are applied as equalities and echoed back in `filter`. A query key that names no column of this entity is SILENTLY IGNORED: the page comes back unfiltered, 200, with an empty `filter`, so compare the echo against what you sent rather than trusting the status.
@@ -274,25 +416,30 @@ declare class ShippingCarriers {
      * @param {string} code - Exact-match filter on `code`. Unique per tenant, so this resolves a code an order shipment already stores without paging the whole list.
      * @param {ShippingCarriersListStatus} status - Exact-match filter on `status`. Quoting state — the cheap way to list only the carriers that may currently be quoted.
      * @param {string} serviceLevel - Exact-match filter on `service_level`. A code into the tenant's own service levels (GET /shipping/service-levels).
+     * @param {string} externalId - Exact-match filter on `external_id`. The carrier one foreign system owns, by the key that system knows it by — how an import finds the row it wrote last run instead of creating a second one. Unique per tenant, so this answers at most one carrier; a carrier nobody imported matches nothing.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    shippingCarriersList(limit?: number, offset?: number, order?: string, code?: string, status?: ShippingCarriersListStatus, serviceLevel?: string): Promise<{}>;
+    shippingCarriersList(limit?: number, offset?: number, order?: string, code?: string, status?: ShippingCarriersListStatus, serviceLevel?: string, externalId?: string): Promise<{}>;
     /**
-     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. Reach for it for a carrier this app does not describe — a regional courier, a forwarder, an own fleet; for the DACH networks read GET /shipping/carriers/catalog and let POST /shipping/carriers/defaults write them. A create cannot omit `code` and `name`; every other column is optional or defaulted by the database. Two rows of this tenant may not share `code` — that is the 409. `service_level` has to name one of the tenant's own levels and `cutoff_time` has to be HH:MM in 24-hour UTC — both are refused rather than stored, because a cut-off the estimator cannot read would be dropped in silence and the shop would keep promising a ship date nobody computed. Creating a carrier quotes nothing on its own: a method has to reference it (`carrier_id`, or a `carrier` text equal to this code) before any of it is inherited.
+     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. Reach for it for a carrier this app does not describe — a regional courier, a forwarder, an own fleet; for the DACH networks read GET /shipping/carriers/catalog and let POST /shipping/carriers/defaults write them. A create cannot omit `code` and `name`; every other column is optional or defaulted by the database. Two rows of this tenant may not share `code` or `external_id` — that is the 409. `service_level` has to name one of the tenant's own levels and `cutoff_time` has to be HH:MM in 24-hour UTC — both are refused rather than stored, because a cut-off the estimator cannot read would be dropped in silence and the shop would keep promising a ship date nobody computed. Creating a carrier quotes nothing on its own: a method has to reference it (`carrier_id`, or a `carrier` text equal to this code) before any of it is inherited.
      *
-     * @param {string} params.code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls). A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field. Deliberately no slug pattern: the column asks only for a non-empty string, and a contract stricter than the implementation would refuse codes merchants already keep.
+     * @param {string} params.code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls), in lower case. A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field — and a tracking request finds it by code without regard to case. A code with a capital letter is refused with 400 `invalid_carrier_code`; a carrier stored with one before 1.0 keeps it and keeps resolving.
      * @param {string} params.name - Display name, as an operator typed it.
-     * @param {string[]} params.countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared upper-cased, so a lower-case entry still matches. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
+     * @param {string[]} params.countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared without regard to case, so a lower-case entry still matches; anything but a two-letter code is refused with 400 `invalid_countries`. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
      * @param {string} params.cutoffTime - This carrier's own daily pickup cut-off, HH:MM in 24-hour form, UTC. Overrides the tenant's cutoff_time for methods on this carrier — one shop-wide time cannot be both DHL's 16:00 and a forwarder's 12:00. Null or the empty string means this carrier declares none; any other shape is a 400, because a cut-off the estimator cannot read is a delivery promise silently computed without one.
      * @param {number} params.etaDaysMax - Transit time upper bound, in calendar days from the ship date.
      * @param {number} params.etaDaysMin - Transit time lower bound, in calendar days from the ship date — inherited by any method on this carrier that states no ETA of its own.
-     * @param {number} params.handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days. Overrides the tenant's handling_days.
+     * @param {string} params.externalId - The key this carrier has in the system that OWNS it — the shipping agent as an ERP numbers it, which is rarely the `code` a merchant types here. Unique per tenant where it is set, so a repeated import upserts on it instead of matching on a name; a carrier created in the Cockpit carries none and never will.
+     * @param {object} params.externalRefs - Every OTHER system that knows this carrier, keyed by system name — a second ERP, a TMS, the label printer's own agent list. `external_id` names the leading system; this is the rest, and the next one costs no column. Answered on read and carrying no query parameter: a jsonb column is compared as a WHOLE document, so a filter over part of one is refused. Look the row up by `external_id` and read this off the answer.
+     * @param {number} params.handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days — a whole number, 0 or more. Overrides the tenant's handling_days.
      * @param {object} params.labels - Localized display names. A flat map keyed by locale — the Cockpit falls back to `en`. Null means the row has no translations and every client shows the untranslated column instead.
      * @param {object} params.metadata - Free-form jsonb the platform never reads or validates — whatever the merchant or their integration needs to keep beside the row (a customer number with the carrier, an ERP key, a label-printer id). The shape varies BY INTEGRATION, not by anything this app knows, so no key is declared and none is reserved; the example is one plausible instance rather than a schema. A flat map of scalars is the convention, and nothing enforces it.
      * @param {number} params.position - Sort order among the carriers; ties fall back to whatever the database returns.
      * @param {string} params.serviceLevel - The class of service this row represents (default 'standard'), as a CODE into the tenant's own service levels (GET /shipping/service-levels). One row is one class: a carrier selling both a parcel and an express product is two rows. Deliberately not an enum here — the set is the merchant's, so a fixed list in this contract would make the gateway reject a level they created. A code the tenant does not keep is a 400 naming the codes they do.
+     * @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 send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so an edit here does not silently throw them away.
+     * @param {string} params.sourceSyncedAt - When this row was last confirmed against its source. A delta run asks the source for what changed since it, and an operator reads it to see that a feed has gone quiet. An edit made HERE does not touch it — it records when the source was last seen, not when the row changed — so a stale value beside a fresh `updated_at` means somebody is maintaining by hand what a feed has stopped delivering.
      * @param {ShippingCarrierStatus} params.status - Whether this carrier may be quoted (default 'active'). Anything else excludes every method that ships with it from POST /shipping/rates, with a reason. Tracking links are NOT gated on it — a retired carrier's old shipments stay resolvable.
      * @param {string} params.trackingUrlTemplate - Tracking page URL with {tracking_code} where the number goes; {postal_code} and {country} are also substituted, URL-encoded. Null for a carrier with no public tracking page.
      * @throws {RevenexxException}
@@ -305,35 +452,43 @@ declare class ShippingCarriers {
         cutoffTime?: string;
         etaDaysMax?: number;
         etaDaysMin?: number;
+        externalId?: string;
+        externalRefs?: object;
         handlingDays?: number;
         labels?: object;
         metadata?: object;
         position?: number;
         serviceLevel?: string;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         status?: ShippingCarrierStatus;
         trackingUrlTemplate?: string;
     }): Promise<Models.ShippingCarrier>;
     /**
-     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. Reach for it for a carrier this app does not describe — a regional courier, a forwarder, an own fleet; for the DACH networks read GET /shipping/carriers/catalog and let POST /shipping/carriers/defaults write them. A create cannot omit `code` and `name`; every other column is optional or defaulted by the database. Two rows of this tenant may not share `code` — that is the 409. `service_level` has to name one of the tenant's own levels and `cutoff_time` has to be HH:MM in 24-hour UTC — both are refused rather than stored, because a cut-off the estimator cannot read would be dropped in silence and the shop would keep promising a ship date nobody computed. Creating a carrier quotes nothing on its own: a method has to reference it (`carrier_id`, or a `carrier` text equal to this code) before any of it is inherited.
+     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. Reach for it for a carrier this app does not describe — a regional courier, a forwarder, an own fleet; for the DACH networks read GET /shipping/carriers/catalog and let POST /shipping/carriers/defaults write them. A create cannot omit `code` and `name`; every other column is optional or defaulted by the database. Two rows of this tenant may not share `code` or `external_id` — that is the 409. `service_level` has to name one of the tenant's own levels and `cutoff_time` has to be HH:MM in 24-hour UTC — both are refused rather than stored, because a cut-off the estimator cannot read would be dropped in silence and the shop would keep promising a ship date nobody computed. Creating a carrier quotes nothing on its own: a method has to reference it (`carrier_id`, or a `carrier` text equal to this code) before any of it is inherited.
      *
-     * @param {string} code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls). A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field. Deliberately no slug pattern: the column asks only for a non-empty string, and a contract stricter than the implementation would refuse codes merchants already keep.
+     * @param {string} code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls), in lower case. A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field — and a tracking request finds it by code without regard to case. A code with a capital letter is refused with 400 `invalid_carrier_code`; a carrier stored with one before 1.0 keeps it and keeps resolving.
      * @param {string} name - Display name, as an operator typed it.
-     * @param {string[]} countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared upper-cased, so a lower-case entry still matches. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
+     * @param {string[]} countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared without regard to case, so a lower-case entry still matches; anything but a two-letter code is refused with 400 `invalid_countries`. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
      * @param {string} cutoffTime - This carrier's own daily pickup cut-off, HH:MM in 24-hour form, UTC. Overrides the tenant's cutoff_time for methods on this carrier — one shop-wide time cannot be both DHL's 16:00 and a forwarder's 12:00. Null or the empty string means this carrier declares none; any other shape is a 400, because a cut-off the estimator cannot read is a delivery promise silently computed without one.
      * @param {number} etaDaysMax - Transit time upper bound, in calendar days from the ship date.
      * @param {number} etaDaysMin - Transit time lower bound, in calendar days from the ship date — inherited by any method on this carrier that states no ETA of its own.
-     * @param {number} handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days. Overrides the tenant's handling_days.
+     * @param {string} externalId - The key this carrier has in the system that OWNS it — the shipping agent as an ERP numbers it, which is rarely the `code` a merchant types here. Unique per tenant where it is set, so a repeated import upserts on it instead of matching on a name; a carrier created in the Cockpit carries none and never will.
+     * @param {object} externalRefs - Every OTHER system that knows this carrier, keyed by system name — a second ERP, a TMS, the label printer's own agent list. `external_id` names the leading system; this is the rest, and the next one costs no column. Answered on read and carrying no query parameter: a jsonb column is compared as a WHOLE document, so a filter over part of one is refused. Look the row up by `external_id` and read this off the answer.
+     * @param {number} handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days — a whole number, 0 or more. Overrides the tenant's handling_days.
      * @param {object} labels - Localized display names. A flat map keyed by locale — the Cockpit falls back to `en`. Null means the row has no translations and every client shows the untranslated column instead.
      * @param {object} metadata - Free-form jsonb the platform never reads or validates — whatever the merchant or their integration needs to keep beside the row (a customer number with the carrier, an ERP key, a label-printer id). The shape varies BY INTEGRATION, not by anything this app knows, so no key is declared and none is reserved; the example is one plausible instance rather than a schema. A flat map of scalars is the convention, and nothing enforces it.
      * @param {number} position - Sort order among the carriers; ties fall back to whatever the database returns.
      * @param {string} serviceLevel - The class of service this row represents (default 'standard'), as a CODE into the tenant's own service levels (GET /shipping/service-levels). One row is one class: a carrier selling both a parcel and an express product is two rows. Deliberately not an enum here — the set is the merchant's, so a fixed list in this contract would make the gateway reject a level they created. A code the tenant does not keep is a 400 naming the codes they do.
+     * @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 send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so an edit here does not silently throw them away.
+     * @param {string} sourceSyncedAt - When this row was last confirmed against its source. A delta run asks the source for what changed since it, and an operator reads it to see that a feed has gone quiet. An edit made HERE does not touch it — it records when the source was last seen, not when the row changed — so a stale value beside a fresh `updated_at` means somebody is maintaining by hand what a feed has stopped delivering.
      * @param {ShippingCarrierStatus} status - Whether this carrier may be quoted (default 'active'). Anything else excludes every method that ships with it from POST /shipping/rates, with a reason. Tracking links are NOT gated on it — a retired carrier's old shipments stay resolvable.
      * @param {string} trackingUrlTemplate - Tracking page URL with {tracking_code} where the number goes; {postal_code} and {country} are also substituted, URL-encoded. Null for a carrier with no public tracking page.
      * @throws {RevenexxException}
      * @returns {Promise<Models.ShippingCarrier>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    shippingCarriersCreate(code: string, name: string, countries?: string[], cutoffTime?: string, etaDaysMax?: number, etaDaysMin?: number, handlingDays?: number, labels?: object, metadata?: object, position?: number, serviceLevel?: string, status?: ShippingCarrierStatus, trackingUrlTemplate?: string): Promise<Models.ShippingCarrier>;
+    shippingCarriersCreate(code: string, name: string, countries?: string[], cutoffTime?: string, etaDaysMax?: number, etaDaysMin?: number, externalId?: string, externalRefs?: object, handlingDays?: number, labels?: object, metadata?: object, position?: number, serviceLevel?: string, sourceData?: object, sourceSyncedAt?: string, status?: ShippingCarrierStatus, trackingUrlTemplate?: string): Promise<Models.ShippingCarrier>;
     /**
      * The DACH set — the three German parcel networks, the express carriers, the AT/CH incumbents and the pallet forwarders — each with the tracking template, service level, transit time and pickup cut-off it would be created with. `seeded` marks the four a fresh install already has. Adding a carrier is a data change, never a code change, and a merchant may of course create one that is not in here at all.
      *
@@ -387,20 +542,24 @@ declare class ShippingCarriers {
      */
     shippingCarriersGet(id: string): Promise<Models.ShippingCarrier>;
     /**
-     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. A partial update — send only what changes, which is where a carrier is paused, given a different tracking template, or moved to another pickup cut-off or transit time. This is the one switch that acts on several methods at once, in both directions. Moving `status` off 'active' takes every method that ships with this carrier out of POST /shipping/rates with a reason, which beats disabling each of them and forgetting one; tracking links are deliberately not gated on it, so a retired carrier's old shipments stay resolvable. Editing `cutoff_time`, `handling_days` or `eta_days_min`/`max` MOVES THE PROMISED SHIP DATE of every method that states none of its own: the estimator adds the handling days, then one further day when the cut-off has already passed at the instant being evaluated — compared at or after, in UTC, and as calendar days that do not skip a weekend. Two rows of this tenant may not share `code` — that is the 409.
+     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. A partial update — send only what changes, which is where a carrier is paused, given a different tracking template, or moved to another pickup cut-off or transit time. This is the one switch that acts on several methods at once, in both directions. Moving `status` off 'active' takes every method that ships with this carrier out of POST /shipping/rates with a reason, which beats disabling each of them and forgetting one; tracking links are deliberately not gated on it, so a retired carrier's old shipments stay resolvable. Editing `cutoff_time`, `handling_days` or `eta_days_min`/`max` MOVES THE PROMISED SHIP DATE of every method that states none of its own: the estimator adds the handling days, then one further day when the cut-off has already passed at the instant being evaluated — compared at or after, in UTC, and as calendar days that do not skip a weekend. Two rows of this tenant may not share `code` or `external_id` — that is the 409.
      *
      * @param {string} params.id - The row id.
-     * @param {string} params.code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls). A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field. Deliberately no slug pattern: the column asks only for a non-empty string, and a contract stricter than the implementation would refuse codes merchants already keep.
-     * @param {string[]} params.countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared upper-cased, so a lower-case entry still matches. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
+     * @param {string} params.code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls), in lower case. A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field — and a tracking request finds it by code without regard to case. A code with a capital letter is refused with 400 `invalid_carrier_code`; a carrier stored with one before 1.0 keeps it and keeps resolving.
+     * @param {string[]} params.countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared without regard to case, so a lower-case entry still matches; anything but a two-letter code is refused with 400 `invalid_countries`. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
      * @param {string} params.cutoffTime - This carrier's own daily pickup cut-off, HH:MM in 24-hour form, UTC. Overrides the tenant's cutoff_time for methods on this carrier — one shop-wide time cannot be both DHL's 16:00 and a forwarder's 12:00. Null or the empty string means this carrier declares none; any other shape is a 400, because a cut-off the estimator cannot read is a delivery promise silently computed without one.
      * @param {number} params.etaDaysMax - Transit time upper bound, in calendar days from the ship date.
      * @param {number} params.etaDaysMin - Transit time lower bound, in calendar days from the ship date — inherited by any method on this carrier that states no ETA of its own.
-     * @param {number} params.handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days. Overrides the tenant's handling_days.
+     * @param {string} params.externalId - The key this carrier has in the system that OWNS it — the shipping agent as an ERP numbers it, which is rarely the `code` a merchant types here. Unique per tenant where it is set, so a repeated import upserts on it instead of matching on a name; a carrier created in the Cockpit carries none and never will.
+     * @param {object} params.externalRefs - Every OTHER system that knows this carrier, keyed by system name — a second ERP, a TMS, the label printer's own agent list. `external_id` names the leading system; this is the rest, and the next one costs no column. Answered on read and carrying no query parameter: a jsonb column is compared as a WHOLE document, so a filter over part of one is refused. Look the row up by `external_id` and read this off the answer.
+     * @param {number} params.handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days — a whole number, 0 or more. Overrides the tenant's handling_days.
      * @param {object} params.labels - Localized display names. A flat map keyed by locale — the Cockpit falls back to `en`. Null means the row has no translations and every client shows the untranslated column instead.
      * @param {object} params.metadata - Free-form jsonb the platform never reads or validates — whatever the merchant or their integration needs to keep beside the row (a customer number with the carrier, an ERP key, a label-printer id). The shape varies BY INTEGRATION, not by anything this app knows, so no key is declared and none is reserved; the example is one plausible instance rather than a schema. A flat map of scalars is the convention, and nothing enforces it.
      * @param {string} params.name - Display name, as an operator typed it.
      * @param {number} params.position - Sort order among the carriers; ties fall back to whatever the database returns.
      * @param {string} params.serviceLevel - The class of service this row represents (default 'standard'), as a CODE into the tenant's own service levels (GET /shipping/service-levels). One row is one class: a carrier selling both a parcel and an express product is two rows. Deliberately not an enum here — the set is the merchant's, so a fixed list in this contract would make the gateway reject a level they created. A code the tenant does not keep is a 400 naming the codes they do.
+     * @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 send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so an edit here does not silently throw them away.
+     * @param {string} params.sourceSyncedAt - When this row was last confirmed against its source. A delta run asks the source for what changed since it, and an operator reads it to see that a feed has gone quiet. An edit made HERE does not touch it — it records when the source was last seen, not when the row changed — so a stale value beside a fresh `updated_at` means somebody is maintaining by hand what a feed has stopped delivering.
      * @param {ShippingCarrierStatus} params.status - Whether this carrier may be quoted (default 'active'). Anything else excludes every method that ships with it from POST /shipping/rates, with a reason. Tracking links are NOT gated on it — a retired carrier's old shipments stay resolvable.
      * @param {string} params.trackingUrlTemplate - Tracking page URL with {tracking_code} where the number goes; {postal_code} and {country} are also substituted, URL-encoded. Null for a carrier with no public tracking page.
      * @throws {RevenexxException}
@@ -413,37 +572,45 @@ declare class ShippingCarriers {
         cutoffTime?: string;
         etaDaysMax?: number;
         etaDaysMin?: number;
+        externalId?: string;
+        externalRefs?: object;
         handlingDays?: number;
         labels?: object;
         metadata?: object;
         name?: string;
         position?: number;
         serviceLevel?: string;
+        sourceData?: object;
+        sourceSyncedAt?: string;
         status?: ShippingCarrierStatus;
         trackingUrlTemplate?: string;
     }): Promise<Models.ShippingCarrier>;
     /**
-     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. A partial update — send only what changes, which is where a carrier is paused, given a different tracking template, or moved to another pickup cut-off or transit time. This is the one switch that acts on several methods at once, in both directions. Moving `status` off 'active' takes every method that ships with this carrier out of POST /shipping/rates with a reason, which beats disabling each of them and forgetting one; tracking links are deliberately not gated on it, so a retired carrier's old shipments stay resolvable. Editing `cutoff_time`, `handling_days` or `eta_days_min`/`max` MOVES THE PROMISED SHIP DATE of every method that states none of its own: the estimator adds the handling days, then one further day when the cut-off has already passed at the instant being evaluated — compared at or after, in UTC, and as calendar days that do not skip a weekend. Two rows of this tenant may not share `code` — that is the 409.
+     * A carrier row is one company shipping one class of service: it owns the tracking-URL template, the service level, the transit days, the pickup cut-off and the handling days, and every method that ships with it inherits all of those unless it states its own. A carrier selling both a parcel and an express product is two rows. A partial update — send only what changes, which is where a carrier is paused, given a different tracking template, or moved to another pickup cut-off or transit time. This is the one switch that acts on several methods at once, in both directions. Moving `status` off 'active' takes every method that ships with this carrier out of POST /shipping/rates with a reason, which beats disabling each of them and forgetting one; tracking links are deliberately not gated on it, so a retired carrier's old shipments stay resolvable. Editing `cutoff_time`, `handling_days` or `eta_days_min`/`max` MOVES THE PROMISED SHIP DATE of every method that states none of its own: the estimator adds the handling days, then one further day when the cut-off has already passed at the instant being evaluated — compared at or after, in UTC, and as calendar days that do not skip a weekend. Two rows of this tenant may not share `code` or `external_id` — that is the 409.
      *
      * @param {string} id - The row id.
-     * @param {string} code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls). A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field. Deliberately no slug pattern: the column asks only for a non-empty string, and a contract stricter than the implementation would refuse codes merchants already keep.
-     * @param {string[]} countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared upper-cased, so a lower-case entry still matches. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
+     * @param {string} code - Stable carrier code, unique per tenant (e.g. dhl, dpd, gls), in lower case. A method whose `carrier` text equals this code resolves to this carrier — that is the migration path off the free-text field — and a tracking request finds it by code without regard to case. A code with a capital letter is refused with 400 `invalid_carrier_code`; a carrier stored with one before 1.0 keeps it and keeps resolving.
+     * @param {string[]} countries - The countries this carrier serves. ISO 3166-1 alpha-2 codes; null or an empty array means no restriction. Compared without regard to case, so a lower-case entry still matches; anything but a two-letter code is refused with 400 `invalid_countries`. Declared as an array rather than the bare object a jsonb column derives to — this one is always a list. ANDed with the method's own restriction: a method may not be offered into a country its carrier does not reach.
      * @param {string} cutoffTime - This carrier's own daily pickup cut-off, HH:MM in 24-hour form, UTC. Overrides the tenant's cutoff_time for methods on this carrier — one shop-wide time cannot be both DHL's 16:00 and a forwarder's 12:00. Null or the empty string means this carrier declares none; any other shape is a 400, because a cut-off the estimator cannot read is a delivery promise silently computed without one.
      * @param {number} etaDaysMax - Transit time upper bound, in calendar days from the ship date.
      * @param {number} etaDaysMin - Transit time lower bound, in calendar days from the ship date — inherited by any method on this carrier that states no ETA of its own.
-     * @param {number} handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days. Overrides the tenant's handling_days.
+     * @param {string} externalId - The key this carrier has in the system that OWNS it — the shipping agent as an ERP numbers it, which is rarely the `code` a merchant types here. Unique per tenant where it is set, so a repeated import upserts on it instead of matching on a name; a carrier created in the Cockpit carries none and never will.
+     * @param {object} externalRefs - Every OTHER system that knows this carrier, keyed by system name — a second ERP, a TMS, the label printer's own agent list. `external_id` names the leading system; this is the rest, and the next one costs no column. Answered on read and carrying no query parameter: a jsonb column is compared as a WHOLE document, so a filter over part of one is refused. Look the row up by `external_id` and read this off the answer.
+     * @param {number} handlingDays - Days needed to make a consignment ready for THIS carrier, added to the ship date before the transit days — a whole number, 0 or more. Overrides the tenant's handling_days.
      * @param {object} labels - Localized display names. A flat map keyed by locale — the Cockpit falls back to `en`. Null means the row has no translations and every client shows the untranslated column instead.
      * @param {object} metadata - Free-form jsonb the platform never reads or validates — whatever the merchant or their integration needs to keep beside the row (a customer number with the carrier, an ERP key, a label-printer id). The shape varies BY INTEGRATION, not by anything this app knows, so no key is declared and none is reserved; the example is one plausible instance rather than a schema. A flat map of scalars is the convention, and nothing enforces it.
      * @param {string} name - Display name, as an operator typed it.
      * @param {number} position - Sort order among the carriers; ties fall back to whatever the database returns.
      * @param {string} serviceLevel - The class of service this row represents (default 'standard'), as a CODE into the tenant's own service levels (GET /shipping/service-levels). One row is one class: a carrier selling both a parcel and an express product is two rows. Deliberately not an enum here — the set is the merchant's, so a fixed list in this contract would make the gateway reject a level they created. A code the tenant does not keep is a 400 naming the codes they do.
+     * @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 send back in `If-Match`, and there is nowhere else to keep it between two runs. `raw` holds the source fields this app does not model, so an edit here does not silently throw them away.
+     * @param {string} sourceSyncedAt - When this row was last confirmed against its source. A delta run asks the source for what changed since it, and an operator reads it to see that a feed has gone quiet. An edit made HERE does not touch it — it records when the source was last seen, not when the row changed — so a stale value beside a fresh `updated_at` means somebody is maintaining by hand what a feed has stopped delivering.
      * @param {ShippingCarrierStatus} status - Whether this carrier may be quoted (default 'active'). Anything else excludes every method that ships with it from POST /shipping/rates, with a reason. Tracking links are NOT gated on it — a retired carrier's old shipments stay resolvable.
      * @param {string} trackingUrlTemplate - Tracking page URL with {tracking_code} where the number goes; {postal_code} and {country} are also substituted, URL-encoded. Null for a carrier with no public tracking page.
      * @throws {RevenexxException}
      * @returns {Promise<Models.ShippingCarrier>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    shippingCarriersUpdate(id: string, code?: string, countries?: string[], cutoffTime?: string, etaDaysMax?: number, etaDaysMin?: number, handlingDays?: number, labels?: object, metadata?: object, name?: string, position?: number, serviceLevel?: string, status?: ShippingCarrierStatus, trackingUrlTemplate?: string): Promise<Models.ShippingCarrier>;
+    shippingCarriersUpdate(id: string, code?: string, countries?: string[], cutoffTime?: string, etaDaysMax?: number, etaDaysMin?: number, externalId?: string, externalRefs?: object, handlingDays?: number, labels?: object, metadata?: object, name?: string, position?: number, serviceLevel?: string, sourceData?: object, sourceSyncedAt?: string, status?: ShippingCarrierStatus, trackingUrlTemplate?: string): Promise<Models.ShippingCarrier>;
     /**
      * Hand in a carrier code and the tracking number printed on the label, and this answers the URL a buyer follows. The carrier owns the URL format, so nobody else has to. `order_shipments` stores a tracking_url per shipment today, which is one carrier's URL shape copied into every row — the day it changes, every historic link is wrong. Ask here instead. Tracking is NOT gated on carrier status: a retired carrier's old shipments stay resolvable.
      *