btrz-api-client 8.29.0 → 8.31.0

package/src/endpoints/inventory/companies.js

@@ -1,12 +1,35 @@
-const { authorizationHeaders } = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
-function companiesFactory({ client, internalAuthTokenProvider }) {
+/**
+ * Query params for GET /companies (btrz-api-inventory). See get-companies getSpec().
+ * @typedef {Object} InventoryCompaniesQuery
+ * @property {string} [search] - Term to find companies (required by API for getBySearch)
+ * @property {string} [disabled] - Filter by disabled [true, false]
+ * @property {string} [providerId] - Get items from the provider
+ */
 
-  function all({ token, jwtToken, query = {}, headers }) {
+/**
+ * Factory for companies API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function }}
+ */
+function companiesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /companies - list companies.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {InventoryCompaniesQuery} [opts.query] - Query params (search, disabled, providerId)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function all({token, jwtToken, query = {}, headers}) {
     return client({
       url: "/companies",
       params: query,
-      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}),
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
     });
   }
 

package/src/endpoints/inventory/control-classes.js

@@ -2,7 +2,53 @@ const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /control-classes (btrz-api-inventory). See get-control-classes getSpec().
+ * @typedef {Object} ControlClassesListQuery
+ * @property {number} [page] - Page number
+ * @property {boolean} [root] - Filter roots only
+ * @property {string} [productId] - Filter by product ID
+ * @property {string} [name] - Filter by name
+ * @property {string} [scheduleId] - Only roots that could apply to this schedule (UUID)
+ * @property {string} [assignedScheduleId] - Only roots assigned to this schedule (UUID)
+ * @property {string} [amenityGroupId] - Filter by amenity group ID(s), comma-separated
+ * @property {string} [brandId] - Filter by brand ID(s), comma-separated
+ * @property {string} [fareId] - Filter by fare ID(s), comma-separated
+ * @property {string} [fareClassId] - Filter by fare class ID(s), comma-separated
+ * @property {string} [seatClassId] - Filter by seat class ID(s), comma-separated
+ * @property {string} [operatingCompanyId] - Filter by operating company ID(s), comma-separated
+ * @property {string} [channel] - Filter by channel(s), comma-separated
+ * @property {number} [advancePurchaseFrom] - Filter by advance purchase from (hours)
+ * @property {number} [advancePurchaseTo] - Filter by advance purchase to (hours)
+ */
+
+/**
+ * Query params for GET /control-classes/:controlClassId (btrz-api-inventory). See get-control-class-by-id getSpec().
+ * @typedef {Object} ControlClassGetQuery
+ * @property {boolean} [tree] - Include the full tree
+ * @property {string} [scheduleId] - When tree requested, filter by schedule
+ * @property {string} [scheduleBrandId] - When tree requested, filter by schedule brand
+ * @property {string} [scheduleOperatingCompanyId] - When tree requested, filter by operating company
+ * @property {string} [scheduleAmenityGroupId] - When tree requested, filter by amenity group
+ */
+
+/**
+ * Factory for control-classes API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function, create: function, update: function, remove: function }}
+ */
 function controlClassesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /control-classes - list control classes.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {ControlClassesListQuery} [opts.query] - Query params
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     jwtToken,
@@ -15,6 +61,16 @@ function controlClassesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /control-classes/:controlClassId - get control class by id.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.controlClassId - Control class id
+   * @param {ControlClassGetQuery} [opts.query] - Query params (tree, scheduleId, etc.)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({controlClassId, token, headers, jwtToken, query = {}}) {
     return client.get(`/control-classes/${controlClassId}`, {
       params: query,
@@ -22,6 +78,15 @@ function controlClassesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * POST /control-classes - create control class. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} opts.controlClass - Control class payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({jwtToken, token, controlClass, headers}) {
     return client({
       url: "/control-classes",
@@ -33,6 +98,15 @@ function controlClassesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * DELETE /control-classes/:controlClassId - remove control class.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.controlClassId - Control class id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function remove({jwtToken, controlClassId, token, headers}) {
     return client({
       url: `/control-classes/${controlClassId}`,
@@ -41,6 +115,16 @@ function controlClassesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /control-classes/:controlClassId - update control class. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.controlClassId - Control class id
+   * @param {Object} opts.controlClass - Control class payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({jwtToken, token, controlClassId, controlClass, headers}) {
     return client({
       url: `/control-classes/${controlClassId}`,

package/src/endpoints/inventory/countries.js

@@ -1,6 +1,28 @@
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /countries (btrz-api-inventory). See get-countries getSpec().
+ * @typedef {Object} CountriesListQuery
+ * @property {string} [isoCode] - Country 2 or 3 letter ISO code
+ */
+
+/**
+ * Factory for countries API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function }}
+ */
 function countriesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /countries - list countries.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {CountriesListQuery} [opts.query] - Query params (isoCode)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({token, query = {}, headers}) {
     return client({
       url: "/countries",
@@ -9,6 +31,15 @@ function countriesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /countries/:id - get country by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.id - Country id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({token, jwtToken, id, query = {}, headers}) {
     return client({
       url: `/countries/${id}`,

package/src/endpoints/inventory/custom-content.js

@@ -1,8 +1,31 @@
 const {
   authorizationHeaders
-} = require("./../endpoints_helpers");
+} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /custom-content (btrz-api-inventory). See get-custom-contents getSpec().
+ * @typedef {Object} InventoryCustomContentQuery
+ * @property {string} [enabled] - Filter by enabled (true, false)
+ * @property {string} [pageId] - The page for the content
+ */
+
+/**
+ * Factory for custom-content API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function, create: function, update: function, remove: function }}
+ */
 function customContentFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /custom-content - list custom content.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {InventoryCustomContentQuery} [opts.query] - Query params (enabled, pageId)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     query = {},
@@ -14,13 +37,31 @@ function customContentFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /custom-content/:customContentId - get custom content by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.customContentId - Custom content id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({customContentId, token, headers}) {
     return client.get(`/custom-content/${customContentId}`, {
       headers: authorizationHeaders({token, internalAuthTokenProvider, headers})
     });
   }
 
-  function create({ jwtToken, token, customContent, headers }) {
+  /**
+   * POST /custom-content - create custom content. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} opts.customContent - Custom content payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function create({jwtToken, token, customContent, headers}) {
     return client({
       url: "/custom-content",
       method: "post",
@@ -31,7 +72,16 @@ function customContentFactory({client, internalAuthTokenProvider}) {
     });
   }
 
-  function remove({ jwtToken, customContentId, token, headers }) {
+  /**
+   * DELETE /custom-content/:customContentId - remove custom content. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.customContentId - Custom content id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function remove({jwtToken, customContentId, token, headers}) {
     return client({
       url: `/custom-content/${customContentId}`,
       method: "delete",
@@ -39,6 +89,16 @@ function customContentFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /custom-content/:customContentId - update custom content. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.customContentId - Custom content id
+   * @param {Object} opts.customContent - Custom content payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({jwtToken, token, customContentId, customContent, headers}) {
     return client({
       url: `/custom-content/${customContentId}`,

package/src/endpoints/inventory/custom-fields.js

@@ -1,6 +1,30 @@
-const {authorizationHeaders} = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /custom-fields (btrz-api-inventory). See get-custom-fields getSpec().
+ * @typedef {Object} InventoryCustomFieldsQuery
+ * @property {string} [enabled] - Required value of the disabled field
+ * @property {string} [required] - Required value of the required field
+ * @property {string} [modelName] - Filter by model (Transactions, Stations)
+ */
+
+/**
+ * Factory for custom-fields API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function, create: function, update: function, types: object }}
+ */
 function customFieldsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /custom-fields - list custom fields.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {InventoryCustomFieldsQuery} [opts.query] - Query params (enabled, required, modelName)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({token, query = {}, headers}) {
     return client({
       url: "/custom-fields",
@@ -9,6 +33,15 @@ function customFieldsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /custom-fields/:fieldId - get custom field by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.fieldId - Field id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({fieldId, token, jwtToken, query = {}, headers}) {
     return client({
       url: `/custom-fields/${fieldId}`,
@@ -17,6 +50,15 @@ function customFieldsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * POST /custom-fields - create custom field. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} opts.field - Field payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({token, jwtToken, field, headers}) {
     return client({
       url: "/custom-fields",
@@ -26,6 +68,16 @@ function customFieldsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /custom-fields/:fieldId - update custom field. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.fieldId - Field id
+   * @param {Object} opts.field - Field payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({token, jwtToken, fieldId, field, headers}) {
     return client({
       url: `/custom-fields/${fieldId}`,
@@ -35,7 +87,15 @@ function customFieldsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /** @type {{ all: function }} */
   const types = {
+    /**
+     * GET /custom-fields/types - list custom field types. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     all({token, headers}) {
       return client({
         url: "/custom-fields/types",

package/src/endpoints/inventory/docs.js

@@ -1,4 +1,14 @@
+/**
+ * Factory for API docs (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @returns {{ get: function }}
+ */
 function docsFactory({client}) {
+  /**
+   * GET /api-docs-v2 - get API docs.
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get() {
     return client.get("/api-docs-v2", {});
   }

package/src/endpoints/inventory/document-types.js

@@ -1,6 +1,29 @@
-const {authorizationHeaders} = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /document-types (btrz-api-inventory). See get-document-types getSpec().
+ * @typedef {Object} DocumentTypesListQuery
+ * @property {string} [providerIds] - Comma-separated provider IDs to get document types for
+ */
+
+/**
+ * Factory for document-types API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function, update: function, remove: function, create: function }}
+ */
 function documentTypesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /document-types - list document types.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {DocumentTypesListQuery} [opts.query] - Query params (providerIds); opts.providerId merged into query if set
+   * @param {string} [opts.providerId] - Provider id (added to query if set)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({token, jwtToken, query = {}, headers, providerId}) {
     const query_ = providerId ? {...query, providerId} : query;
     return client({
@@ -11,6 +34,16 @@ function documentTypesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /document-types/:id - get document type by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.id - Document type id
+   * @param {string} [opts.providerId] - Provider id (added to query if set)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({token, jwtToken, id, query = {}, headers, providerId}) {
     const query_ = providerId ? {...query, providerId} : query;
     return client({
@@ -21,6 +54,16 @@ function documentTypesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /document-types/:id - update document type. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.id - Document type id
+   * @param {Object} opts.data - Document type payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({token, jwtToken, id, data, query = {}, headers}) {
     return client({
       url: `/document-types/${id}`,
@@ -31,6 +74,15 @@ function documentTypesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * DELETE /document-types/:id - remove document type. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.id - Document type id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function remove({token, jwtToken, id, query = {}, headers}) {
     return client({
       url: `/document-types/${id}`,
@@ -40,6 +92,15 @@ function documentTypesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * POST /document-types - create document type. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} opts.data - Document type payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({token, jwtToken, data, query = {}, headers}) {
     return client({
       url: "/document-types",

package/src/endpoints/inventory/external-passes.js

@@ -2,7 +2,37 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Query params for GET /external-passes (btrz-api-inventory). See get-external-passes getSpec().
+ * @typedef {Object} ExternalPassesListQuery
+ * @property {string} [passNumber] - Filter by pass number
+ * @property {string} [accountDisplayName] - Filter by Pay On Account name
+ * @property {string} [expirationDateFrom] - Filter by expiration date >= (yyyy-mm-dd)
+ * @property {string} [expirationDateTo] - Filter by expiration date <= (yyyy-mm-dd)
+ * @property {string} [lastUpdatedAt] - Filter by last updated (ISO format)
+ * @property {number} [page] - Page for pagination
+ * @property {string} [orderBy] - Field to order by
+ * @property {string} [orderDir] - asc (1) or desc (-1)
+ * @property {number} [pageSize] - Results per page
+ */
+
+/**
+ * Factory for external-passes API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, get: function }}
+ */
 function externalPassesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /external-passes - list external passes.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {ExternalPassesListQuery} [opts.query] - Query params
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     jwtToken,
@@ -15,6 +45,15 @@ function externalPassesFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /external-passes/:externalPassId - get external pass by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.externalPassId - External pass id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({externalPassId, token, jwtToken, headers}) {
     return client.get(`/external-passes/${externalPassId}`, {
       headers: authorizationHeaders({token, internalAuthTokenProvider, jwtToken, headers})

package/src/endpoints/inventory/external-wallets.js

@@ -2,14 +2,39 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for external-wallets API (btrz-api-inventory).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ saldoMax: object }}
+ */
 function externalWalletsFactory({client, internalAuthTokenProvider}) {
+  /** @type {{ all: function, create: function, get: function, update: function, movements: object }} */
   const saldoMax = {
+    /**
+     * GET /external-wallets/saldo-max - list saldo max wallets. API does not accept 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>}
+     */
     all: ({token, jwtToken, query = {}, headers}) => {
       return client.get("/external-wallets/saldo-max", {
         params: query,
         headers: authorizationHeaders({token, internalAuthTokenProvider, jwtToken, headers})
       });
     },
+    /**
+     * POST /external-wallets/saldo-max - create saldo max wallet. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {Object} opts.externalWallet - External wallet payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create: ({token, jwtToken, externalWallet, headers}) => {
       return client({
         url: "/external-wallets/saldo-max",
@@ -18,11 +43,29 @@ function externalWalletsFactory({client, internalAuthTokenProvider}) {
         data: {externalWallet}
       });
     },
+    /**
+     * GET /external-wallets/saldo-max/:walletId - get saldo max wallet. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.walletId - Wallet id
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get: ({token, jwtToken, walletId, headers}) => {
       return client.get(`/external-wallets/saldo-max/${walletId}`, {
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * PUT /external-wallets/saldo-max/:externalWallet._id - update saldo max wallet. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {Object} opts.externalWallet - External wallet payload (must include _id)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update: ({token, jwtToken, externalWallet, headers}) => {
       const externalWalletFieldsToUpdate = {
         nip: externalWallet.nip,
@@ -39,7 +82,17 @@ function externalWalletsFactory({client, internalAuthTokenProvider}) {
         }
       });
     },
+    /** @type {{ create: function }} */
     movements: {
+      /**
+       * PUT /external-wallets/saldo-max/:walletId/movements - create movement. API does not accept query params.
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {string} opts.walletId - Wallet id
+       * @param {Object} opts.movement - Movement payload
+       * @returns {Promise<import("axios").AxiosResponse>}
+       */
       create: ({token, jwtToken, walletId, movement}) => {
         return client({
           url: `/external-wallets/saldo-max/${walletId}/movements`,