Merge pull request #1 from dev-aces/allow-number-outsum

v.1.1.0 Allow number type for outSum, fixed special symbols in userParams

Author: ArturAmpilogov

.github/workflows/release_package.yml

@@ -3,7 +3,7 @@ on:
   workflow_dispatch:
     inputs:
       release-type:
-        description: 'Release type (one of): patch, minor, major, prerelease'
+        description: 'Release type (one of): major, minor, patch, prerelease'
         required: true
 jobs:
   release:

.prettierignore

@@ -0,0 +1 @@
+CHANGELOG.md

CHANGELOG.md

@@ -7,18 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Allow outSum to be a number or a formatted string.
+
+### Fixed
+
+- Fixed calculating signature value with special symbols in userParams (@ in emails).
+- Renamed Email to EMail field in IRobokassaResponse.
+
 ## 1.0.1 - 2023-05-13
+
 ### Changed
+
 - Translated README.md to Russian language.
 
 ## 1.0.0 - 2023-05-12
+
 ### Added
+
 - Added `isTest` mode parameter.
 - Added `receipt` parameter to conform the fiscal policy.
 - Added unit tests.
 
 ### Changed
+
 - Rewrote the forked code to use TypeScript.
 
 ### Fixed
+
 - Semantic Version calculation errors in the old forked repositories.

README.md

@@ -1,6 +1,6 @@
 # Robokassa Node.JS
 
-Пакет Node.JS для [Robokassa](https://docs.robokassa.ru).
+Пакет [Robokassa](https://docs.robokassa.ru) для Node.JS.
 
 Поддерживает JavaScript и TypeScript.
 
@@ -29,13 +29,16 @@ const robokassa = new Robokassa({
   merchantLogin: 'my_merchant_login',
   password1: 'my_password_1',
   password2: 'my_password_2',
+  // hashAlgorithm: 'md5' (default)
+  // isTest: false (default)
+  // url: 'https://auth.robokassa.ru/Merchant/Index.aspx' (default)
 });
 
 const url = robokassa.generatePaymentUrl({
-  outSum: '10.00',
+  outSum: '10.00', // или outSum: 10 (type number)
   description: 'Тестовый продукт',
-  // Пользовательские параметры должны начинаться с "shp_" | "Shp_" | "SHP_".
-  // Они будут переданы на ваш сервер вызовом Робокассы после оплаты.
+  // Пользовательские параметры должны начинаться с "shp_" или "Shp_" или "SHP_".
+  // Они будут переданы на ваш сервер вызовом Робокассы после оплаты в том же виде.
   userParameters: {
     shp_interface: 'link',
     shp_user_id: 'user_id',
@@ -68,7 +71,11 @@ const { Robokassa } = require('@dev-aces/robokassa');
 
 ## Webhooks
 
-Если в настройках Робокассы исользуется метод `POST` для отправки рузультатов (рекомендуется), то можно использовать Express.JS для обработки запросов:
+Result URL для подтверждения и обработки успешной оплаты.
+
+Для перенаправления браузера пользователя после оплаты Робокасса использует параметры Success URL и Failure URL. Не перепутайте.
+
+Если в настройках Робокассы исользуется метод `POST` для отправки Result URL (рекомендуется), то можно использовать следующий код Express.JS для обработки запросов:
 
 TypeScript:
 
@@ -84,12 +91,12 @@ const robokassa = new Robokassa({
 
 const app = express();
 
-// Указать данный URL для отправки результатов в настройках Робокассы
+// Указать данный URL для отправки успешного результаты оплаты в настройках Робокассы (Method of sending data to Result Url)
 app.post('/payment/result', function (req: Request, res: Response) {
   const robokassaResponse = req.body as IRobokassaResponse;
 
   if (robokassa.checkPayment(robokassaResponse)) {
-    console.log('PAYMENT SUCCESS!');
+    console.log('Successful payment!');
 
     const { InvId, /* OutSum, shp_interface, ...etc */ } = robokassaResponse;
 
@@ -102,18 +109,6 @@ app.post('/payment/result', function (req: Request, res: Response) {
 });
 ```
 
-Опционально можно добавить webhook APIs для оповещения об успешной и неуспешной оплате.
-
-```typescript
-app.get('/payment/true', function (req: Request, res: Response) {
-  res.render('payment_true');
-});
-
-app.get('/payment/false', function (req: Request, res: Response) {
-  res.render('payment_false');
-});
-```
-
 ## Внесение изменений
 
 Сделайте fork репозитория, изменения, убедитесь что успешно пройдены тесты и форматирование:

src/Robokassa.spec.ts

@@ -76,6 +76,54 @@ describe('#Robokassa', () => {
         );
       });
 
+      it('should generate url without IsTest', () => {
+        const testRobokassa = new Robokassa({
+          merchantLogin: 'my_merchant_login',
+          password1: 'my_password1',
+          password2: 'my_password2',
+          isTest: false,
+        });
+        const result = testRobokassa.generatePaymentUrl({
+          description: 'Товар 1',
+          invId: 42,
+          outSum: '100.00',
+        });
+        expect(result).toEqual(
+          'https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=my_merchant_login&Description=%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%201&InvId=42&OutSum=100.00&SignatureValue=7642fdc174d0aabe022d992afd59f276',
+        );
+      });
+
+      it('should format outSum to fixed string when number type is passed', () => {
+        const testRobokassa = new Robokassa({
+          merchantLogin: 'my_merchant_login',
+          password1: 'my_password1',
+          password2: 'my_password2',
+        });
+        const result = testRobokassa.generatePaymentUrl({
+          description: 'Товар 1',
+          invId: 42,
+          outSum: 100,
+        });
+        expect(result).toEqual(
+          'https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=my_merchant_login&Description=%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%201&InvId=42&OutSum=100.00&SignatureValue=7642fdc174d0aabe022d992afd59f276',
+        );
+      });
+
+      it('should pass InvId=0 when invId is not specified', () => {
+        const testRobokassa = new Robokassa({
+          merchantLogin: 'my_merchant_login',
+          password1: 'my_password1',
+          password2: 'my_password2',
+        });
+        const result = testRobokassa.generatePaymentUrl({
+          description: 'Товар 1',
+          outSum: '100.00',
+        });
+        expect(result).toEqual(
+          'https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=my_merchant_login&Description=%D0%A2%D0%BE%D0%B2%D0%B0%D1%80%201&OutSum=100.00&InvId=0&SignatureValue=cd9e54da801539e5bb4d6d371f6fef3f',
+        );
+      });
+
       it('should generate url with maximum parameters', () => {
         const result = robokassa.generatePaymentUrl({
           description: 'Услуги по разработке',

src/Robokassa.ts

@@ -22,6 +22,10 @@ export class Robokassa {
       order.invId = 0;
     }
 
+    if (typeof order.outSum === 'number') {
+      order.outSum = order.outSum.toFixed(2);
+    }
+
     const { userParameters, receipt, ...usualOrderParameters } = order;
 
     const orderWithCapitalizedKeys = Object.fromEntries(

src/internal/calculateReceivingSignatureValue.spec.ts

@@ -28,7 +28,7 @@ describe('#calculateReceivingSignatureValue', () => {
       });
 
       expect(result).toEqual(
-        '200.00:84:my_password2:Shp_email=test%40test.com:Shp_user_id=123',
+        '200.00:84:my_password2:Shp_email=test@test.com:Shp_user_id=123',
       );
     });
   });

src/internal/calculateReceivingSignatureValue.ts

@@ -16,9 +16,8 @@ export const buildExpectedReceivingSignatureString = ({
   );
 
   const signatureUserParams =
-    userParameters.map(
-      ([key, value]) => `${key}=${encodeURIComponent(value?.toString() ?? '')}`,
-    ) ?? [];
+    userParameters.map(([key, value]) => `${key}=${value?.toString() ?? ''}`) ??
+    [];
   // Порядок параметров важен, сортируем по алфавиту
   signatureUserParams.sort((a, b) => a.localeCompare(b));
 

src/internal/calculateSendingSignatureValue.spec.ts

@@ -34,7 +34,7 @@ describe('#calculateSendingSignatureValue', () => {
       });
 
       expect(result).toEqual(
-        'my_merchant_login:200.00:84:my_password1:Shp_email=test%40test.com:Shp_user_id=123',
+        'my_merchant_login:200.00:84:my_password1:Shp_email=test@test.com:Shp_user_id=123',
       );
     });
 

src/internal/calculateSendingSignatureValue.ts

@@ -12,7 +12,7 @@ export const buildSendingSignatureString = ({
 }) => {
   const signatureUserParams =
     Object.entries(order.userParameters ?? {}).map(
-      ([key, value]) => `${key}=${encodeURIComponent(value?.toString() ?? '')}`,
+      ([key, value]) => `${key}=${value?.toString() ?? ''}`,
     ) ?? [];
   // Порядок параметров важен, сортируем по алфавиту
   signatureUserParams.sort((a, b) => a.localeCompare(b));