btrz-api-client 8.29.0 → 8.31.0

package/src/endpoints/notifications/twilio.js

@@ -1,12 +1,28 @@
 const {
   authorizationHeaders
-} = require("./../endpoints_helpers.js");
+} = require("../endpoints_helpers.js");
 
+/**
+ * Factory for twilio API (btrz-api-notifications).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ phoneNumbers: { all: function, create: function }, sms: { create: function }, whatsapp: { create: function } }}
+ */
 function twilioFactory({
   client, internalAuthTokenProvider
 }) {
   return {
     phoneNumbers: {
+      /**
+       * GET /twilio/phone-numbers/:isocode - list Twilio phone numbers for country isocode. API does not accept query params.
+       * @param {Object} opts
+       * @param {string} opts.isocode - Country ISO code
+       * @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({
         isocode, token, jwtToken, query = {}, headers
       }) {
@@ -15,6 +31,15 @@ function twilioFactory({
           headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
         });
       },
+      /**
+       * POST /twilio/phone-numbers - create/provision a Twilio phone number.
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {Object} [opts.phoneNumberData] - Phone number payload
+       * @param {Object} [opts.headers] - Optional headers
+       * @returns {Promise<import("axios").AxiosResponse>}
+       */
       create({
         token, jwtToken, phoneNumberData = {}, headers
       }) {
@@ -29,6 +54,15 @@ function twilioFactory({
       }
     },
     sms: {
+      /**
+       * POST /twilio/sms - send SMS via Twilio.
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {Object} [opts.smsMsg] - SMS message payload
+       * @param {Object} [opts.headers] - Optional headers
+       * @returns {Promise<import("axios").AxiosResponse>}
+       */
       create({
         token, jwtToken, smsMsg = {}, headers
       }) {
@@ -43,6 +77,15 @@ function twilioFactory({
       }
     },
     whatsapp: {
+      /**
+       * POST /twilio/whatsapp - send WhatsApp message via Twilio.
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {Object} [opts.whatsappMsg] - WhatsApp message payload
+       * @param {Object} [opts.headers] - Optional headers
+       * @returns {Promise<import("axios").AxiosResponse>}
+       */
       create({
         token, jwtToken, whatsappMsg = {}, headers
       }) {
@@ -56,7 +99,6 @@ function twilioFactory({
         });
       }
     }
-
   };
 }
 

package/src/endpoints/operations/accounting_items.js

@@ -2,9 +2,34 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Query params for GET /accounting-items (btrz-api-operations). See accounting-items get-handler getSpec().
+ * @typedef {Object} AccountingItemsListQuery
+ * @property {number} [page] - Page number (20 records per page)
+ * @property {string} [shiftId] - Shift id (ObjectId format)
+ * @property {string} [type] - "account_payable" | "account_receivable"
+ * @property {string} [trxId] - Transaction id (ObjectId format)
+ * @property {string} [status] - Comma-separated statuses: created, paid, waiting for payment
+ */
+
+/**
+ * Factory for accounting-items API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} accounting-items API methods
+ */
 function accountingItemsFactory({
   client, internalAuthTokenProvider
 }) {
+  /**
+   * GET /accounting-items - list accounting items.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {AccountingItemsListQuery} [opts.query] - Query params (all optional)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     query = {},
@@ -20,6 +45,14 @@ function accountingItemsFactory({
     });
   }
 
+  /**
+   * GET /accounting-items/:accountingItemId - get accounting item by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} opts.accountingItemId - Accounting item id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({
     accountingItemId, token, headers
   }) {

package/src/endpoints/operations/applied_insurance.js

@@ -1,18 +1,40 @@
-const { authorizationHeaders } = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
-function appliedInsuranceFactory({ client, internalAuthTokenProvider }) {
+/**
+ * Factory for applied-insurance API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} applied-insurance API methods
+ */
+/**
+ * Query params for GET /appliedInsurances (btrz-api-operations). See get-applied-insurances getSpec().
+ * Deprecated: use GET /transactions/:transactionId/applied-insurance.
+ * @typedef {Object} AppliedInsurancesListQuery
+ * @property {string} trxId - Associated transaction id (required)
+ */
 
-  function all({ token, jwtToken, trxId, headers }) {
+function appliedInsuranceFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /appliedInsurances - list applied insurances by transaction id (query: trxId).
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.trxId - Transaction id (required, sent as query param)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function all({token, jwtToken, trxId, headers}) {
     const query = {trxId};
 
     return client({
-      url: `/appliedInsurances`,
+      url: "/appliedInsurances",
       params: query,
-      headers: authorizationHeaders({ token , jwtToken, internalAuthTokenProvider, headers })
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
     });
   }
 
-  return { all };
+  return {all};
 }
 
 module.exports = appliedInsuranceFactory;

package/src/endpoints/operations/calendar_entries.js

@@ -1,8 +1,31 @@
-const { authorizationHeaders } = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
-function calendarEntriesFactory({ client, internalAuthTokenProvider }) {
+/**
+ * Query params for GET /calendar-entries (btrz-api-operations). See get-calendar-entries getSpec().
+ * @typedef {Object} CalendarEntriesListQuery
+ * @property {string} from - Start travel date (required, format yyyy-mm-dd)
+ * @property {string} to - End travel date (required, format yyyy-mm-dd, max 31 days range)
+ * @property {string} [providerId] - Provider id when consuming from a non-main account
+ * @property {string} [channels] - Filter by channel (e.g. websales); must be one of allowed channels
+ */
 
-  function all({ token, query = {}, headers }) {
+/**
+ * Factory for calendar-entries API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} calendar-entries API methods
+ */
+function calendarEntriesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * GET /calendar-entries - list calendar entries.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {CalendarEntriesListQuery} [opts.query] - Query params (from, to required)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
+  function all({token, query = {}, headers}) {
     return client({
       url: "/calendar-entries",
       params: query,
@@ -11,8 +34,8 @@ function calendarEntriesFactory({ client, internalAuthTokenProvider }) {
   }
 
   return {
-    all,
+    all
   };
 }
 
-module.exports = calendarEntriesFactory;
+module.exports = calendarEntriesFactory;

package/src/endpoints/operations/docs.js

@@ -1,4 +1,15 @@
-function docsFactory({client}) {
+/**
+ * Factory for API docs (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} docs API methods
+ */
+function docsFactory({client, internalAuthTokenProvider: _internalAuthTokenProvider}) {
+  /**
+   * GET /api-docs-v2 - get API docs.
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get() {
     return client.get("/api-docs-v2", {});
   }

package/src/endpoints/operations/external-bookings.js

@@ -1,6 +1,22 @@
 const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Factory for external-bookings API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} external-bookings API methods
+ */
 function externalBookingsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /external-bookings - create external booking. 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.externalBooking - External booking payload
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function create({jwtToken, token, externalBooking, headers, query = {}}) {
     return client({
       url: "/external-bookings",
@@ -11,6 +27,15 @@ function externalBookingsFactory({client, internalAuthTokenProvider}) {
     });
   }
 
+  /**
+   * DELETE /external-bookings/:ticketId - remove external booking. 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.ticketId - Ticket id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function remove({jwtToken, token, ticketId, headers}) {
     return client({
       url: `/external-bookings/${ticketId}`,

package/src/endpoints/operations/flexpasses.js

@@ -1,6 +1,23 @@
-const {authorizationHeaders} = require("./../endpoints_helpers");
+const {authorizationHeaders} = require("./../endpoints_helpers.js");
 
+/**
+ * Factory for flexpasses API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} flexpasses API methods
+ */
 function flexpassesFactory({client, internalAuthTokenProvider}) {
+  /**
+   * DELETE /flexpasses/:flexpassId/scannings/:tripId - delete scan by trip 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.flexpassId - Flexpass id
+   * @param {string} opts.tripId - Trip id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function deleteScanBytripId({jwtToken, token, flexpassId, tripId, headers}) {
     return client({
       url: `/flexpasses/${flexpassId}/scannings/${tripId}`,

package/src/endpoints/operations/loans.js

@@ -1,10 +1,36 @@
 const {
   authorizationHeaders
-} = require("./../endpoints_helpers");
+} = require("./../endpoints_helpers.js");
 
+/**
+ * Query params for GET /loans (btrz-api-operations). See loans get-handler getSpec().
+ * @typedef {Object} LoansListQuery
+ * @property {number} [page] - Page number (20 records per page)
+ * @property {string} [shiftId] - Shift id (ObjectId format)
+ * @property {string} [type] - "loan" | "re-payment"
+ * @property {string} [trxId] - Transaction id (ObjectId format)
+ * @property {string} [status] - Comma-separated statuses: created, paid, waiting for payment
+ * @property {string} [providerId] - Provider id (for agencies)
+ */
+
+/**
+ * Factory for loans API (btrz-api-operations).
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {Object} loans API methods
+ */
 function loansFactory({
   client, internalAuthTokenProvider
 }) {
+  /**
+   * GET /loans - list loans.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {LoansListQuery} [opts.query] - Query params (all optional)
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function all({
     token,
     query = {},
@@ -20,6 +46,14 @@ function loansFactory({
     });
   }
 
+  /**
+   * GET /loans/:loanId - get loan by id. API does not accept query params.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} opts.loanId - Loan id
+   * @param {Object} [opts.headers] - Optional headers
+   * @returns {Promise<import("axios").AxiosResponse>}
+   */
   function get({
     loanId, token, headers
   }) {