btrz-api-client 8.53.0 → 8.54.0

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

@@ -3,12 +3,27 @@
 var _require = require("../endpoints_helpers.js"),
     authorizationHeaders = _require.authorizationHeaders;
 
+/**
+ * Body for PUT /external-wallets/saldo-max/:walletId/movements (ExternalWalletMovementData).
+ * @typedef {Object} ExternalWalletMovementData
+ * @property {number} amount
+ * @property {'purchase'|'refund'} type - `purchase` withdraws balance; `refund` adds balance (ADO)
+ * @property {string|number} nip - Four-digit NIP; prefer string to preserve leading zeros (e.g. "0202")
+ * @property {string} transactionId - Betterez transaction id; sent to ADO as erpcoOperationId
+ * @property {boolean} [sendMail] - Optional; ADO receipt email on success
+ */
+
 /**
  * Factory for external-wallets API (btrz-api-inventory). SaldoMax external wallets only.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
- * @returns {{ saldoMax: { all: function, get: function, create: function, update: function, movements: { create: function } } }}
+ * @returns {{
+ *   saldoMax: {
+ *     all: function, get: function, create: function, update: function,
+ *     nip: object, authorization: { create: function }, movements: { create: function }
+ *   }
+ * }}
  */
 
 
@@ -16,7 +31,12 @@ function externalWalletsFactory(_ref) {
   var client = _ref.client,
       internalAuthTokenProvider = _ref.internalAuthTokenProvider;
 
-  /** @type {{ all: function, create: function, get: function, update: function, movements: object }} */
+  /**
+   * @type {{
+   *   all: function, create: function, get: function, update: function,
+   *   nip: object, authorization: { create: function }, movements: object
+   * }}
+   */
   var saldoMax = {
     /**
      * GET /external-wallets/saldo-max - list SaldoMax external wallets (paginated).
@@ -144,25 +164,60 @@ function externalWalletsFactory(_ref) {
       }
     },
     /** @type {{ create: function }} */
-    movements: {
+    authorization: {
       /**
-       * PUT /external-wallets/saldo-max/:walletId/movements - add movement to wallet.
+       * POST /external-wallets/saldo-max/:walletId/authorization — Validate NIP with ADO Saldo Max (authorize wallet).
+       * Typical: `authorization.create({ walletId, nip, token, jwtToken, headers })` — body sent as `{ nip }`.
+       * Alternate body: pass `nipAuthorization` instead of `nip` (wrapper form per API).
        * @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 (amount, type: payment|refund|manual, reason, nip)
+       * @param {string} opts.walletId - Saldo Max wallet id (idWallet)
+       * @param {string|number} [opts.nip] - Four-digit NIP (use with `token`/`jwtToken` as above, or use nipAuthorization)
+       * @param {{ nip: string|number }} [opts.nipAuthorization] - Wrapped NIP payload instead of `nip`
        * @param {Object} [opts.headers] - Optional headers
-       * @returns {Promise<import("axios").AxiosResponse<{ externalWallet: Object }>>}
-       * @throws When response is 4xx/5xx (400, 401, 403 INVALID_NIP/WALLET_BLOCKED/WALLET_NOT_ACTIVE, 404, 500)
+       * @returns {Promise<import("axios").AxiosResponse<{ valid: boolean }>>}
+       * @throws When response is 4xx/5xx (400 WRONG_DATA, INVALID_WALLET_ID, VALIDATE_NIP_WALLET_MISMATCH;
+       *   401; 403 incorrect NIP; 404; 502; 503; 500)
        */
       create: function create(_ref7) {
         var token = _ref7.token,
             jwtToken = _ref7.jwtToken,
             walletId = _ref7.walletId,
-            movement = _ref7.movement,
+            nip = _ref7.nip,
+            nipAuthorization = _ref7.nipAuthorization,
             headers = _ref7.headers;
 
+        var data = nipAuthorization != null ? { nipAuthorization: nipAuthorization } : { nip: nip };
+        return client({
+          url: "/external-wallets/saldo-max/" + walletId + "/authorization",
+          method: "post",
+          headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers }),
+          data: data
+        });
+      }
+    },
+    /** @type {{ create: function }} */
+    movements: {
+      /**
+       * PUT /external-wallets/saldo-max/:walletId/movements — Validate NIP, balance, then apply movement in ADO.
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {string} opts.walletId - Saldo Max wallet id (idWallet)
+       * @param {ExternalWalletMovementData} opts.movement
+       * @param {Object} [opts.headers] - Optional headers
+       * @returns {Promise<import("axios").AxiosResponse<{ result: { operationId?: string, region?: string } }>>}
+       * @throws When response is 4xx/5xx (400 WRONG_DATA, INVALID_MOVEMENT_*, INSUFFICIENT_FUNDS,
+       *   VALIDATE_NIP_WALLET_MISMATCH; 401; 403 INVALID_NIP, WALLET_NOT_ACTIVE; 404; 502; 503; 500)
+       */
+      create: function create(_ref8) {
+        var token = _ref8.token,
+            jwtToken = _ref8.jwtToken,
+            walletId = _ref8.walletId,
+            movement = _ref8.movement,
+            headers = _ref8.headers;
+
         return client({
           url: "/external-wallets/saldo-max/" + walletId + "/movements",
           method: "put",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "btrz-api-client",
-  "version": "8.53.0",
+  "version": "8.54.0",
   "description": "Api client for Betterez endpoints",
   "main": "index.js",
   "scripts": {

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

@@ -2,15 +2,35 @@ const {
   authorizationHeaders
 } = require("../endpoints_helpers.js");
 
+/**
+ * Body for PUT /external-wallets/saldo-max/:walletId/movements (ExternalWalletMovementData).
+ * @typedef {Object} ExternalWalletMovementData
+ * @property {number} amount
+ * @property {'purchase'|'refund'} type - `purchase` withdraws balance; `refund` adds balance (ADO)
+ * @property {string|number} nip - Four-digit NIP; prefer string to preserve leading zeros (e.g. "0202")
+ * @property {string} transactionId - Betterez transaction id; sent to ADO as erpcoOperationId
+ * @property {boolean} [sendMail] - Optional; ADO receipt email on success
+ */
+
 /**
  * Factory for external-wallets API (btrz-api-inventory). SaldoMax external wallets only.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
- * @returns {{ saldoMax: { all: function, get: function, create: function, update: function, movements: { create: function } } }}
+ * @returns {{
+ *   saldoMax: {
+ *     all: function, get: function, create: function, update: function,
+ *     nip: object, authorization: { create: function }, movements: { create: function }
+ *   }
+ * }}
  */
 function externalWalletsFactory({client, internalAuthTokenProvider}) {
-  /** @type {{ all: function, create: function, get: function, update: function, movements: object }} */
+  /**
+   * @type {{
+   *   all: function, create: function, get: function, update: function,
+   *   nip: object, authorization: { create: function }, movements: object
+   * }}
+   */
   const saldoMax = {
     /**
      * GET /external-wallets/saldo-max - list SaldoMax external wallets (paginated).
@@ -111,17 +131,45 @@ function externalWalletsFactory({client, internalAuthTokenProvider}) {
       }
     },
     /** @type {{ create: function }} */
+    authorization: {
+      /**
+       * POST /external-wallets/saldo-max/:walletId/authorization — Validate NIP with ADO Saldo Max (authorize wallet).
+       * Typical: `authorization.create({ walletId, nip, token, jwtToken, headers })` — body sent as `{ nip }`.
+       * Alternate body: pass `nipAuthorization` instead of `nip` (wrapper form per API).
+       * @param {Object} opts
+       * @param {string} [opts.token] - API key
+       * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+       * @param {string} opts.walletId - Saldo Max wallet id (idWallet)
+       * @param {string|number} [opts.nip] - Four-digit NIP (use with `token`/`jwtToken` as above, or use nipAuthorization)
+       * @param {{ nip: string|number }} [opts.nipAuthorization] - Wrapped NIP payload instead of `nip`
+       * @param {Object} [opts.headers] - Optional headers
+       * @returns {Promise<import("axios").AxiosResponse<{ valid: boolean }>>}
+       * @throws When response is 4xx/5xx (400 WRONG_DATA, INVALID_WALLET_ID, VALIDATE_NIP_WALLET_MISMATCH;
+       *   401; 403 incorrect NIP; 404; 502; 503; 500)
+       */
+      create: ({token, jwtToken, walletId, nip, nipAuthorization, headers}) => {
+        const data = nipAuthorization != null ? {nipAuthorization} : {nip};
+        return client({
+          url: `/external-wallets/saldo-max/${walletId}/authorization`,
+          method: "post",
+          headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}),
+          data
+        });
+      }
+    },
+    /** @type {{ create: function }} */
     movements: {
       /**
-       * PUT /external-wallets/saldo-max/:walletId/movements - add movement to wallet.
+       * PUT /external-wallets/saldo-max/:walletId/movements — Validate NIP, balance, then apply movement in ADO.
        * @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 (amount, type: payment|refund|manual, reason, nip)
+       * @param {string} opts.walletId - Saldo Max wallet id (idWallet)
+       * @param {ExternalWalletMovementData} opts.movement
        * @param {Object} [opts.headers] - Optional headers
-       * @returns {Promise<import("axios").AxiosResponse<{ externalWallet: Object }>>}
-       * @throws When response is 4xx/5xx (400, 401, 403 INVALID_NIP/WALLET_BLOCKED/WALLET_NOT_ACTIVE, 404, 500)
+       * @returns {Promise<import("axios").AxiosResponse<{ result: { operationId?: string, region?: string } }>>}
+       * @throws When response is 4xx/5xx (400 WRONG_DATA, INVALID_MOVEMENT_*, INSUFFICIENT_FUNDS,
+       *   VALIDATE_NIP_WALLET_MISMATCH; 401; 403 INVALID_NIP, WALLET_NOT_ACTIVE; 404; 502; 503; 500)
        */
       create: ({token, jwtToken, walletId, movement, headers}) => {
         return client({

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

@@ -98,9 +98,9 @@ describe("inventory/external-wallets", () => {
       const walletId = "wallet-id-123";
       const movement = {
         amount: 100,
-        type: "credit",
-        reason: "refund",
-        nip: "1234"
+        type: "refund",
+        nip: "1234",
+        transactionId: "txn-refund-001"
       };
 
       axiosMock.onPut(`/external-wallets/saldo-max/${walletId}/movements`).reply(expectRequest({
@@ -115,13 +115,45 @@ describe("inventory/external-wallets", () => {
       });
     });
 
-    it("should create a debit movement for a Saldo Max wallet", async () => {
+    it("should authorize NIP for a Saldo Max wallet (root nip body)", async () => {
+      const walletId = "749";
+      const nip = "1357";
+
+      axiosMock.onPost(`/external-wallets/saldo-max/${walletId}/authorization`).reply(expectRequest({
+        statusCode: 200, token, jwtToken, body: {nip}
+      }));
+
+      return api.inventory.externalWallets.saldoMax.authorization.create({
+        walletId,
+        nip,
+        token,
+        jwtToken
+      });
+    });
+
+    it("should authorize NIP for a Saldo Max wallet (nipAuthorization wrapper)", async () => {
+      const walletId = "749";
+      const nipAuthorization = {nip: "2468"};
+
+      axiosMock.onPost(`/external-wallets/saldo-max/${walletId}/authorization`).reply(expectRequest({
+        statusCode: 200, token, jwtToken, body: {nipAuthorization}
+      }));
+
+      return api.inventory.externalWallets.saldoMax.authorization.create({
+        jwtToken,
+        token,
+        walletId,
+        nipAuthorization
+      });
+    });
+
+    it("should create a purchase (withdraw) movement for a Saldo Max wallet", async () => {
       const walletId = "wallet-id-456";
       const movement = {
         amount: 50.75,
-        type: "debit",
-        reason: "purchase",
-        nip: "9876"
+        type: "purchase",
+        nip: "9876",
+        transactionId: "txn-purchase-002"
       };
 
       axiosMock.onPut(`/external-wallets/saldo-max/${walletId}/movements`).reply(expectRequest({
@@ -140,9 +172,9 @@ describe("inventory/external-wallets", () => {
       const walletId = "wallet-id-789";
       const movement = {
         amount: 0,
-        type: "adjustment",
-        reason: "correction",
-        nip: "0000"
+        type: "purchase",
+        nip: "0000",
+        transactionId: "txn-zero-003"
       };
 
       axiosMock.onPut(`/external-wallets/saldo-max/${walletId}/movements`).reply(expectRequest({