btrz-api-client 8.31.0 → 8.32.0

package/src/endpoints/accounts/applications.js

@@ -1,7 +1,8 @@
+/* eslint-disable max-len */
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
 /**
- * Factory for applications (by id/name) API (btrz-api-accounts).
+ * Factory for applications API (btrz-api-accounts): get by id or by name. Requires BETTEREZ_APP or MOBILE_SCANNER (get by id); get by name requires authentication.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -9,13 +10,13 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function applicationsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /applications/:id - get an application by id.
+   * GET /applications/:id - get an application by id. Application must belong to the authenticated account.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Application id (ObjectId)
+   * @param {string} opts.id - Application id (24-char hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse>} Response data: { application } (full application document including privateKey)
    */
   function get({token, id, jwtToken, headers}) {
     return client.get(`/applications/${id}`, {
@@ -23,13 +24,13 @@ function applicationsFactory({client, internalAuthTokenProvider}) {
     });
   }
   /**
-   * GET /applications/name/:appName - get an application by name.
+   * GET /applications/name/:appName - get an application by name. Returns non-internal, non-deleted application for the account; response excludes privateKey.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.appName - Application name
+   * @param {string} opts.appName - Application name (exact match)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse>} Response data: { application } (application document without privateKey)
    */
   function getByName({token, appName, jwtToken, headers}) {
     return client.get(`/applications/name/${appName}`, {

package/src/endpoints/accounts/customers.js

@@ -1,15 +1,16 @@
+/* eslint-disable max-len */
 const base64 = require("base-64");
 const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
 /**
- * Query params for GET /customers (btrz-api-accounts). See get-customers getSpec().
+ * Query params for GET /customers (btrz-api-accounts). Response is paginated (customers array + pagination).
  * @typedef {Object} CustomersQuery
- * @property {string} [customerNumber] - A particular customer number; only that customer will be listed
- * @property {string} [externalId] - A particular externalId (same format as when creating the customer)
- * @property {string} [providerIds] - Provider ids to get customers from (comma-separated if more than one)
- * @property {string} [lookupSearchParams] - Lookup search data in format "documentTypeId|DNI,documentNumber|1234567"
+ * @property {string} [customerNumber] - Filter: only that customer will be listed
+ * @property {string} [externalId] - Filter: same format as when creating the customer; only that customer listed
+ * @property {string} [providerIds] - Filter: provider ids to get customers from (comma-separated)
+ * @property {string} [lookupSearchParams] - Lookup search in format "documentTypeId|DNI,documentNumber|1234567" (documentNumber required)
  */
 
 /**
@@ -21,14 +22,14 @@ const {
  */
 function customersFactory({client, internalAuthTokenProvider}) {
   /**
-   * PUT /customers/:customerId - update a customer (full replace).
+   * PUT /customers/:customerId - update a customer (full replace). Requires BETTEREZ_APP or CUSTOMER audience; customer token may only update own record. Side effect: may emit customer.updated webhook.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.customerId - Customer id (ObjectId)
-   * @param {Object} opts.customer - Customer payload
+   * @param {string} opts.customerId - Customer id (24-char hex ObjectId)
+   * @param {Object} opts.customer - Customer payload (CustomerData)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ _id: string, customerNumber: string, ... }>>}
    */
   function put({customerId, customer, token, jwtToken, headers}) {
     return client({
@@ -40,14 +41,14 @@ function customersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /customers - list customers.
+   * GET /customers - list customers (paginated). Optional filters: customerNumber, externalId, providerIds, lookupSearchParams.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {CustomersQuery} [opts.query] - Query params (customerNumber, externalId, providerIds, lookupSearchParams)
-   * @param {string} [opts.providerId] - Provider id; if set, added to query (convenience for single provider)
+   * @param {CustomersQuery} [opts.query] - Query params; API expects providerIds (comma-separated). Use providerId to send a single id.
+   * @param {string} [opts.providerId] - Convenience: added to query as providerId (single provider)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ customers: Array<object>, total: number, ... }>>}
    */
   function all({token, jwtToken, query = {}, headers, providerId}) {
     const query_ = providerId ? {...query, providerId} : query;
@@ -59,13 +60,14 @@ function customersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /customer - create a customer.
+   * POST /customer - create a customer. Body: { customer }. If password is included, activation token is created and activation email sent. Side effect: may emit customer.created webhook.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.customer - Customer payload
+   * @param {Object} opts.customer - Customer payload (CustomerPost); email, firstName, lastName required
+   * @param {Object} [opts.query] - Optional: uniqueEmail, lang, channel, platform, appVersion, appName, activateIfExists
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ _id: string, customerNumber: string, ... }>>}
    */
   function create({customer, token, jwtToken, query, headers}) {
     return client({
@@ -125,14 +127,15 @@ function customersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PATCH /customers/:customerId - partial update a customer.
+   * PATCH /customers/:customerId - apply operations (activate, reset password, activateEmailAndPwd). Body: { operations } array of PatchCustomerOperation. Returns Customer and auth tokens. Side effect: may emit customer.updated webhook.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.customerId - Customer id (ObjectId)
-   * @param {Object} opts.data - Partial customer payload
+   * @param {string} opts.customerId - Customer id (24-char hex ObjectId)
+   * @param {Object} opts.data - Body: { operations } or array of { op, path, value }
+   * @param {Object} [opts.query] - Optional query
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<CustomerWithAuthToken>>}
    */
   function update({customerId, token, jwtToken, data, query, headers}) {
     return client({
@@ -145,13 +148,13 @@ function customersFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /customers/merge - merge source customers into destination.
+   * POST /customers/merge - merge source customers into destination. Requires BETTEREZ_APP. Side effect: emits customers.merged webhook.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.destinationCustomerId - Destination customer id (ObjectId)
-   * @param {Array<string>} opts.sourceCustomerIds - Source customer ids (ObjectIds)
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @param {string} opts.destinationCustomerId - Destination customer id (24-char hex ObjectId)
+   * @param {Array<string>} opts.sourceCustomerIds - Source customer ids (24-char hex ObjectIds)
+   * @returns {Promise<import("axios").AxiosResponse<{ customerMerge: object }>>}
    */
   function merge({destinationCustomerId, sourceCustomerIds, jwtToken, token}) {
     return client({

package/src/endpoints/accounts/domains.js

@@ -4,6 +4,7 @@ const {
 
 /**
  * Factory for domains API (btrz-api-accounts).
+ * Endpoints manage subdomains for the account: list, create (with DNS and websales config), and delete.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -11,11 +12,12 @@ const {
  */
 function domainsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /domains - list domains. API does not accept query params.
+   * GET /domains – List all domain names for the current account.
+   * Response body is an array of strings (primary domain first, then secondary domains). No query parameters.
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
+   * @param {string} [opts.token] - API key (X-API-KEY)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<string[]>>} response.data is string[]
    */
   function all({token, query = {}, headers}) {
     return client({
@@ -26,13 +28,14 @@ function domainsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /domains - create a domain.
+   * POST /domains – Create a new subdomain for the account.
+   * Adds DNS CNAME and default websales config. Requires BETTEREZ_APP JWT. Emits domains.created (and websalesConfig.created) webhooks.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Domain payload
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {Object} opts.data - Body: { domain } or { domainInfo: { domain } }. domain must match pattern (no dots, no underscores).
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ domain: string }>>} response.data is AddedDomainResponse
    */
   function create({data, token, jwtToken, headers}) {
     return client({
@@ -44,13 +47,15 @@ function domainsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * DELETE /domains/:domain - remove a domain.
+   * DELETE /domains/:domain – Remove a subdomain from the account.
+   * Removes DNS entry, websales config, and domain from payment methods and inventory products.
+   * Primary domain cannot be deleted. Emits domains.deleted and websalesConfig.deleted.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.domain - Domain name
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {string} opts.domain - Domain name (path parameter)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ domain: string }>>} response.data is DeletedDomainResponse
    */
   function remove({domain, token, jwtToken, headers}) {
     return client({

package/src/endpoints/accounts/email-settings.js

@@ -3,6 +3,7 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
 /**
  * Factory for email-settings API (btrz-api-accounts).
+ * Manage account email settings (identity/verified senders). Path parameter is email address.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -10,12 +11,13 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function emailSettingsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /email-settings - list email settings. API does not accept query params.
+   * GET /email-settings – List all email settings for the account.
+   * Response may trigger AWS verification and commIdentity updates. No query params.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ emailSettings: object[] }>>}
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({
@@ -25,13 +27,13 @@ function emailSettingsFactory({client, internalAuthTokenProvider}) {
     });
   }
   /**
-   * GET /email-settings/:email - get email settings by email. API does not accept query params.
+   * GET /email-settings/:email – Get one email setting by email address (path param).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.email - Email address
+   * @param {string} opts.email - Email address (path parameter; must match email pattern)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<object>>} response.data is EmailSetting
    */
   function getByEmail({token, jwtToken, email, query = {}, headers}) {
     return client({
@@ -42,13 +44,14 @@ function emailSettingsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /email-settings - create email settings.
+   * POST /email-settings – Create an email setting. Requires BETTEREZ_APP JWT. Emits emailSetting.created.
+   * Body: { emailSetting } or { name, email, active }. Email and domain are verified in AWS.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Email settings payload
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {Object} opts.data - Body: { name, email, active? } or { emailSetting: { name, email, active? } }
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ emailSetting: object }>>}
    */
   function create({data, token, jwtToken, headers}) {
     return client({
@@ -60,14 +63,14 @@ function emailSettingsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PUT /email-settings/:email - update email settings.
+   * PUT /email-settings/:email – Update an email setting. Requires BETTEREZ_APP JWT. Emits emailSetting.updated.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.email - Email address
-   * @param {Object} opts.data - Email settings payload
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {string} opts.email - Email address (path parameter)
+   * @param {Object} opts.data - Body: { name, email, active?, ... } or { emailSetting: { ... } }
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ emailSetting: object }>>}
    */
   function update({token, jwtToken, email, data, headers}) {
     return client({
@@ -79,13 +82,14 @@ function emailSettingsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * DELETE /email-settings/:email - remove email settings.
+   * DELETE /email-settings/:email – Remove an email setting. Requires BETTEREZ_APP JWT. Emits emailSetting.deleted.
+   * Fails with 400 if the email is currently active.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.email - Email address
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {string} opts.email - Email address (path parameter)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ emailSetting: object }>>}
    */
   function remove({email, token, jwtToken, headers}) {
     return client({

package/src/endpoints/accounts/email-templates.js

@@ -12,6 +12,7 @@ const {
  * @property {string} [sort] - relevance | natural | createdAsc | createdDesc | updatedAsc | updatedDesc
  * @property {string} [templateCollectionId] - default | custom
  * @property {string} [status] - draft | published
+ * @property {string} [agencyId] - Filter sub-templates for this agency (ObjectId)
  * @property {string} [mainTemplateAccountId] - Filter by source provider (ObjectId)
  * @property {string} [lang] - ISO language code (e.g. en-us)
  * @property {number} [page] - 1-based page for pagination
@@ -159,7 +160,8 @@ function emailTemplatesFactory({client, internalAuthTokenProvider}) {
    * @param {string} opts.mainTemplateId - Main template id (ObjectId)
    * @param {string} opts.agencyId - Agency id (ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ emailTemplate: object }>>}
+   * @throws {import("axios").AxiosError} 400 validation (WRONG_DATA, MAIN_TEMPLATE_IS_NOT_CUSTOM), 401 (MAIN_TEMPLATE_ACCOUNT_MISMATCH, MAIN_TEMPLATE_NOT_FROM_PROVIDER), 404 MAIN_TEMPLATE_NOT_FOUND, 500
    */
   function createSub({token, jwtToken, mainTemplateId, agencyId, headers}) {
     return client({
@@ -172,14 +174,16 @@ function emailTemplatesFactory({client, internalAuthTokenProvider}) {
 
   const versions = {
     /**
-     * PUT /email-templates/:emailTemplateId/versions/:versionId - update a template version.
+     * PUT /email-templates/:emailTemplateId/versions/:versionId - roll back template to a saved version (versionId is zero-based index in versions array).
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
      * @param {string} opts.emailTemplateId - Template id (ObjectId)
-     * @param {string} opts.versionId - Version id (ObjectId)
+     * @param {string} opts.versionId - Zero-based version index (e.g. "0", "1")
+     * @param {Object} [opts.query] - Optional query (superUserId, superUserHash for default templates)
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ emailTemplate: object }>>}
+     * @throws {import("axios").AxiosError} 400 WRONG_DATA, 401 NOT_SUPER_USER, 404 EMAIL_TEMPLATE_NOT_FOUND / EMAIL_TEMPLATE_VERSION_NOT_FOUND, 500
      */
     update({token, jwtToken, emailTemplateId, versionId, query = {}, headers}) {
       return client({

package/src/endpoints/accounts/exchange-rates.js

@@ -4,6 +4,7 @@ const {authorizationHeaders} = require("./../endpoints_helpers");
 
 /**
  * Factory for exchange-rates API (btrz-api-accounts).
+ * Manage account exchange rates by currency ISO code. GET returns paginated list; POST creates a rate and updates account preferences.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -11,13 +12,15 @@ const {authorizationHeaders} = require("./../endpoints_helpers");
  */
 function exchangeRatesFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /exchange-rates/:isoCode - get exchange rates by ISO code. API does not define query params in getSpec().
+   * GET /exchange-rates/:isoCode – List exchange rates for the account filtered by currency ISO code (3 letters).
+   * Response is paginated (exchangeRates array + totalRecords, page, etc.).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.isoCode - Currency ISO code (3 characters)
+   * @param {string} opts.isoCode - Currency ISO code (3 uppercase letters, e.g. USD, MXN)
+   * @param {Object} [opts.query] - Optional query (e.g. page for pagination)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ exchangeRates: object[], totalRecords: number, ... }>>}
    */
   function allByIsoCode({token, jwtToken, isoCode, query = {}, headers}) {
     return client({
@@ -28,13 +31,15 @@ function exchangeRatesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /exchange-rates - create an exchange rate.
+   * POST /exchange-rates – Create an exchange rate. Requires BETTEREZ_APP JWT. Currency must be in account preferences and enabled.
+   * Updates account preferences.supportedCurrencies for that currency. Emits exchangeRates.created.
+   * Body: { exchangeRate } or { isoCode, buy, sell }. buy and sell must be > 0.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Exchange rate payload
+   * @param {string} [opts.jwtToken] - JWT (required for BETTEREZ_APP audience)
+   * @param {Object} opts.data - Body: { isoCode, buy, sell } or { exchangeRate: { isoCode, buy, sell } }
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ exchangeRate: object }>>}
    */
   function create({data, token, jwtToken, headers}) {
     return client({

package/src/endpoints/accounts/exchange-receipts.js

@@ -3,6 +3,7 @@ const {authorizationHeaders} = require("../endpoints_helpers");
 
 /**
  * Factory for exchange-receipt-settings API (btrz-api-accounts).
+ * Get or update account exchange receipt settings (CNBV-related fields). Requires BETTEREZ_APP audience.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -10,13 +11,15 @@ const {authorizationHeaders} = require("../endpoints_helpers");
  */
 function exchangeReceiptsFactory({client, internalAuthTokenProvider}) {
   /**
-   * PUT /exchange-receipt-settings - update exchange receipt settings. API does not accept query params.
+   * PUT /exchange-receipt-settings – Update exchange receipt settings. Requires BETTEREZ_APP JWT.
+   * Body: { exchangeReceipt } or ExchangeReceipt fields at root. All fields must be strings.
+   * Emits exchangeReceipt.updated.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.data - Settings payload
+   * @param {string} [opts.jwtToken] - JWT (BETTEREZ_APP audience)
+   * @param {Object} opts.data - Body: { exchangeReceipt } or required ExchangeReceipt fields
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ exchangeReceipt: object }>>}
    */
   function update({data, token, jwtToken, headers}) {
     return client({
@@ -28,12 +31,13 @@ function exchangeReceiptsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /exchange-receipt-settings - get exchange receipt settings. API does not accept query params.
+   * GET /exchange-receipt-settings – Get exchange receipt settings. Requires BETTEREZ_APP JWT.
+   * Returns empty object if not set.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ exchangeReceipt: object }>>}
    */
   function get({token, jwtToken, headers}) {
     return client({

package/src/endpoints/accounts/external-customers.js

@@ -0,0 +1,37 @@
+/* eslint-disable import/extensions */
+const {authorizationHeaders} = require("../endpoints_helpers");
+
+/**
+ * Factory for external-customers API (btrz-api-accounts). Saldo Max (ADO) registration proxy.
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ registerSaldoMax: function }}
+ */
+function externalCustomersFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /external-customers/ado – Register a user with Saldo Max (ADO). Requires BETTEREZ_APP JWT.
+   * Body: SaldoMaxRegistrationRequest at root or { body: SaldoMaxRegistrationRequest }.
+   * Required: firstName, lastName, email, password (Base64), verificationCode, isoCode (2-letter).
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT (BETTEREZ_APP audience)
+   * @param {Object} opts.data - Request body (or { body: SaldoMaxRegistrationRequest })
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse<{ code: string }>>}
+   */
+  function registerSaldoMax({data, token, jwtToken, headers}) {
+    return client({
+      url: "/external-customers/ado",
+      method: "post",
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}),
+      data
+    });
+  }
+
+  return {
+    registerSaldoMax
+  };
+}
+
+module.exports = externalCustomersFactory;

package/src/endpoints/accounts/goal-settings.js

@@ -3,7 +3,7 @@ const {
 } = require("./../endpoints_helpers.js");
 
 /**
- * Factory for goal-settings API (btrz-api-accounts).
+ * Factory for goal-settings API (btrz-api-accounts). Goal API integration settings.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -11,12 +11,13 @@ const {
  */
 function goalSettingsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /goal-settings - get goal settings. API does not accept query params.
+   * GET /goal-settings – Get goal settings for the account. Requires BETTEREZ_APP JWT.
+   * If user lacks read permission for /admin/integrations/goal, returns 200 with empty goalSettings.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ goalSettings: object }>>}
    */
   function get({token, jwtToken, query, headers}) {
     return client({
@@ -27,13 +28,14 @@ function goalSettingsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PUT /goal-settings - update goal settings. API does not accept query params.
+   * PUT /goal-settings – Update goal settings. Requires BETTEREZ_APP and update permission for
+   * /admin/integrations/goal. Emits goalsettings.updated. Body: { goalSettings }.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.goalSettings - Settings payload
+   * @param {Object} opts.goalSettings - Required: baseUrl, clientId, clientSecret, pushOnManifestStatus
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ goalSettings: object }>>}
    */
   function update({jwtToken, token, goalSettings, headers}) {
     return client({

package/src/endpoints/accounts/images.js

@@ -2,7 +2,7 @@
 const {authorizationHeaders} = require("./../endpoints_helpers");
 
 /**
- * Factory for images API (btrz-api-accounts).
+ * Factory for images API (btrz-api-accounts). Account images (url-based). POST/DELETE require BETTEREZ_APP.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -10,12 +10,13 @@ const {authorizationHeaders} = require("./../endpoints_helpers");
  */
 function ImagesFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /images - list images. API getSpec() does not define query params.
+   * GET /images – List images for the account (paginated). Query: page.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} [opts.query] - Optional query (e.g. page for pagination)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ images: object[], totalRecords: number, ... }>>}
    */
   function all({token, jwtToken, query = {}, headers}) {
     return client({
@@ -26,13 +27,13 @@ function ImagesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /images/:imageId - get an image. API does not accept query params.
+   * GET /images/:imageId – Get a single image by id (24 hex ObjectId).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.imageId - Image id (ObjectId)
+   * @param {string} opts.imageId - Image id (24 hex characters)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ image: object }>>}
    */
   function get({token, jwtToken, query = {}, headers, imageId}) {
     return client({
@@ -43,13 +44,13 @@ function ImagesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /images - create an image.
+   * POST /images – Create an image. Requires BETTEREZ_APP JWT. Body: { image } with url required. Emits images.created.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.image - Image payload
+   * @param {string} [opts.jwtToken] - JWT (BETTEREZ_APP audience)
+   * @param {Object} opts.image - { url } (required)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ image: object }>>}
    */
   function create({jwtToken, token, image, headers}) {
     return client({
@@ -65,13 +66,13 @@ function ImagesFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * DELETE /images/:imageId - remove an image.
+   * DELETE /images/:imageId – Delete an image. Requires BETTEREZ_APP JWT. Emits images.deleted (data: { imageId }).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.imageId - Image id (ObjectId)
+   * @param {string} opts.imageId - Image id (24 hex ObjectId)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ imageId: string }>>}
    */
   function remove({imageId, token, jwtToken, headers}) {
     return client({