@yosle/tropipayjs 0.2.1 → 0.2.3

package/README.md

@@ -133,6 +133,33 @@ console.log(paylink.shortUrl);
 
 For more examples, please refer to the [Documentation](https://github.com/yosle/tropipayjs/blob/master/docs/)
 
+### Refunding a Transaction
+
+The library provides two methods for handling refunds with 2FA confirmation:
+
+#### Request a Security Code (Production only)
+
+In **Production** mode, you must first request a 2FA code via SMS:
+
+```javascript
+await tpp.requestSecurityCode();
+// An SMS with the code will be sent to your phone
+```
+
+#### Refund a Movement
+
+Once you have the security code (or in Development mode), you can refund a transaction:
+
+```javascript
+// Development mode — use the default test code
+const result = await tpp.refundMovement("ORD-123456", 5000, "123456");
+
+// Production mode — pass the code received via SMS
+const result = await tpp.refundMovement("ORD-123456", 5000, "847291");
+```
+
+**Note:** The refund endpoint requires the `ALLOW_REFUND` scope and 2FA to be enabled on your Tropipay account. In Development mode the default 2FA code is `123456` unless you have configured the Authenticator app.
+
 # Contributing
 
 If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Supply Chain Security Plan
+
+## 1. Lockfile Integrity
+- Always commit `package-lock.json` — it pins exact sub-dependency versions
+- Verify integrity: `npm audit signatures` after install (requires npm 9+)
+
+## 2. Automated Scanning
+```yaml
+# CI steps
+- run: npm audit --audit-level=high    # fail on high/critical known CVEs
+- run: npx socket-cli scan             # detect protestware, typo-squatting, obfuscation
+```
+- [Socket.dev](https://socket.dev) — free tier detects behavioral risks (not just CVEs)
+- [Snyk](https://snyk.io) — broader CVE coverage, integrates with GitHub
+
+## 3. Dependency Updates
+- Enable **Dependabot** or **Renovate** — auto-create PRs for security patches
+- Review every new dependency before adding: check downloads, maintenance, publisher
+
+## 4. Overrides for Transitive Dependencies
+```json
+{
+  "overrides": {
+    "axios": "1.18.1",
+    "semver": "^7.6.0"
+  }
+}
+```
+Use `overrides` to force-patch transitive deps when upstream is slow to release.
+
+## 5. Minimal Surface Area
+- Fewer dependencies = fewer attack vectors
+- Regularly audit with `npm ls --depth=0` and remove unused packages
+
+## 6. SBOM Generation
+```bash
+npm sbom --sbom-format cyclonedx > sbom.json
+```
+Generate a Software Bill of Materials for compliance and tracking.
+
+## 7. Package Provenance
+- Prefer packages with [provenance attestations](https://docs.npmjs.com/generating-provenance-statements) (npm publish --provenance)
+- Check publisher reputation and maintainer count before adding

package/api/TropipayAPI.d.ts

@@ -5,19 +5,17 @@
  *
  */
 import { Axios } from "axios";
-import { TropipayConfig, AccountBalance, Country, PaymentLink, MediationPaymentCardConfig, LoginResponse } from "../interfaces";
+import { TropipayConfig, AccountBalance, Country, PaymentLink, MediationPaymentCardConfig, LoginResponse, RefundResponse } from "../interfaces";
 type ServerMode = "Development" | "Production";
 import TropipayHooks from "../hooks/TropipayHooks";
 import PaymentCard from "../paymentcard/PaymentCard";
 import MediationPaymentCard from "../mediationPaymentCard/MediationPaymentCard";
 import DepositAccounts from "../depositAccount/depositAccounts";
-import Accounts from "../accounts/accounts";
 export declare class Tropipay {
     readonly clientId: string;
     readonly clientSecret: string;
     readonly scopes: String[];
     request: Axios;
-    loginRequest: Axios;
     static accessToken: string | null;
     static refreshToken: string | null;
     static expiresIn: number | null;
@@ -26,7 +24,6 @@ export declare class Tropipay {
     paymentCards: PaymentCard;
     depositAccounts: DepositAccounts;
     mediationPaymentCard: MediationPaymentCard;
-    accounts: Accounts;
     /**
      * Initializes a new instance of the Tropipay class.
      *
@@ -85,10 +82,39 @@ export declare class Tropipay {
      * belonging or not to the TropiPay platform with the particularity
      * that the payment will be held in custody or retained until it is
      * released with the approval of the payer.
+     * @deprecated This method is no longer supported and may be removed in a future release.
      * @see https://tpp.stoplight.io/docs/tropipay-api-doc/12a128ff971e4-creating-a-mediation-payment-card
      * @param config Payload with the payment details
      */
     createMediationPaymentCard(config: MediationPaymentCardConfig): Promise<PaymentLink>;
+    /**
+     * Refund a completed transaction.
+     * Requires 2FA enabled and ALLOW_REFUND permission on the Tropipay account.
+     *
+     * In Development mode, `securityCode` defaults to `"123456"` when omitted.
+     * In Production mode, you must first call `requestSecurityCode()` to receive
+     * the 2FA code via SMS, then pass it as the `securityCode` parameter.
+     *
+     * @see https://doc.tropipay.com/docs/api-reference/movements#refund-a-transaction
+     * @param orderCode Code of the order/transaction to refund (e.g. "ORD-123456")
+     * @param amount Amount to refund in cents (e.g. 5000 = 50.00 USD/EUR)
+     * @param securityCode 2FA confirmation code. Use "123456" in Development or
+     * the code received via SMS in Production (obtained via requestSecurityCode()).
+     */
+    refundMovement(orderCode: string, amount: number, securityCode: string): Promise<RefundResponse>;
+    /**
+     * Request a 2FA security code to be sent via SMS for confirming sensitive
+     * operations like refunds.
+     *
+     * In Production mode, you must call this method first to trigger an SMS with
+     * the code, then use the received code when calling `refundMovement()`.
+     * In Development mode this is not required as the default code "123456"
+     * is used automatically.
+     *
+     * @see https://doc.tropipay.com/docs/api-reference/movements#refund-a-transaction
+     * @returns The API response confirming the code was sent
+     */
+    requestSecurityCode(type?: "sms" | "email"): Promise<any>;
 }
 export declare class ClientSideUtils {
     constructor(tropipayInstance: Tropipay);
@@ -102,5 +128,6 @@ export declare const Scopes: {
     ALLOW_GET_BALANCE: string;
     ALLOW_GET_MOVEMENT_LIST: string;
     ALLOW_GET_CREDENTIAL: string;
+    ALLOW_REFUND: string;
 };
 export {};

package/index.d.ts

@@ -39,71 +39,36 @@ interface UserHookSubscribed extends UserHook {
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Interface for creating payment links/cards
- * @see https://tpp.stoplight.io/docs/tropipay-api-doc/b3A6ODgyNTM3OQ-create-a-new-pay-link-charge
- */
 interface PaymentLinkPayload {
-    /** Account ID where the funds will be received if compatible */
-    accountId?: number;
-    /** Reference code for the payment, preferred to be unique */
     reference: string;
-    /** Short description of the payment */
     concept: string;
-    /** Whether to mark this payment link as favorite */
     favorite: boolean;
-    /** Amount to charge in the specified currency */
     amount: number;
-    /** Currency code (EUR, USD, etc.) */
     currency: string;
-    /** Detailed description of the payment */
     description: string;
-    /** If true, the payment link can only be used once */
     singleUse: boolean;
-    /** Reason ID for the payment */
     reasonId: number;
-    /** Number of days until the payment link expires */
     expirationDays: number;
-    /** Language code for the payment page (en, es, etc.) */
     lang: string;
-    /** URL to redirect after successful payment */
     urlSuccess: string;
-    /** URL to redirect after failed payment */
     urlFailed: string;
-    /** Webhook URL for payment notifications */
     urlNotification: string;
-    /** Date when the service will be provided (ISO format) */
     serviceDate: string;
-    /** Client information for the payment */
     client?: {
-        /** Client's first name */
         name?: string;
-        /** Client's last name */
         lastName?: string;
-        /** Client's address */
         address?: string;
-        /** Client's phone number */
         phone?: string;
-        /** Client's email address */
         email?: string;
-        /** Client's country ID */
         countryId?: number;
-        /** Client's country ISO code */
         countryIso?: string;
-        /** Client's city */
         city: string;
-        /** Client's postal code */
         postCode: string;
-        /** Whether client accepted terms and conditions */
         termsAndConditions: boolean;
     } | null;
-    /** @deprecated If true, redirects directly to payment page */
     directPayment: boolean;
-    /** List of allowed payment methods */
     paymentMethods?: string[];
-    /** Base64 encoded image for the payment page */
     imageBase?: string;
-    /** Whether to save the payment token for future use */
     saveToken?: boolean;
 }
 interface PaymentLink extends PaymentLinkPayload {
@@ -203,6 +168,16 @@ type AccountDeposits = {
     count: number;
     rows: Deposit[];
 };
+type RefundResponse = {
+    id: number;
+    orderCode: string;
+    amount: number;
+    currency: string;
+    state: string;
+    type: string;
+    createdAt: string;
+    completedAt: string;
+};
 
 declare class TropipayHooks {
     private tropipay;
@@ -354,58 +329,6 @@ declare class DepositAccounts {
     delete(id: number): Promise<any>;
 }
 
-interface PaymentMethod {
-    slug: string;
-    name: string;
-    enabled: boolean;
-    allowedCurrencies: string[];
-}
-interface ServiceLimit {
-    value: number | null;
-    currency: string;
-}
-interface ServiceLimits {
-    min: ServiceLimit;
-    max: ServiceLimit;
-}
-interface Service {
-    slug: string;
-    enabled: boolean;
-    allowed_currencies: string[];
-    limits: ServiceLimits;
-}
-interface TropiCard {
-}
-interface Account {
-    id: number;
-    accountNumber: string;
-    userId: string;
-    alias: string;
-    balance: number;
-    pendingIn: number;
-    pendingOut: number;
-    state: number;
-    paymentEntityId: number;
-    currency: string;
-    type: number;
-    createdAt: string;
-    updatedAt: string;
-    isDefault: boolean;
-    groupId: number | null;
-    TropiCards: TropiCard[];
-    services: Service[];
-    paymentMethods: PaymentMethod[];
-}
-declare class Accounts {
-    private tropipay;
-    constructor(tropipayInstance: Tropipay);
-    /**
-     * List all accounts of the authenticated user
-     * @returns Array of Account objects
-     */
-    list(): Promise<Account[]>;
-}
-
 /**
  * Tropipayjs is a Typescript/Javascript library for the Tropipay API.
  *
@@ -420,7 +343,6 @@ declare class Tropipay {
     readonly clientSecret: string;
     readonly scopes: String[];
     request: Axios;
-    loginRequest: Axios;
     static accessToken: string | null;
     static refreshToken: string | null;
     static expiresIn: number | null;
@@ -429,7 +351,6 @@ declare class Tropipay {
     paymentCards: PaymentCard;
     depositAccounts: DepositAccounts;
     mediationPaymentCard: MediationPaymentCard;
-    accounts: Accounts;
     /**
      * Initializes a new instance of the Tropipay class.
      *
@@ -488,10 +409,39 @@ declare class Tropipay {
      * belonging or not to the TropiPay platform with the particularity
      * that the payment will be held in custody or retained until it is
      * released with the approval of the payer.
+     * @deprecated This method is no longer supported and may be removed in a future release.
      * @see https://tpp.stoplight.io/docs/tropipay-api-doc/12a128ff971e4-creating-a-mediation-payment-card
      * @param config Payload with the payment details
      */
     createMediationPaymentCard(config: MediationPaymentCardConfig): Promise<PaymentLink>;
+    /**
+     * Refund a completed transaction.
+     * Requires 2FA enabled and ALLOW_REFUND permission on the Tropipay account.
+     *
+     * In Development mode, `securityCode` defaults to `"123456"` when omitted.
+     * In Production mode, you must first call `requestSecurityCode()` to receive
+     * the 2FA code via SMS, then pass it as the `securityCode` parameter.
+     *
+     * @see https://doc.tropipay.com/docs/api-reference/movements#refund-a-transaction
+     * @param orderCode Code of the order/transaction to refund (e.g. "ORD-123456")
+     * @param amount Amount to refund in cents (e.g. 5000 = 50.00 USD/EUR)
+     * @param securityCode 2FA confirmation code. Use "123456" in Development or
+     * the code received via SMS in Production (obtained via requestSecurityCode()).
+     */
+    refundMovement(orderCode: string, amount: number, securityCode: string): Promise<RefundResponse>;
+    /**
+     * Request a 2FA security code to be sent via SMS for confirming sensitive
+     * operations like refunds.
+     *
+     * In Production mode, you must call this method first to trigger an SMS with
+     * the code, then use the received code when calling `refundMovement()`.
+     * In Development mode this is not required as the default code "123456"
+     * is used automatically.
+     *
+     * @see https://doc.tropipay.com/docs/api-reference/movements#refund-a-transaction
+     * @returns The API response confirming the code was sent
+     */
+    requestSecurityCode(type?: "sms" | "email"): Promise<any>;
 }
 declare class ClientSideUtils {
     constructor(tropipayInstance: Tropipay);
@@ -501,9 +451,7 @@ declare class ServerSideUtils {
     private tropipay;
     constructor(tropipayInstance: Tropipay);
     /**
-     * DEPRECATED Verify Topipay's signature on API V2 webhooks.
-     * @deprecated This method is deprecated and will be removed in future versions.
-     * Use the `verifySignatureV3` method from the `ServerSideUtils` class instead.
+     * Verify Topipay's signature on webhooks.
      * @param credentials Credential object or Tropipay instance
      * @param {String} originalCurrencyAmount
      * @param bankOrderCode
@@ -542,19 +490,9 @@ declare class ServerSideUtils {
      * @return {Promise<string>} the valid base64 image
      */
     static isValidImage(base64Image: string): boolean;
-    /**
-     * Verify Topipay's signature on API V3 webhooks.
-     * @param {string} originalCurrencyAmount
-     * @param {string} bankOrderCode
-     * @param {string} signature signaturev3 field to be verified
-     * @returns {boolean}
-     */
-    static verifySignatureV3(credentials: {
-        clientId: string;
-        clientSecret: string;
-    } | Tropipay, originalCurrencyAmount: string, bankOrderCode: string, signature: string): boolean;
 }
 
 declare const SERVER_MODE: ServerMode$1;
 
-export { AccountBalance, AccountDeposits, ClientSideUtils, Country, Deposit, HookEventType, HookTargetType, LoginError, LoginResponse, MAX_IMAGE_SIZE_MB, MediationPaymentCardConfig, PaymentLink, PaymentLinkPayload, SERVER_MODE, ServerMode$1 as ServerMode, ServerSideUtils, Tropipay, TropipayConfig, TropipayCredentials, UserHook, UserHookSubscribed };
+export { ClientSideUtils, MAX_IMAGE_SIZE_MB, SERVER_MODE, ServerSideUtils, Tropipay };
+export type { AccountBalance, AccountDeposits, Country, Deposit, HookEventType, HookTargetType, LoginError, LoginResponse, MediationPaymentCardConfig, PaymentLink, PaymentLinkPayload, RefundResponse, ServerMode$1 as ServerMode, TropipayConfig, TropipayCredentials, UserHook, UserHookSubscribed };