btrz-api-client 8.29.0 → 8.31.0

package/src/endpoints/btrzpay/prismaTerminals.js

@@ -2,14 +2,48 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Query params for GET payment/reversal/refund and PUT refund (btrz-api-payments). See get-by-id-* and put-refunds getSpec().
+ * @typedef {Object} PrismaTerminalsQuery
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
+ * @property {boolean} [validateRefund] - (PUT refunds only) If true, fetch current state from Prisma before applying
+ */
+
+/**
+ * Factory for Prisma terminals API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ payments: Object, settlements: Object }}
+ */
 function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
   const reversals = {
+    /**
+     * GET /prisma-terminals/reversals/:id - get reversal by id.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Reversal id
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/prisma-terminals/reversals/${id}`, {
         params: query,
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * POST /prisma-terminals/payments/:id/reversals - create reversal. 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 - Payment id
+     * @param {Object} opts.prismaReversal - Prisma reversal payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({token, jwtToken, id, prismaReversal, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/payments/${id}/reversals`,
@@ -19,6 +53,15 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
         data: {prismaReversal}
       });
     },
+    /**
+     * DELETE /prisma-terminals/reversals/:id - delete reversal. 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 - Reversal id
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     delete({token, jwtToken, id, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/reversals/${id}`,
@@ -30,12 +73,32 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
   };
 
   const refunds = {
+    /**
+     * GET /prisma-terminals/refunds/:id - get refund by id.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Refund id
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/prisma-terminals/refunds/${id}`, {
         params: query,
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * POST /prisma-terminals/payments/:id/refunds - create refund. 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 - Payment id
+     * @param {Object} opts.prismaRefund - Prisma refund payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({token, jwtToken, id, prismaRefund, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/payments/${id}/refunds`,
@@ -45,6 +108,15 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
         data: {prismaRefund}
       });
     },
+    /**
+     * DELETE /prisma-terminals/refunds/:id - delete refund. 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 - Refund id
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     delete({token, jwtToken, id, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/refunds/${id}`,
@@ -53,6 +125,17 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
         params: query
       });
     },
+    /**
+     * PUT /prisma-terminals/refunds/:id - update refund.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Refund id
+     * @param {Object} opts.prismaRefund - Prisma refund payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId, validateRefund)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({token, jwtToken, id, prismaRefund, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/refunds/${id}`,
@@ -65,12 +148,31 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
   };
 
   const payments = {
+    /**
+     * GET /prisma-terminals/payments/:id - get payment by id.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Payment id
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/prisma-terminals/payments/${id}`, {
         params: query,
         headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
       });
     },
+    /**
+     * POST /prisma-terminals/payments - create payment. 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.prismaPayment - Prisma payment payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({token, jwtToken, prismaPayment, query = {}, headers}) {
       return client({
         url: "/prisma-terminals/payments",
@@ -80,6 +182,15 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
         data: {prismaPayment}
       });
     },
+    /**
+     * DELETE /prisma-terminals/payments/:id - delete payment. 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 - Payment id
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     delete({token, jwtToken, id, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/payments/${id}`,
@@ -88,6 +199,16 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
         params: query
       });
     },
+    /**
+     * PUT /prisma-terminals/payments/:id - update payment. 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 - Payment id
+     * @param {Object} opts.prismaPayment - Prisma payment payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({token, jwtToken, id, prismaPayment, query = {}, headers}) {
       return client({
         url: `/prisma-terminals/payments/${id}`,
@@ -102,6 +223,15 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
   };
 
   const settlements = {
+    /**
+     * POST /prisma-terminals/settlements - create settlement. 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.settlement - Settlement payload
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     create({token, jwtToken, settlement, query = {}, headers}) {
       return client({
         url: "/prisma-terminals/settlements",

package/src/endpoints/btrzpay/reference-numbers.js

@@ -1,13 +1,28 @@
-const { authorizationHeaders } = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
-function referenceNumbersFactory({ client, internalAuthTokenProvider }) {
-
-  function create({ token, jwtToken, referenceNumberRequest, headers }) {
+/**
+ * Factory for reference numbers API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ create: function }}
+ */
+function referenceNumbersFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /reference-numbers - create reference number. 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.referenceNumberRequest - Reference number request payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function create({token, jwtToken, referenceNumberRequest, headers}) {
     return client({
       url: "/reference-numbers",
       method: "post",
       headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}),
-      data: { referenceNumberRequest }
+      data: {referenceNumberRequest}
     });
   }
 

package/src/endpoints/btrzpay/referenced-payments.js

@@ -1,6 +1,29 @@
-const {authorizationHeaders} = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Query for POST .../referenced-payments/:type/:referenceNumber/results (btrz-api-payments). See post-referenced-payments getSpec().
+ * @typedef {Object} ReferencedPaymentsUpdateQuery
+ * @property {string} [includePaidOrExpired] - Update beyond paid/expired for completion [true, false]
+ */
+
+/**
+ * Factory for referenced payments API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ getStatus: function, update: function }}
+ */
 function referencedPaymentsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /referenced-payments/:transactionId/:referenceNumber/status - get status. 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.transactionId - Transaction id
+   * @param {string} opts.referenceNumber - Reference number
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function getStatus({token, jwtToken, transactionId, referenceNumber, headers}) {
     return client.get(`/referenced-payments/${transactionId}/${referenceNumber}/status`, {
       params: {},
@@ -8,10 +31,23 @@ function referencedPaymentsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
-  function update({token, jwtToken, externalType, referenceNumber, paymentResult, headers}) {
+  /**
+   * POST /referenced-payments/:externalType/:referenceNumber/results - update payment result.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.externalType - External type
+   * @param {string} opts.referenceNumber - Reference number
+   * @param {Object} opts.paymentResult - Payment result payload
+   * @param {ReferencedPaymentsUpdateQuery} [opts.query] - Query params (includePaidOrExpired)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function update({token, jwtToken, externalType, referenceNumber, paymentResult, query = {}, headers}) {
     return client({
       url: `/referenced-payments/${externalType}/${referenceNumber}/results`,
       method: "post",
+      params: query,
       headers: authorizationHeaders({token, jwtToken, headers}),
       data: {paymentResult}
     });

package/src/endpoints/btrzpay/square.js

@@ -1,8 +1,25 @@
 const {
   authorizationHeaders
-} = require("./../endpoints_helpers");
+} = require("./../endpoints_helpers.js");
 
+/**
+ * Factory for Square webhooks API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ create: function }}
+ */
 function squareWebhooksFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /square-webhooks/:providerId - create Square webhook. 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.providerId - Provider id
+   * @param {Object} opts.data - Request body
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({token, jwtToken, data, providerId, headers}) {
     return client({
       url: `/square-webhooks/${providerId}`,
@@ -17,7 +34,22 @@ function squareWebhooksFactory({client, internalAuthTokenProvider}) {
   };
 }
 
+/**
+ * Factory for Square terminals API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function }}
+ */
 function squareTerminalsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /square-terminals - get Square terminals. 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.get("/square-terminals", {
       params: {},

package/src/endpoints/btrzpay/stripe-terminals.js

@@ -2,7 +2,29 @@ const {
   authorizationHeaders
 } = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /stripe-terminals (btrz-api-payments). See get-handler getSpec().
+ * @typedef {Object} StripeTerminalsListQuery
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
+ */
+
+/**
+ * Factory for Stripe terminals API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function, simulate: function }}
+ */
 function stripeTerminalsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /stripe-terminals - list Stripe terminals.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {StripeTerminalsListQuery} [opts.query] - Query params (providerId)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({token, jwtToken, headers, query = {}}) {
     return client.get("/stripe-terminals", {
       params: query,
@@ -12,6 +34,16 @@ function stripeTerminalsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * POST /stripe-terminals/:id/simulate - simulate Stripe payment. 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 - Terminal id
+   * @param {Object} opts.stripePayment - Stripe payment payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function simulate({token, jwtToken, id, stripePayment, query = {}, headers}) {
     return client({
       url: `/stripe-terminals/${id}/simulate`,

package/src/endpoints/btrzpay/terminalPayments.js

@@ -2,8 +2,41 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Query params for GET /terminal-payments/mit/:id (btrz-api-payments). See get-mit-by-id-handler getSpec().
+ * @typedef {Object} TerminalPaymentsMitGetQuery
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
+ * @property {string} [branchId] - Branch id where payment started (required for GET)
+ * @property {string} [companyId] - Company id where payment started (required for GET)
+ * @property {string} [date] - Date when payment started; format dd/mm/yyyy (required for GET)
+ */
+
+/**
+ * Query params for PUT /terminal-payments/mit/:id (btrz-api-payments). See put-mit-handler getSpec().
+ * @typedef {Object} TerminalPaymentsMitPutQuery
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
+ */
+
+/**
+ * Factory for terminal payments API (btrz-api-payments).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ mit: Object, webhooks: Object }}
+ */
 function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
   const mit = {
+    /**
+     * PUT /terminal-payments/mit/:id - update MIT terminal payment.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Terminal payment id
+     * @param {Object} opts.terminalPayment - Terminal payment payload
+     * @param {TerminalPaymentsMitPutQuery} [opts.query] - Query params (providerId)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     update({token, jwtToken, id, terminalPayment, query = {}, headers}) {
       return client({
         url: `/terminal-payments/mit/${id}`,
@@ -13,6 +46,16 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
         data: {terminalPayment}
       });
     },
+    /**
+     * GET /terminal-payments/mit/:id - get MIT terminal payment.
+     * @param {Object} opts
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @param {string} opts.id - Terminal payment id
+     * @param {TerminalPaymentsMitGetQuery} [opts.query] - Query params (providerId, branchId, companyId, date)
+     * @param {Object} [opts.headers] - Optional headers
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/terminal-payments/mit/${id}`, {
         params: query,
@@ -22,6 +65,16 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
   };
 
   const webhooks = {
+    /**
+     * POST /terminal-payments/webhooks/getnet/:providerId - Getnet webhook. API does not accept query params.
+     * @param {Object} opts
+     * @param {Object} opts.data - Request body
+     * @param {string} opts.providerId - Provider id
+     * @param {Object} [opts.headers] - Optional headers
+     * @param {string} [opts.token] - API key
+     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+     * @returns {Promise<import("axios").AxiosResponse>}
+     */
     getnet({data, providerId, headers = {}, token, jwtToken}) {
       const _headers = token && jwtToken ?
         authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}) :

package/src/endpoints/coltrane/docs.js

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

package/src/endpoints/coltrane/merged-fare-tables.js

@@ -1,6 +1,24 @@
+/* eslint-disable max-len */
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Factory for Coltrane merged fare tables API (btrz-api-coltrane).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function }}
+ */
 function mergedFareTablesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /coltrane/routes/:routeId/merged-fare-tables/:productId - get merged fare table. 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.routeId - Route id
+   * @param {string} opts.productId - Product id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({token, jwtToken, routeId, productId, headers}) {
     return client({
       url: `/coltrane/routes/${routeId}/merged-fare-tables/${productId}`,

package/src/endpoints/coltrane/paths.js

@@ -1,6 +1,34 @@
+/* eslint-disable max-len */
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /paths (btrz-api-coltrane). See get-paths getSpec().
+ * @typedef {Object} ColtranePathsListQuery
+ * @property {string} [providerId] - Account ID of the travel provider (required by API)
+ * @property {string} [productId] - Product ID belonging to the provider (required by API)
+ * @property {string} [originId] - Origin station id (required by API)
+ * @property {string} [destinationId] - Destination station id (required by API)
+ * @property {string} [departureFromDate] - Start of search interval; ISO 8601 (e.g. 2021-10-07T17:30:00.000-0400)
+ * @property {string} [departureToDate] - End of search interval; ISO 8601; interval max 25h
+ * @property {string} [metrics] - If true, response includes metrics (debugging)
+ */
+
+/**
+ * Factory for Coltrane paths API (btrz-api-coltrane).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ all: function }}
+ */
 function coltraneFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /paths - list Coltrane paths.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {ColtranePathsListQuery} [opts.query] - Query params (providerId, productId, originId, destinationId, etc.)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({token, query = {}, headers}) {
     return client({
       url: "/paths",

package/src/endpoints/endpoints_helpers.js

@@ -1,5 +1,15 @@
-const constants = require("../constants");
+/* eslint-disable max-len */
+const constants = require("../constants.js");
 
+/**
+ * Builds authorization and forwarding headers for API requests.
+ * @param {Object} opts - Options for authorization
+ * @param {string} [opts.token] - API key; sets x-api-key header when provided
+ * @param {string} [opts.jwtToken] - JWT or internal auth symbol; sets Authorization Bearer when provided
+ * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - When jwtToken is INTERNAL_AUTH_TOKEN_SYMBOL, getToken() is used for the Bearer token
+ * @param {Object} [opts.headers] - Optional request headers; x-amzn-trace-id and x-elevation-token are forwarded when present; cookie with "btrz-trusted" is forwarded for trusted machine
+ * @returns {Object} Headers object suitable for axios (x-api-key, Authorization, cookie, x-amzn-trace-id, x-elevation-token as applicable)
+ */
 function authorizationHeaders({
   token, jwtToken, internalAuthTokenProvider, headers
 }) {

package/src/endpoints/gps/scanner-app-location.js

@@ -1,7 +1,31 @@
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
-//TODO: add docs function when docs published
+/**
+ * Query params for GET /scanner-app-location (GPS API). API is external (not in workspace);
+ * shape from btrz-vue-websales and client usage.
+ * @typedef {Object} ScannerAppLocationQuery
+ * @property {string} [scheduleId] - Schedule id
+ * @property {string} [routeId] - Route id
+ * @property {string} [date] - Date (e.g. YYYY-MM-DD); defaults to today when omitted in websales
+ * @property {boolean} [includeTravelledPath] - Whether to include travelled path
+ */
+
+/**
+ * Factory for scanner app location API (GPS).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ get: function }}
+ */
 function scannerAppLocationFactory({client}) {
+  /**
+   * GET /scanner-app-location - get scanner app location.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {ScannerAppLocationQuery} [opts.query] - Query params (scheduleId, routeId, date, includeTravelledPath)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>} response.data may contain location
+   */
   function get({token, query = {}, headers}) {
     return client({
       url: "/scanner-app-location",