@revenexx/node 0.1.1 → 0.2.0

package/dist/services/customers.d.ts

@@ -1,6 +1,10 @@
 import { Client } from '../client.js';
 import { Models } from '../models.js';
+import { Factor } from '../enums/factor.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';
@@ -14,12 +18,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';
@@ -47,18 +62,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';
@@ -68,6 +109,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';
@@ -75,6 +117,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';
@@ -91,28 +134,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';
@@ -134,6 +189,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';
@@ -145,22 +201,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';
@@ -190,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';
@@ -245,27 +386,55 @@ declare class Customers {
     client: Client;
     constructor(client: Client);
     /**
-     * An email and a password go in; a session and the CONTACT behind it come back, so a storefront knows in one call both that the buyer is signed in and who they are. The session is minted server-side rather than handed back from the credential check, because the account route hides the session secret from non-privileged responses and a trusted BFF needs it. `permissions` carries the buyer's effective grants, so a BFF does not need a second call to decide what to render.
+     * The same token `POST /customers/auth/magic-link` mints, answered WITH its secret instead of mailed — for a buyer another system has already authenticated and who therefore has no mailbox to check and no link to click. Punchout is the caller it exists for: an ERP hands its user over, this app decides whether that buyer may sign in, and the secret is redeemed through `PUT /customers/auth/magic-link` exactly as a mailed one is. Which is also why the method checked is the magic-link one: a store with `login_magic_link` off cannot redeem what this mints. Nothing is delivered, no account is founded (an address nobody holds is a 404 here, not a registration) and no `contact_event` is written — signing in is mechanics, and this app keeps it off the event bus. Not callable from a browser or a storefront: `handoff_key` is an operations secret configured on the calling app, and a deployment that has none has this capability switched off.
+     *
+     * @param {string} params.handoffKey - The operations secret that makes the caller a trusted in-cluster app. Configured on both functions; never a value a browser or a storefront holds. In the body rather than a header because the gateway forwards a fixed header set, the same reason session material travels this way.
+     * @param {string} params.contactId - The buyer to sign in, as this app knows them. Exactly one of this and `email` is sent — this one when the caller already resolved the external name to a contact.
+     * @param {string} params.email - The buyer to sign in, by address, when the caller holds no contact id. Exactly one of this and `contact_id` is sent. An address nobody holds is a 404 — this route never registers.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.AuthHandoffResponse>}
+     */
+    customersAuthHandoff(params: {
+        handoffKey: string;
+        contactId?: string;
+        email?: string;
+    }): Promise<Models.AuthHandoffResponse>;
+    /**
+     * The same token `POST /customers/auth/magic-link` mints, answered WITH its secret instead of mailed — for a buyer another system has already authenticated and who therefore has no mailbox to check and no link to click. Punchout is the caller it exists for: an ERP hands its user over, this app decides whether that buyer may sign in, and the secret is redeemed through `PUT /customers/auth/magic-link` exactly as a mailed one is. Which is also why the method checked is the magic-link one: a store with `login_magic_link` off cannot redeem what this mints. Nothing is delivered, no account is founded (an address nobody holds is a 404 here, not a registration) and no `contact_event` is written — signing in is mechanics, and this app keeps it off the event bus. Not callable from a browser or a storefront: `handoff_key` is an operations secret configured on the calling app, and a deployment that has none has this capability switched off.
+     *
+     * @param {string} handoffKey - The operations secret that makes the caller a trusted in-cluster app. Configured on both functions; never a value a browser or a storefront holds. In the body rather than a header because the gateway forwards a fixed header set, the same reason session material travels this way.
+     * @param {string} contactId - The buyer to sign in, as this app knows them. Exactly one of this and `email` is sent — this one when the caller already resolved the external name to a contact.
+     * @param {string} email - The buyer to sign in, by address, when the caller holds no contact id. Exactly one of this and `contact_id` is sent. An address nobody holds is a 404 — this route never registers.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.AuthHandoffResponse>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    customersAuthHandoff(handoffKey: string, contactId?: string, email?: string): Promise<Models.AuthHandoffResponse>;
+    /**
+     * An identifier — email address, username or customer number, as the shop allows — and a password go in; a session and the CONTACT behind it come back, so a storefront knows in one call both that the buyer is signed in and who they are. The session is minted server-side rather than handed back from the credential check, because the account route hides the session secret from non-privileged responses and a trusted BFF needs it. `permissions` carries the buyer's effective grants, so a BFF does not need a second call to decide what to render.
      *
-     * @param {string} params.email - The buyer's login address — the same one the contact carries.
      * @param {string} params.password - The password from registration or recovery. Wrong credentials are a 401; a correct one on an undecided application is a 403.
+     * @param {string} params.email - Deprecated alias of `identifier`, kept so every storefront written against the earlier contract keeps working. Read exactly like `identifier` — an address, a username or a customer number — and ignored when `identifier` is sent too.
+     * @param {string} params.identifier - Who is signing in: the buyer's email address, their username, or their company's customer number. Which of the three a shop accepts is the merchant's choice (`login_identifier_email`, `login_identifier_username`, `login_identifier_customer_number`); a shape the shop does not accept is a 403 `identifier_not_offered`. The shape is read from the value — anything holding an `@` is an address, only digits is a customer number, anything else a username. A customer number names a COMPANY and signs in as its primary contact, which makes it a shared account.
      * @throws {RevenexxException}
      * @returns {Promise<Models.AuthLoginResponse>}
      */
     customersAuthLogin(params: {
-        email: string;
         password: string;
+        email?: string;
+        identifier?: string;
     }): Promise<Models.AuthLoginResponse>;
     /**
-     * An email and a password go in; a session and the CONTACT behind it come back, so a storefront knows in one call both that the buyer is signed in and who they are. The session is minted server-side rather than handed back from the credential check, because the account route hides the session secret from non-privileged responses and a trusted BFF needs it. `permissions` carries the buyer's effective grants, so a BFF does not need a second call to decide what to render.
+     * An identifier — email address, username or customer number, as the shop allows — and a password go in; a session and the CONTACT behind it come back, so a storefront knows in one call both that the buyer is signed in and who they are. The session is minted server-side rather than handed back from the credential check, because the account route hides the session secret from non-privileged responses and a trusted BFF needs it. `permissions` carries the buyer's effective grants, so a BFF does not need a second call to decide what to render.
      *
-     * @param {string} email - The buyer's login address — the same one the contact carries.
      * @param {string} password - The password from registration or recovery. Wrong credentials are a 401; a correct one on an undecided application is a 403.
+     * @param {string} email - Deprecated alias of `identifier`, kept so every storefront written against the earlier contract keeps working. Read exactly like `identifier` — an address, a username or a customer number — and ignored when `identifier` is sent too.
+     * @param {string} identifier - Who is signing in: the buyer's email address, their username, or their company's customer number. Which of the three a shop accepts is the merchant's choice (`login_identifier_email`, `login_identifier_username`, `login_identifier_customer_number`); a shape the shop does not accept is a 403 `identifier_not_offered`. The shape is read from the value — anything holding an `@` is an address, only digits is a customer number, anything else a username. A customer number names a COMPANY and signs in as its primary contact, which makes it a shared account.
      * @throws {RevenexxException}
      * @returns {Promise<Models.AuthLoginResponse>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    customersAuthLogin(email: string, password: string): Promise<Models.AuthLoginResponse>;
+    customersAuthLogin(password: string, email?: string, identifier?: string): Promise<Models.AuthLoginResponse>;
     /**
      * Ends ONE session — the buyer signs out on this device and stays signed in on the others, because the session id is what is revoked and not the account. The contact row is untouched: signing out is not blocking, and a caller wanting the second thing wants `status: "blocked"` on the contact instead. Both ids come from what `/customers/auth/login` answered, and a BFF should drop its own cookie whatever this answers — the session is unusable afterwards either way.
      *
@@ -289,9 +458,9 @@ declare class Customers {
      */
     customersAuthLogout(sessionId: string, userId: string): Promise<{}>;
     /**
-     * Sign in without a password: a link goes to the address, and `PUT /customers/auth/magic-link` turns it into a session. Creates the account when the address is new, which makes this a registration path as much as a sign-in one — and why an address nobody holds is not distinguished in the answer. The mail is this shop's own template through the messaging service; the secret is not in this response, only in the link.
+     * Sign in without a password: a link goes to the address, and `PUT /customers/auth/magic-link` turns it into a session. Only a buyer this shop holds, with a login, who may sign in is sent one. For anybody else — an address nobody holds, a contact with no login, a blocked buyer or company, an undecided application — nothing is created and nothing is sent, and the answer is the same 201 in the same shape, so it cannot be used to find out who is a customer. It never founds an account. The mail is this shop's own template through the messaging service; the secret is not in this response, only in the link.
      *
-     * @param {string} params.email - Who to send the link to. An address that has never been seen creates an account rather than failing.
+     * @param {string} params.email - Who to send the link to. An address that cannot sign in is answered exactly like one that can, and nothing is sent to it.
      * @param {string} params.url - Where the mailed link points. `userId`, `secret` and `expire` are appended as query parameters; the first two are what the confirm call takes.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthMagicLinkResponse>}
@@ -301,9 +470,9 @@ declare class Customers {
         url: string;
     }): Promise<Models.DefaultAuthMagicLinkResponse>;
     /**
-     * Sign in without a password: a link goes to the address, and `PUT /customers/auth/magic-link` turns it into a session. Creates the account when the address is new, which makes this a registration path as much as a sign-in one — and why an address nobody holds is not distinguished in the answer. The mail is this shop's own template through the messaging service; the secret is not in this response, only in the link.
+     * Sign in without a password: a link goes to the address, and `PUT /customers/auth/magic-link` turns it into a session. Only a buyer this shop holds, with a login, who may sign in is sent one. For anybody else — an address nobody holds, a contact with no login, a blocked buyer or company, an undecided application — nothing is created and nothing is sent, and the answer is the same 201 in the same shape, so it cannot be used to find out who is a customer. It never founds an account. The mail is this shop's own template through the messaging service; the secret is not in this response, only in the link.
      *
-     * @param {string} email - Who to send the link to. An address that has never been seen creates an account rather than failing.
+     * @param {string} email - Who to send the link to. An address that cannot sign in is answered exactly like one that can, and nothing is sent to it.
      * @param {string} url - Where the mailed link points. `userId`, `secret` and `expire` are appended as query parameters; the first two are what the confirm call takes.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthMagicLinkResponse>}
@@ -335,47 +504,47 @@ declare class Customers {
     /**
      * The platform user, the customer record mirrored against it and the effective grants, in one call. The expected caller is a trusted storefront BFF holding the session on the buyer's behalf, which is why the ids travel in the body rather than in a browser-facing header. The grants are derived here on every call rather than returned from anywhere they could be cached, so a role changed a second ago is already reflected.
      *
+     * @param {string} params.sessionId - The session the storefront holds for that user — `session.$id` from the login. A revoked or expired one is a 401.
      * @param {string} params.userId - The platform user to resolve — `session.userId` from the login.
-     * @param {string} params.sessionId - Optional session to verify. Pass it to ask "is this session still alive?" (a revoked one is then a 401); omit it to only ask who a user is.
      * @throws {RevenexxException}
      * @returns {Promise<Models.AuthMeResponse>}
      */
     customersAuthMe(params: {
+        sessionId: string;
         userId: string;
-        sessionId?: string;
     }): Promise<Models.AuthMeResponse>;
     /**
      * The platform user, the customer record mirrored against it and the effective grants, in one call. The expected caller is a trusted storefront BFF holding the session on the buyer's behalf, which is why the ids travel in the body rather than in a browser-facing header. The grants are derived here on every call rather than returned from anywhere they could be cached, so a role changed a second ago is already reflected.
      *
+     * @param {string} sessionId - The session the storefront holds for that user — `session.$id` from the login. A revoked or expired one is a 401.
      * @param {string} userId - The platform user to resolve — `session.userId` from the login.
-     * @param {string} sessionId - Optional session to verify. Pass it to ask "is this session still alive?" (a revoked one is then a 401); omit it to only ask who a user is.
      * @throws {RevenexxException}
      * @returns {Promise<Models.AuthMeResponse>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    customersAuthMe(userId: string, sessionId?: string): Promise<Models.AuthMeResponse>;
+    customersAuthMe(sessionId: string, userId: string): Promise<Models.AuthMeResponse>;
     /**
      * Between the password and the finished session: the buyer has proved one thing and is asked for another. Created by user id, because the account route that creates challenges hides the code from whoever may call it — and answered with the half-finished session the sign-in is in the middle of, through `PUT /customers/auth/mfa/challenge`. Needs a platform build that returns the challenge code; without one there is no way to read what to send, and the call answers 502 rather than mailing an empty challenge.
      *
      * @param {string} params.userId - The platform user being challenged.
-     * @param {string} params.factor - Which factor to challenge. Defaults to `email`, the only one this route mails.
+     * @param {Factor} params.factor - Which factor to challenge. `email` (the default) is the only one this route sends; any other value is a 400 `factor_not_supported`.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthMfaChallengeResponse>}
      */
     customersAuthMfaChallenge(params: {
         userId: string;
-        factor?: string;
+        factor?: Factor;
     }): Promise<Models.DefaultAuthMfaChallengeResponse>;
     /**
      * Between the password and the finished session: the buyer has proved one thing and is asked for another. Created by user id, because the account route that creates challenges hides the code from whoever may call it — and answered with the half-finished session the sign-in is in the middle of, through `PUT /customers/auth/mfa/challenge`. Needs a platform build that returns the challenge code; without one there is no way to read what to send, and the call answers 502 rather than mailing an empty challenge.
      *
      * @param {string} userId - The platform user being challenged.
-     * @param {string} factor - Which factor to challenge. Defaults to `email`, the only one this route mails.
+     * @param {Factor} factor - Which factor to challenge. `email` (the default) is the only one this route sends; any other value is a 400 `factor_not_supported`.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthMfaChallengeResponse>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    customersAuthMfaChallenge(userId: string, factor?: string): Promise<Models.DefaultAuthMfaChallengeResponse>;
+    customersAuthMfaChallenge(userId: string, factor?: Factor): Promise<Models.DefaultAuthMfaChallengeResponse>;
     /**
      * The code the buyer typed, against the challenge it was sent for. The session becomes fully authenticated when this answers.
      *
@@ -405,9 +574,9 @@ declare class Customers {
      */
     customersAuthMfaChallengeConfirm(challengeId: string, code: string, sessionSecret: string, userId?: string): Promise<Models.DefaultAuthMfaChallengeConfirmResponse>;
     /**
-     * The same token as the sign-in link, delivered as a short code instead — for a buyer on a phone, where leaving for a mail client and coming back loses the checkout they were in the middle of. Redeemed with `PUT /customers/auth/otp`.
+     * The same token as the sign-in link, delivered as a short code instead — for a buyer on a phone, where leaving for a mail client and coming back loses the checkout they were in the middle of. Redeemed with `PUT /customers/auth/otp`. Sent under the same rule as the link: only to a buyer who may sign in, and for anybody else nothing is created or sent while the answer looks exactly the same.
      *
-     * @param {string} params.email - Who to send the code to. As with the sign-in link, an unknown address creates an account rather than failing.
+     * @param {string} params.email - Who to send the code to. As with the sign-in link, an address that cannot sign in is answered exactly like one that can, and nothing is sent to it.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthOtpResponse>}
      */
@@ -415,9 +584,9 @@ declare class Customers {
         email: string;
     }): Promise<Models.DefaultAuthOtpResponse>;
     /**
-     * The same token as the sign-in link, delivered as a short code instead — for a buyer on a phone, where leaving for a mail client and coming back loses the checkout they were in the middle of. Redeemed with `PUT /customers/auth/otp`.
+     * The same token as the sign-in link, delivered as a short code instead — for a buyer on a phone, where leaving for a mail client and coming back loses the checkout they were in the middle of. Redeemed with `PUT /customers/auth/otp`. Sent under the same rule as the link: only to a buyer who may sign in, and for anybody else nothing is created or sent while the answer looks exactly the same.
      *
-     * @param {string} email - Who to send the code to. As with the sign-in link, an unknown address creates an account rather than failing.
+     * @param {string} email - Who to send the code to. As with the sign-in link, an address that cannot sign in is answered exactly like one that can, and nothing is sent to it.
      * @throws {RevenexxException}
      * @returns {Promise<Models.DefaultAuthOtpResponse>}
      * @deprecated Use the object parameter style method for a better developer experience.
@@ -446,7 +615,7 @@ declare class Customers {
      */
     customersAuthOtpConfirm(secret: string, userId: string): Promise<Models.AuthOtpConfirmResponse>;
     /**
-     * Step one of two: a link goes to the address given, and `PUT /customers/auth/recovery` is what the buyer's browser comes back to. The identity service mints the token; the MAIL is this shop's own — the tenant's template, layout, language and sending domain, through the messaging service. The secret is NOT in this answer: it exists only inside the mailed link, which is the whole point of the two-step shape, and echoing it here would make the mail decorative. Nothing about the contact changes; the password only moves in step two.
+     * Step one of two: a link goes to the address given, and `PUT /customers/auth/recovery` is what the buyer's browser comes back to. The identity service mints the token; the MAIL is this shop's own — the tenant's template, layout, language and sending domain, through the messaging service. The secret is NOT in this answer: it exists only inside the mailed link, which is the whole point of the two-step shape, and echoing it here would make the mail decorative. One thing about the contact CAN change: a buyer this shop holds who carries no platform login — an address written straight into the record by an import — is given one here, because the alternative is telling the one person who cannot help themselves that no account exists, with no other way in. Nothing else about the contact moves, and the password only moves in step two.
      *
      * @param {string} params.email - Who to send the recovery mail to. An address nobody holds is not distinguished here — do not build an account-existence check on the answer.
      * @param {string} params.url - Where the mailed link points. `userId`, `secret` and `expire` are appended as query parameters — the first two are what the confirm call takes. Same shape the identity service's own mail used, so a storefront that already handles that link needs no change.
@@ -458,7 +627,7 @@ declare class Customers {
         url: string;
     }): Promise<Models.DefaultAuthRecoveryResponse>;
     /**
-     * Step one of two: a link goes to the address given, and `PUT /customers/auth/recovery` is what the buyer's browser comes back to. The identity service mints the token; the MAIL is this shop's own — the tenant's template, layout, language and sending domain, through the messaging service. The secret is NOT in this answer: it exists only inside the mailed link, which is the whole point of the two-step shape, and echoing it here would make the mail decorative. Nothing about the contact changes; the password only moves in step two.
+     * Step one of two: a link goes to the address given, and `PUT /customers/auth/recovery` is what the buyer's browser comes back to. The identity service mints the token; the MAIL is this shop's own — the tenant's template, layout, language and sending domain, through the messaging service. The secret is NOT in this answer: it exists only inside the mailed link, which is the whole point of the two-step shape, and echoing it here would make the mail decorative. One thing about the contact CAN change: a buyer this shop holds who carries no platform login — an address written straight into the record by an import — is given one here, because the alternative is telling the one person who cannot help themselves that no account exists, with no other way in. Nothing else about the contact moves, and the password only moves in step two.
      *
      * @param {string} email - Who to send the recovery mail to. An address nobody holds is not distinguished here — do not build an account-existence check on the answer.
      * @param {string} url - Where the mailed link points. `userId`, `secret` and `expire` are appended as query parameters — the first two are what the confirm call takes. Same shape the identity service's own mail used, so a storefront that already handles that link needs no change.
@@ -500,7 +669,7 @@ declare class Customers {
      * @param {string} params.firstName - Given name. Optional: an ERP import often has only a mailbox.
      * @param {string} params.lastName - Family name. Optional for the same reason.
      * @param {string} params.locale - The language this person is written to in — BCP 47, and one of the store's configured locales. Null falls back to the store default. One of the store's own locales, or the call is a 400.
-     * @param {string} params.organizationId - JOIN an existing company — the invite shape. Neither b2b_registration_enabled nor b2c_registration_enabled applies to it.
+     * @param {string} params.organizationId - REFUSED when set: joining an existing company is an invitation, not a registration, so a value here answers 403 `join_requires_invitation` (400 `organization_ambiguous` beside `organization_name`). Send null or leave it out.
      * @param {string} params.organizationName - FOUND a new company, with this contact as its admin. This is what makes the registration a B2B one; leaving it out registers a standalone buyer.
      * @param {string} params.url - Where the welcome mail's button points — the buyer's first stop in this shop. Absent, the mail still goes out and simply carries no button. Ignored when the registration is an APPLICATION: there is no account to send anybody to yet.
      * @param {string} params.vatId - VAT identification number (USt-IdNr. in Germany) — the closest thing a B2B buyer has to a legal identity. Validated against the EU VIES service when the tenant's `organization_vat_id_required` setting is on, and stored verbatim otherwise, including for buyers outside the EU. Required when the tenant's `organization_vat_id_required` is on, and checked BEFORE the company is created so a bad one leaves no half-founded organization behind.
@@ -528,7 +697,7 @@ declare class Customers {
      * @param {string} firstName - Given name. Optional: an ERP import often has only a mailbox.
      * @param {string} lastName - Family name. Optional for the same reason.
      * @param {string} locale - The language this person is written to in — BCP 47, and one of the store's configured locales. Null falls back to the store default. One of the store's own locales, or the call is a 400.
-     * @param {string} organizationId - JOIN an existing company — the invite shape. Neither b2b_registration_enabled nor b2c_registration_enabled applies to it.
+     * @param {string} organizationId - REFUSED when set: joining an existing company is an invitation, not a registration, so a value here answers 403 `join_requires_invitation` (400 `organization_ambiguous` beside `organization_name`). Send null or leave it out.
      * @param {string} organizationName - FOUND a new company, with this contact as its admin. This is what makes the registration a B2B one; leaving it out registers a standalone buyer.
      * @param {string} url - Where the welcome mail's button points — the buyer's first stop in this shop. Absent, the mail still goes out and simply carries no button. Ignored when the registration is an APPLICATION: there is no account to send anybody to yet.
      * @param {string} vatId - VAT identification number (USt-IdNr. in Germany) — the closest thing a B2B buyer has to a legal identity. Validated against the EU VIES service when the tenant's `organization_vat_id_required` setting is on, and stored verbatim otherwise, including for buyers outside the EU. Required when the tenant's `organization_vat_id_required` is on, and checked BEFORE the company is created so a bad one leaves no half-founded organization behind.
@@ -583,24 +752,27 @@ declare class Customers {
      */
     customersAuthVerificationConfirm(secret: string, userId: string): Promise<Models.DefaultAuthVerificationConfirmResponse>;
     /**
-     * The capability the API gateway calls to turn a caller's X-Revenexx-Principal assertion into the permission set it forwards to every other app as X-Revenexx-Permissions. This app is the platform's role provider (manifest#provides_roles), and this is the hot path of every attributed storefront request — one contact read plus the tenant's role map. A blocked or pending contact always resolves with active=false; what its `permissions` then say is the tenant's blocked_contact_behavior setting — 'keep' (the default, the role's grants), 'catalog_only' or 'deny_all'.
+     * The capability the API gateway calls to turn whoever is acting into the permission set it forwards to every other app as X-Revenexx-Permissions. This app is the platform's role provider (manifest#provides_roles), and this is the hot path of every attributed request — one contact read plus the tenant's role map. Send EXACTLY ONE of two references. `contact_id` is the storefront plane: a BFF holding the tenant API key asserted a contact, and the gateway is resolving the assertion. `user_id` is the authenticated plane (RAD-12): the gateway verified a person's own Zitadel token and is resolving its subject against `contacts.external_user_id`, so the answer stands on a proven identity rather than a claimed one. The answer is the same shape either way — which plane a request came from is the gateway's business, not this app's. A blocked or pending contact always resolves with active=false; what its `permissions` then say is the tenant's blocked_contact_behavior setting — 'keep' (the default, the role's grants), 'catalog_only' or 'deny_all'.
      *
-     * @param {string} params.contactId - The contact the caller is acting for.
+     * @param {string} params.contactId - The contact the caller asserted it is acting for.
+     * @param {string} params.userId - The platform login the gateway authenticated, matched against `contacts.external_user_id` — the identity mirror this app maintains when it registers or invites a contact. Not a uuid: it is whatever the identity service issues as a subject.
      * @throws {RevenexxException}
      * @returns {Promise<Models.ContactPermissions>}
      */
-    customersPrincipalResolve(params: {
-        contactId: string;
+    customersPrincipalResolve(params?: {
+        contactId?: string;
+        userId?: string;
     }): Promise<Models.ContactPermissions>;
     /**
-     * The capability the API gateway calls to turn a caller's X-Revenexx-Principal assertion into the permission set it forwards to every other app as X-Revenexx-Permissions. This app is the platform's role provider (manifest#provides_roles), and this is the hot path of every attributed storefront request — one contact read plus the tenant's role map. A blocked or pending contact always resolves with active=false; what its `permissions` then say is the tenant's blocked_contact_behavior setting — 'keep' (the default, the role's grants), 'catalog_only' or 'deny_all'.
+     * The capability the API gateway calls to turn whoever is acting into the permission set it forwards to every other app as X-Revenexx-Permissions. This app is the platform's role provider (manifest#provides_roles), and this is the hot path of every attributed request — one contact read plus the tenant's role map. Send EXACTLY ONE of two references. `contact_id` is the storefront plane: a BFF holding the tenant API key asserted a contact, and the gateway is resolving the assertion. `user_id` is the authenticated plane (RAD-12): the gateway verified a person's own Zitadel token and is resolving its subject against `contacts.external_user_id`, so the answer stands on a proven identity rather than a claimed one. The answer is the same shape either way — which plane a request came from is the gateway's business, not this app's. A blocked or pending contact always resolves with active=false; what its `permissions` then say is the tenant's blocked_contact_behavior setting — 'keep' (the default, the role's grants), 'catalog_only' or 'deny_all'.
      *
-     * @param {string} contactId - The contact the caller is acting for.
+     * @param {string} contactId - The contact the caller asserted it is acting for.
+     * @param {string} userId - The platform login the gateway authenticated, matched against `contacts.external_user_id` — the identity mirror this app maintains when it registers or invites a contact. Not a uuid: it is whatever the identity service issues as a subject.
      * @throws {RevenexxException}
      * @returns {Promise<Models.ContactPermissions>}
      * @deprecated Use the object parameter style method for a better developer experience.
      */
-    customersPrincipalResolve(contactId: string): Promise<Models.ContactPermissions>;
+    customersPrincipalResolve(contactId?: string, userId?: string): Promise<Models.ContactPermissions>;
 }
 
 export { Customers };