btrz-api-client 8.29.0 → 8.31.0

package/src/endpoints/accounts/interline.js

@@ -2,8 +2,23 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for interline API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ invitations: object, consumers: object, providers: object, network: object, remove: function }}
+ */
 function interlineFactory({client, internalAuthTokenProvider}) {
   const invitations = {
+    /**
+     * GET /interline/invitations - list interline invitations. 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({
         url: "/interline/invitations",
@@ -11,11 +26,28 @@ function interlineFactory({client, internalAuthTokenProvider}) {
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * GET /interline/invitations/:invitationId - get an invitation. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} opts.invitationId - Invitation id (ObjectId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, invitationId, headers}) {
       return client.get(`/interline/invitations/${invitationId}`, {
         headers: authorizationHeaders({token, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * POST /interline/invitations - create an invitation.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {Object} opts.data - Invitation payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({data, token, jwtToken, headers}) {
       return client({
         url: "/interline/invitations",
@@ -24,6 +56,16 @@ function interlineFactory({client, internalAuthTokenProvider}) {
         data
       });
     },
+    /**
+     * PUT /interline/invitations/:invitationId - update an invitation.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.invitationId - Invitation id (ObjectId)
+     * @param {Object} opts.data - Invitation payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({invitationId, data, token, jwtToken, headers}) {
       return client({
         url: `/interline/invitations/${invitationId}`,
@@ -35,6 +77,14 @@ function interlineFactory({client, internalAuthTokenProvider}) {
   };
 
   const consumers = {
+    /**
+     * GET /interline/consumers - list interline consumers. 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({
         url: "/interline/consumers",
@@ -45,6 +95,14 @@ function interlineFactory({client, internalAuthTokenProvider}) {
   };
 
   const providers = {
+    /**
+     * GET /interline/providers - list interline providers. 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({
         url: "/interline/providers",
@@ -55,11 +113,29 @@ function interlineFactory({client, internalAuthTokenProvider}) {
   };
 
   const network = {
+    /**
+     * GET /interline/:interlineId/network - get interline network. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} opts.interlineId - Interline id (ObjectId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, interlineId, headers}) {
       return client.get(`/interline/${interlineId}/network`, {
         headers: authorizationHeaders({token, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * PUT /interline/:interlineId/network - update interline network.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.interlineId - Interline id (ObjectId)
+     * @param {Object} opts.data - Network payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({interlineId, data, token, jwtToken, headers}) {
       return client({
         url: `/interline/${interlineId}/network`,
@@ -75,6 +151,15 @@ function interlineFactory({client, internalAuthTokenProvider}) {
     consumers,
     providers,
     network,
+    /**
+     * DELETE /interline/:interlineId - remove an interline.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.interlineId - Interline id (ObjectId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     remove({interlineId, token, jwtToken, headers}) {
       return client({
         url: `/interline/${interlineId}`,

package/src/endpoints/accounts/journey-prices-settings.js

@@ -2,7 +2,22 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for journey-prices-settings API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function, update: function }}
+ */
 function journeyPricesSettingsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /journey-prices-settings - get journey prices settings. 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>}
+   */
   function get({token, jwtToken, headers}) {
     return client({
       url: "/journey-prices-settings",
@@ -10,6 +25,15 @@ function journeyPricesSettingsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /journey-prices-settings - update journey prices settings. 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.journeyPricesSettings - Settings payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({token, jwtToken, journeyPricesSettings, headers}) {
     return client({
       url: "/journey-prices-settings",

package/src/endpoints/accounts/lexicons.js

@@ -1,10 +1,56 @@
+/* eslint-disable max-len */
 const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /lexicons/:lexiconCollectionId (btrz-api-accounts). See get-lexicons handler getSpec().
+ * @typedef {Object} LexiconsListQuery
+ * @property {string} [providerIds] - Provider ids to get lexicons for
+ * @property {string} [context] - Context of the lexicons to search
+ * @property {boolean} [accountOnly] - Filter lexicons only for the given providerIds; context ignored when true
+ * @property {string} [key] - Specific lexicon key to search for
+ * @property {string} [keys] - Comma-separated list of keys to search for
+ * @property {string} [lang] - ISO language code to filter values
+ * @property {string} [langs] - Comma-separated ISO language codes to filter values
+ */
+
+/**
+ * Query params for GET /lexicons/suggestions (btrz-api-accounts). See get-lexicons-suggestions handler getSpec().
+ * @typedef {Object} LexiconSuggestionsListQuery
+ * @property {string} [status] - Filter by status: under review | accepted | rejected
+ * @property {string} [lang] - Filter by language code (e.g. en-us, pt-br)
+ * @property {string} [key] - Filter by lexicon key
+ * @property {string} [superUserId] - Super user id; with superUserHash returns suggestions for all accounts
+ * @property {string} [superUserHash] - Super user hash; with superUserId returns suggestions for all accounts
+ */
+
+/**
+ * Query params for GET /lexicons/suggestions/:id (btrz-api-accounts). See get-lexicons-suggestion-by-id handler getSpec().
+ * @typedef {Object} LexiconSuggestionGetByIdQuery
+ * @property {string} [superUserId] - Super user id; with superUserHash any suggestion can be retrieved
+ * @property {string} [superUserHash] - Super user hash; with superUserId any suggestion can be retrieved
+ */
+
+/**
+ * Factory for lexicons API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, create: function, createOrUpdateMany: function, updateMany: function, getByText: function, suggestions: { list: function, getById: function, update: function, delete: function, create: function } }}
+ */
 function lexiconsFactory({
   client, internalAuthTokenProvider
 }) {
+  /**
+   * GET /lexicons/buscompany - list lexicons (collection buscompany). Query params from get-lexicons getSpec().
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.context] - Context of the lexicons to search (merged into query)
+   * @param {LexiconsListQuery} [opts.query] - Query params: providerIds, context, accountOnly, key, keys, lang, langs
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     context,
@@ -20,6 +66,15 @@ function lexiconsFactory({
     });
   }
 
+  /**
+   * POST /lexicons - create lexicon entries.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Array} opts.lexiconEntries - Entries to create
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({
     token,
     jwtToken,
@@ -36,6 +91,15 @@ function lexiconsFactory({
     });
   }
 
+  /**
+   * PUT /lexicons - create or update many lexicon entries.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Array} opts.entries - Entries to create or update
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function createOrUpdateMany({
     token,
     jwtToken,
@@ -54,6 +118,15 @@ function lexiconsFactory({
     });
   }
 
+  /**
+   * PATCH /lexicons - update many lexicon entries.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Array} opts.updates - Updates to apply
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function updateMany({
     token,
     jwtToken,
@@ -90,12 +163,12 @@ function lexiconsFactory({
 
   const suggestions = {
     /**
-     * List lexicon suggestions for the account (or all accounts when super user params are provided).
+     * GET /lexicons/suggestions - list lexicon suggestions (or all accounts when super user params provided).
      * @param {Object} opts
      * @param {string} [opts.token] - API key (x-api-key)
      * @param {string} [opts.jwtToken] - JWT or constants.INTERNAL_AUTH_TOKEN_SYMBOL for internal auth
      * @param {Object} [opts.headers] - Optional request headers
-     * @param {Object} [opts.params] - Query params: status, lang, key, superUserId, superUserHash
+     * @param {LexiconSuggestionsListQuery} [opts.params] - Query params: status, lang, key, superUserId, superUserHash
      * @returns {Promise<{data: { suggestions: Array }}>}
      */
     list({token, jwtToken, headers, params = {}}) {
@@ -107,13 +180,13 @@ function lexiconsFactory({
     },
 
     /**
-     * Get a single lexicon suggestion by id.
+     * GET /lexicons/suggestions/:id - get a single lexicon suggestion by id.
      * @param {Object} opts
      * @param {string} opts.suggestionId - MongoDB ObjectId of the suggestion
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
      * @param {Object} [opts.headers] - Optional request headers
-     * @param {Object} [opts.params] - Query params: superUserId, superUserHash (to access any account's suggestion)
+     * @param {LexiconSuggestionGetByIdQuery} [opts.params] - Query params: superUserId, superUserHash (to access any account's suggestion)
      * @returns {Promise<{data: Object}>}
      */
     getById({token, jwtToken, headers, suggestionId, params = {}}) {

package/src/endpoints/accounts/market-pricing-settings.js

@@ -2,7 +2,22 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for market-pricing-settings API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function, update: function }}
+ */
 function marketPricingSettingsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /market-pricing-settings - get market pricing settings. 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>}
+   */
   function get({token, jwtToken, headers}) {
     return client({
       url: "/market-pricing-settings",
@@ -10,6 +25,15 @@ function marketPricingSettingsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /market-pricing-settings - update market pricing settings. 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.marketPricingSettings - Settings payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({token, jwtToken, marketPricingSettings, headers}) {
     return client({
       url: "/market-pricing-settings",

package/src/endpoints/accounts/multiproduct-sales-settings.js

@@ -2,7 +2,22 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for multiproduct-sales-settings API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function, update: function }}
+ */
 function multiproductSalesSettingsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /multiproduct-sales-settings - get multiproduct sales settings. 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>}
+   */
   function get({token, jwtToken, headers}) {
     return client({
       url: "/multiproduct-sales-settings",
@@ -10,6 +25,15 @@ function multiproductSalesSettingsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /multiproduct-sales-settings - update multiproduct sales settings. 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 - Settings payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({token, jwtToken, data, headers}) {
     return client({
       url: "/multiproduct-sales-settings",

package/src/endpoints/accounts/network.js

@@ -1,9 +1,25 @@
+/* eslint-disable max-len */
 const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Factory for network API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ agencies: { all: function, get: function, update: function, create: function, removeProduct: function, removeFare: function } }}
+ */
 function networkFactory({client, internalAuthTokenProvider}) {
   const agencies = {
+    /**
+     * GET /network/agencies - list agencies. API getSpec() does not define 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({
         url: "/network/agencies",
@@ -11,6 +27,14 @@ function networkFactory({client, internalAuthTokenProvider}) {
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * GET /network/agencies/:agencyId - get an agency by id. API does not accept query params.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} opts.sellerId - Seller/agency id (ObjectId), maps to path agencyId
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, query, headers, sellerId}) {
       return client({
         url: `/network/agencies/${sellerId}`,
@@ -18,6 +42,16 @@ function networkFactory({client, internalAuthTokenProvider}) {
         headers: authorizationHeaders({token, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * PUT /network/agencies/:sellerId - update an agency. 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.sellerId - Seller/agency id (ObjectId)
+     * @param {Object} opts.agency - Agency payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({jwtToken, token, sellerId, agency, headers, query}) {
       return client({
         url: `/network/agencies/${sellerId}`,
@@ -31,6 +65,15 @@ function networkFactory({client, internalAuthTokenProvider}) {
         params: query
       });
     },
+    /**
+     * POST /network/agencies - create an agency.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {Object} opts.agency - Agency payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({jwtToken, token, agency, headers}) {
       return client({
         url: "/network/agencies",
@@ -43,6 +86,15 @@ function networkFactory({client, internalAuthTokenProvider}) {
         }
       });
     },
+    /**
+     * PUT /network/agencies/remove-product - remove product from agency. 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.productId - Product id (ObjectId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     removeProduct({token, jwtToken, productId, headers}) {
       return client({
         url: "/network/agencies/remove-product",
@@ -55,6 +107,15 @@ function networkFactory({client, internalAuthTokenProvider}) {
         }
       });
     },
+    /**
+     * PUT /network/agencies/remove-fare - remove fare from agency. 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.fareId - Fare id (ObjectId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     removeFare({token, jwtToken, fareId, headers}) {
       return client({
         url: "/network/agencies/remove-fare",

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

@@ -2,7 +2,22 @@ const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
+/**
+ * Factory for operation-settings API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function, update: function }}
+ */
 function operationSettingsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /operation-settings - get operation settings. 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>}
+   */
   function get({token, jwtToken, query, headers}) {
     return client({
       url: "/operation-settings",
@@ -11,6 +26,15 @@ function operationSettingsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /operation-settings - update operation settings. 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.operationSettings - Settings payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({jwtToken, token, operationSettings, headers}) {
     return client({
       url: "/operation-settings",

package/src/endpoints/accounts/people-lookups.js

@@ -1,8 +1,43 @@
+/* eslint-disable max-len */
 const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /people-lookups (btrz-api-accounts). See get-handler getSpec().
+ * @typedef {Object} PeopleLookupsListQuery
+ * @property {string} [dynamicFormId] - If provided, only include this dynamic form's data in response
+ * @property {string} [documentNumber] - Document number to search for
+ * @property {string} [documentTypeId] - Document type id to search for
+ * @property {string} [email] - Email to search for
+ * @property {string} [customerNumber] - Customer number to search for
+ * @property {string} [phone] - Phone to search for
+ */
+
+/**
+ * Query params for GET /people-lookups/:personId (btrz-api-accounts). See get-by-id-handler getSpec().
+ * @typedef {Object} PeopleLookupGetByIdQuery
+ * @property {string} [dynamicFormId] - If provided, only include this dynamic form's data in response
+ */
+
+/**
+ * Factory for people-lookups API (btrz-api-accounts).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, getById: function, update: function, create: function, remove: function }}
+ */
 function peopleLookupsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /people-lookups - list people lookups.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {PeopleLookupsListQuery} [opts.query] - Query params (dynamicFormId, documentNumber, documentTypeId, email, customerNumber, phone)
+   * @param {string} [opts.providerId] - Provider id (ObjectId); merged into query for provider context
+   * @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({
@@ -12,6 +47,17 @@ function peopleLookupsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * GET /people-lookups/:personId - get a person lookup.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.personId - Person id (ObjectId)
+   * @param {PeopleLookupGetByIdQuery} [opts.query] - Query params: dynamicFormId
+   * @param {string} [opts.providerId] - Provider id (ObjectId); merged into query for provider context
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function getById({token, jwtToken, query, headers, personId, providerId}) {
     const query_ = providerId ? {...query, providerId} : query;
 
@@ -22,6 +68,17 @@ function peopleLookupsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * PUT /people-lookups/:personId - update a person lookup. API getSpec() does not define query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.personId - Person id (ObjectId)
+   * @param {Object} opts.person - Person payload
+   * @param {string} [opts.providerId] - Provider id (ObjectId); sent as query for provider context
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function update({jwtToken, token, personId, person, headers, providerId}) {
     const query = providerId ? {providerId} : {};
 
@@ -38,6 +95,16 @@ function peopleLookupsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * POST /people-lookups - create a person lookup. API getSpec() does not define query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {Object} opts.person - Person payload
+   * @param {string} [opts.providerId] - Provider id (ObjectId); sent as query for provider context
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({jwtToken, token, person, headers, providerId}) {
     const query = providerId ? {providerId} : {};
 
@@ -54,6 +121,15 @@ function peopleLookupsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * DELETE /people-lookups/:personId - remove a person lookup. 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.personId - Person id (ObjectId)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function remove({personId, token, jwtToken, headers}) {
     return client({
       url: `/people-lookups/${personId}`,