@mbanq/core-sdk-js 0.26.0 → 0.28.0

package/README.md

@@ -44,12 +44,20 @@ npm install @mbanq/core-sdk-js
 import { createInstance, CreatePayment, GetTransfers } from '@mbanq/core-sdk-js';
 
 const client = createInstance({
-  secret: 'your-jwt-secret',
-  signee: 'YOUR-SIGNEE',
   baseUrl: 'https://api.cloud.mbanq.com',
   tenantId: 'your-tenant-id'
 });
 
+await client.connect({
+  credential: {
+    client_id: 'your-client-id',
+    client_secret: 'your-client-secret',
+    username: 'your-username',
+    password: 'your-password',
+    grant_type: 'password'
+  }
+});
+
 // Create payment
 const payment = await client.request(CreatePayment({
   amount: 100.00,
@@ -84,77 +92,35 @@ const transfers = await client.request(GetTransfers({
 
 ## Setup
 
-### Authentication Options
+### Authentication
 
-The SDK supports multiple authentication methods. Choose the one that fits your integration:
-
-#### 1. JWT Token Authentication (Recommended)
-Use your API secret and signee for JWT-based authentication:
+The SDK uses OAuth 2.0 password grant flow for authentication:
 
 ```javascript
 const client = createInstance({
-  secret: 'your-jwt-secret',
-  signee: 'YOUR-SIGNEE', 
   baseUrl: 'https://api.cloud.mbanq.com',
   tenantId: 'your-tenant-id'
 });
-```
 
-#### 2. Bearer Token Authentication
-If you already have a valid access token:
-
-```javascript
-// With "Bearer " prefix (recommended)
-const client = createInstance({
-  bearerToken: 'Bearer your-access-token',
-  baseUrl: 'https://api.cloud.mbanq.com', 
-  tenantId: 'your-tenant-id'
-});
-
-// Without "Bearer " prefix (automatically added)
-const client = createInstance({
-  bearerToken: 'your-access-token', // "Bearer " will be added automatically
-  baseUrl: 'https://api.cloud.mbanq.com', 
-  tenantId: 'your-tenant-id'
-});
-```
-
-#### 3. OAuth Credential Authentication
-For OAuth 2.0 password grant flow:
-
-```javascript
-const client = createInstance({
+await client.connect({
   credential: {
     client_id: 'your-client-id',
     client_secret: 'your-client-secret',
     username: 'your-username',
     password: 'your-password',
     grant_type: 'password'
-  },
-  baseUrl: 'https://api.cloud.mbanq.com',
-  tenantId: 'your-tenant-id'
+  }
 });
 ```
 
-#### Authentication Priority
-When multiple authentication methods are provided, the SDK uses them in this order:
-1. **`bearerToken`** - Takes highest priority if provided
-2. **`credential`** - OAuth flow is used if no bearerToken 
-3. **`secret` + `signee`** - JWT authentication used as fallback
-
 #### Additional Configuration Options
 ```javascript
 const client = createInstance({
-  // Choose one authentication method from above
-  secret: 'your-jwt-secret',
-  signee: 'YOUR-SIGNEE',
-  
   // Required configuration
   baseUrl: 'https://api.cloud.mbanq.com',
   tenantId: 'your-tenant-id',
   
   // Optional configuration
-  traceId: 'custom-trace-id', // Custom request tracing identifier
   axiosConfig: {
     timeout: 30000, // Request timeout in milliseconds (default: 29000)
     keepAlive: true, // HTTP keep-alive for connection reuse
@@ -163,6 +129,17 @@ const client = createInstance({
     }
   }
 });
+
+// Authenticate with OAuth credentials
+await client.connect({
+  credential: {
+    client_id: 'your-client-id',
+    client_secret: 'your-client-secret',
+    username: 'your-username',
+    password: 'your-password',
+    grant_type: 'password'
+  }
+});
 ```
 
 ### Security Best Practices
@@ -176,11 +153,19 @@ const client = createInstance({
 #### Environment Variables Example
 ```javascript
 const client = createInstance({
-  secret: process.env.MBANQ_API_SECRET,
-  signee: process.env.MBANQ_API_SIGNEE,
   baseUrl: process.env.MBANQ_API_URL,
   tenantId: process.env.MBANQ_TENANT_ID
 });
+
+await client.connect({
+  credential: {
+    client_id: process.env.MBANQ_CLIENT_ID,
+    client_secret: process.env.MBANQ_CLIENT_SECRET,
+    username: process.env.MBANQ_USERNAME,
+    password: process.env.MBANQ_PASSWORD,
+    grant_type: 'password'
+  }
+});
 ```
 
 #### Production Considerations
@@ -811,7 +796,7 @@ For detailed information about specific features and APIs, refer to the followin
 - **[Mbanq API Reference](https://apidocs.cloud.mbanq.com/reference)** - Official API documentation with detailed endpoint information, request/response schemas, and examples
 
 ### Quick Links
-- [Authentication Options](#authentication-options) - JWT, Bearer Token, and OAuth configuration
+- [Authentication](#authentication) - OAuth credential configuration
 - [Middleware Configuration](#middleware) - Logging, metrics, and custom middleware
 - [Error Handling Patterns](#error-handling) - Error types and handling strategies
 - [Type Definitions](#type-safety--validation) - Complete schema and type reference
@@ -846,8 +831,6 @@ The library uses a consistent error handling pattern. All API calls may throw th
 ### Error Types
 - **`CommandError`**: Base error type with `code`, `message`, `statusCode`, and optional `requestId`
 - **Authentication Errors**: Invalid or missing API credentials
-  - Invalid JWT secret/signee combination
-  - Expired or invalid bearer token
   - OAuth credential authentication failure
 - **Validation Errors**: Invalid parameters provided (uses Zod validation)
 - **API Errors**: Server-side errors with specific error codes
@@ -855,8 +838,6 @@ The library uses a consistent error handling pattern. All API calls may throw th
 
 ### Common Authentication Error Scenarios
 - **Missing credentials**: No authentication method provided
-- **Invalid JWT**: Incorrect secret or signee values
-- **Expired token**: Bearer token has expired and needs refresh
 - **OAuth failure**: Invalid username/password or client credentials
 
 ## Examples
@@ -868,12 +849,20 @@ import { createInstance, CreateTransfer, GetTransfer, MarkAsSuccess } from '@mba
 
 // Initialize the client
 const client = createInstance({ 
-  secret: 'your-secret', 
-  signee: 'YOUR-SIGNEE', 
   baseUrl: 'https://api.cloud.mbanq.com', 
   tenantId: 'your-tenant-id' 
 });
 
+await client.connect({
+  credential: {
+    client_id: 'your-client-id',
+    client_secret: 'your-client-secret',
+    username: 'your-username',
+    password: 'your-password',
+    grant_type: 'password'
+  }
+});
+
 // Create an ACH transfer
 const achTransfer = await client.request(CreateTransfer({
   amount: 1500,

package/dist/client/index.d.mts

@@ -1,4 +1,4 @@
-import { C as Config, A as AuthConfig, a as Command, R as RequestOptions } from '../config.d-BSoFrdxi.mjs';
+import { C as Config, A as AuthConfig, a as Command, R as RequestOptions } from '../config.d-BvqzFkbH.mjs';
 import 'graphql';
 import 'axios';
 

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Config, A as AuthConfig, a as Command, R as RequestOptions } from '../config.d-BSoFrdxi.js';
+import { C as Config, A as AuthConfig, a as Command, R as RequestOptions } from '../config.d-BvqzFkbH.js';
 import 'graphql';
 import 'axios';
 

package/dist/commands/index.d.mts

@@ -1,5 +1,5 @@
 import z$1, { z } from 'zod';
-import { a as Command, G as GraphQLRequest } from '../config.d-BSoFrdxi.mjs';
+import { a as Command, G as GraphQLRequest } from '../config.d-BvqzFkbH.mjs';
 import * as buffer from 'buffer';
 import { e as ProcessOutput, G as GetTransferInput, T as Transfer, b as CreateTransferInput, ai as CreateTransferOutput, P as Payment, aj as PaymentFilters, a as PaymentResponse, C as CreatePaymentInput, ak as ProcessOutput$1, U as UpdatePaymentInput, u as SavingAccount, al as ListAccountsOfClientRequest, y as UpdateAccountRequest, am as CreateAndActivateAccountRequest, an as CreateAndActivateAccountResponse, ao as CloseAccountRequest, ap as CloseAccountResponse, aq as BlockAccountRequest, ar as BlockAccountResponse, as as HoldAmountRequest, at as HoldAmountResponse, au as UpdateRecipientRequest, R as Recipient, g as CreateRecipientRequest, h as RecipientRequest, av as Recipients, B as UserDetail, aw as EnableSelfServiceAccessRequest, ax as EnableSelfServiceAccessResponse, ay as UpdateSelfServiceUserRequest, az as UpdateSelfServiceUserResponse, aA as DeleteSelfServiceUserResponse } from '../recipient-i5k7edaA.mjs';
 import 'graphql';
@@ -9040,6 +9040,70 @@ type CardSettlement = z.infer<typeof CardSettlementSchema>;
 type GetCardSettlementsRequest = z.infer<typeof GetCardSettlementsRequestSchema>;
 type GetCardSettlementsResponse = z.infer<typeof GetCardSettlementsResponseSchema>;
 type GetCardSettlementByIdRequest = z.infer<typeof GetCardSettlementByIdRequestSchema>;
+declare const AcquiredCard: z.ZodObject<{
+    id: z.ZodNumber;
+    lastDigits: z.ZodString;
+    expiryDate: z.ZodString;
+    network: z.ZodString;
+    pushEnabled: z.ZodBoolean;
+    pullEnabled: z.ZodBoolean;
+    isRegulated: z.ZodBoolean;
+    avsVerified: z.ZodBoolean;
+    pushFundAvailability: z.ZodString;
+    countryCode: z.ZodString;
+    currencyCode: z.ZodString;
+    cardType: z.ZodString;
+    fullName: z.ZodString;
+    referenceId: z.ZodString;
+    externalId: z.ZodString;
+    deleted: z.ZodBoolean;
+    status: z.ZodString;
+    financialInstitution: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    id: number;
+    externalId: string;
+    createdAt: string;
+    countryCode: string;
+    financialInstitution: string;
+    network: string;
+    cardType: string;
+    expiryDate: string;
+    lastDigits: string;
+    pushEnabled: boolean;
+    pullEnabled: boolean;
+    isRegulated: boolean;
+    avsVerified: boolean;
+    pushFundAvailability: string;
+    currencyCode: string;
+    fullName: string;
+    referenceId: string;
+    deleted: boolean;
+    updatedAt: string;
+}, {
+    status: string;
+    id: number;
+    externalId: string;
+    createdAt: string;
+    countryCode: string;
+    financialInstitution: string;
+    network: string;
+    cardType: string;
+    expiryDate: string;
+    lastDigits: string;
+    pushEnabled: boolean;
+    pullEnabled: boolean;
+    isRegulated: boolean;
+    avsVerified: boolean;
+    pushFundAvailability: string;
+    currencyCode: string;
+    fullName: string;
+    referenceId: string;
+    deleted: boolean;
+    updatedAt: string;
+}>;
 declare const AcquiredCardsList: z.ZodArray<z.ZodObject<{
     id: z.ZodNumber;
     lastDigits: z.ZodString;
@@ -9104,6 +9168,7 @@ declare const AcquiredCardsList: z.ZodArray<z.ZodObject<{
     deleted: boolean;
     updatedAt: string;
 }>, "many">;
+type AcquiredCardResponse = z.infer<typeof AcquiredCard>;
 type AcquiredCardsResponse = z.infer<typeof AcquiredCardsList>;
 
 declare const CreatePrepaidCardRequestSchema: z.ZodObject<{
@@ -11494,6 +11559,22 @@ declare const GetCardSettlements: (params: GetCardSettlementsRequest) => Command
 declare const GetCardSettlementById: (params: GetCardSettlementByIdRequest) => Command<{
     params: GetCardSettlementByIdRequest;
 }, CardSettlement>;
+/**
+ * Terminate a card
+ *
+ * Permanently terminates a card, making it unusable for any transactions.
+ * This action is irreversible and the card cannot be reactivated after termination.
+ * Use this when a card should be completely removed from service.
+ *
+ * @param cardId - The unique identifier of the card to terminate
+ * @returns Command object that executes the API request and returns termination details
+ *
+ * @example
+ * ```typescript
+ * const command = TerminateCard(67890);
+ * const result = await client.request(command);
+ * ```
+ */
 declare const TerminateCard: (cardId: number) => Command<{
     cardId: number;
     command: string;
@@ -11503,6 +11584,22 @@ declare const TerminateCard: (cardId: number) => Command<{
     clientId: number;
     cardToken: string;
 }>;
+/**
+ * Suspend a card
+ *
+ * Temporarily suspends a card, preventing it from being used for transactions.
+ * The card can be reactivated later using ReactivateCard or ActivateCard.
+ * Use this for temporary card holds or when investigating suspicious activity.
+ *
+ * @param cardId - The unique identifier of the card to suspend
+ * @returns Command object that executes the API request and returns suspension details
+ *
+ * @example
+ * ```typescript
+ * const command = SuspendCard(67890);
+ * const result = await client.request(command);
+ * ```
+ */
 declare const SuspendCard: (cardId: number) => Command<{
     cardId: number;
     command: string;
@@ -11512,6 +11609,22 @@ declare const SuspendCard: (cardId: number) => Command<{
     clientId: number;
     cardToken: string;
 }>;
+/**
+ * Activate a card
+ *
+ * Activates a card that has been issued but not yet activated.
+ * This is typically required for new cards or cards that were previously suspended.
+ * Activation enables the card for transactions according to its configured features.
+ *
+ * @param cardId - The unique identifier of the card to activate
+ * @returns Command object that executes the API request and returns activation details
+ *
+ * @example
+ * ```typescript
+ * const command = ActivateCard(67890);
+ * const result = await client.request(command);
+ * ```
+ */
 declare const ActivateCard: (cardId: number) => Command<{
     cardId: number;
     command: string;
@@ -11521,6 +11634,23 @@ declare const ActivateCard: (cardId: number) => Command<{
     clientId: number;
     cardToken: string;
 }>;
+/**
+ * Reactivate a suspended card
+ *
+ * Reactivates a card that was previously suspended. This restores the card's
+ * ability to process transactions according to its configuration.
+ * Use this to restore a suspended card back to active status.
+ *
+ * @param cardId - The unique identifier of the card to reactivate
+ * @returns Command object that executes the API request and returns reactivation details
+ *
+ * @example
+ * ```typescript
+ * const command = ReactivateCard(67890);
+ * const result = await client.request(command);
+ * console.log(`Card ${result.id} has been reactivated`);
+ * ```
+ */
 declare const ReactivateCard: (cardId: number) => Command<{
     cardId: number;
     command: string;
@@ -11530,6 +11660,24 @@ declare const ReactivateCard: (cardId: number) => Command<{
     clientId: number;
     cardToken: string;
 }>;
+/**
+ * Replace a card
+ *
+ * Requests a replacement for an existing card due to loss, theft, damage, or non-receipt.
+ * This action terminates the current card and issues a new card with a new number and details.
+ * The replacement card will inherit the same configuration and features as the original card.
+ *
+ * @param cardId - The unique identifier of the card to replace
+ * @param reason - The reason for replacement (LOST, STOLEN, DAMAGED, or CARD_NOT_RECEIVED)
+ * @returns Command object that executes the API request and returns replacement card details
+ *
+ * @example
+ * ```typescript
+ * // Replace a lost card
+ * const command = ReplaceCard(67890, 'LOST');
+ * const result = await client.request(command);
+ * ```
+ */
 declare const ReplaceCard: (cardId: number, reason: "LOST" | "STOLEN" | "DAMAGED" | "CARD_NOT_RECEIVED") => Command<{
     cardId: number;
     reason: string;
@@ -11538,6 +11686,25 @@ declare const ReplaceCard: (cardId: number, reason: "LOST" | "STOLEN" | "DAMAGED
     resourceId: number;
     clientId: number;
 }>;
+/**
+ * Renew a card
+ *
+ * Renews an expiring card by issuing a new card with the same product type.
+ * This is typically used when a card is approaching its expiration date and needs
+ * to be renewed with a new expiration date. The new card will maintain the same
+ * product configuration and features as the original card.
+ *
+ * @param cardId - The unique identifier of the card to renew
+ * @param productId - The product ID for the renewed card (can be the same or different from original)
+ * @returns Command object that executes the API request and returns renewed card details
+ *
+ * @example
+ * ```typescript
+ * // Renew a card with the same product
+ * const command = RenewCard(67890, 12345);
+ * const result = await client.request(command);
+ * ```
+ */
 declare const RenewCard: (cardId: number, productId: number) => Command<{
     cardId: number;
     productId: number;
@@ -11546,9 +11713,75 @@ declare const RenewCard: (cardId: number, productId: number) => Command<{
     resourceId: number;
     clientId: number;
 }>;
+/**
+ * Get all acquired cards for a client
+ *
+ * Retrieves a list of all acquired/external cards associated with a specific client ID.
+ * Acquired cards are cards that were obtained from external sources or integrated systems.
+ * Returns comprehensive card details including status, type, network, and configuration.
+ *
+ * @param clientId - The unique identifier of the client
+ * @returns Command object that executes the API request and returns list of acquired cards
+ *
+ * @example
+ * ```typescript
+ * const command = GetAcquiredCards(12345);
+ * const acquiredCards = await client.request(command);
+ * ```
+ */
 declare const GetAcquiredCards: (clientId: number) => Command<{
     clientId: number;
 }, AcquiredCardsResponse>;
+/**
+ * Get acquired card by ID
+ *
+ * Retrieves detailed information for a specific acquired/external card using its unique identifier.
+ * This endpoint allows you to fetch specific information related to an acquired card based on the
+ * card ID, including all card details such as network, type, status, and configuration settings.
+ *
+ * @param clientId - The unique identifier of the client who owns the acquired card
+ * @param acquiredCardId - The unique identifier of the acquired card to retrieve
+ * @returns Command object that executes the API request and returns acquired card details
+ *
+ * @example
+ * ```typescript
+ * const command = getAcquiredCardById(12345, 67890);
+ * const acquiredCard = await client.request(command);
+ * ```
+ */
+declare const getAcquiredCardById: (clientId: number, acquiredCardId: number) => Command<{
+    clientId: number;
+    acquiredCardId: number;
+}, AcquiredCardResponse>;
+/**
+ * Adds an acquired card to a client
+ *
+ * Adds an acquired card to a client by storing the card information in the client's
+ * external cards list. This endpoint allows you to add a card that was obtained from an
+ * external source or integrated system to a client's list of acquired cards.
+ *
+ * @param clientId - The unique identifier of the client
+ * @param params - Object containing the card data to add
+ * @returns Command object that executes the API request and returns the added acquired card details
+ * ```typescript
+ * const command = AddAcquiredCard(12345, {
+ *   cardData: 'cardData'
+ * });
+ * ```
+ */
+declare const AddAcquiredCard: (clientId: number, params: {
+    cardData: string;
+}) => Command<{
+    clientId: number;
+    params: {
+        cardData: string;
+    };
+}, {
+    id: number;
+    officeId: number;
+    clientId: number;
+    resourceId: number;
+}>;
 
 /**
  * Create Prepaid Card
@@ -17031,4 +17264,4 @@ declare const DeleteFixedDepositAccount: (accountId: number) => Command<{
     accountId: number;
 }, DeleteFixedDepositAccountResponse>;
 
-export { ActivateCard, ActivatePhysicalCard, AddCardToMobileWallet, ApproveRejectClientDocument, BlockAccount, ChangeCardType, CloseAccount, CreateAccountProduct, CreateAndActivateAccount, CreateCard, CreateCardProduct, CreateClient, CreateClientAddress, CreateClientIdentifier, CreateFixedDepositAccount, CreatePayment, CreatePrepaidCard, CreateRecipient, CreateTransfer, CustomCreate, CustomGet, CustomUpdate, DeactivatePrepaidCard, DeleteAccount, DeleteClient, DeleteClientDocument, DeleteFixedDepositAccount, DeletePayment, DeleteRecipient, DeleteSelfServiceUser, DownloadAccountStatement, EnableDisableConfiguration, EnableSelfServiceAccess, GenerateAccountStatement, GetAccount, GetAccountDocumentsDetails, GetAccountProductById, GetAccountsOfClient, GetAcquiredCards, GetAllAccountProducts, GetBankDetailsFromRoutingCode, GetCardAuthorizationById, GetCardAuthorizations, GetCardById, GetCardImageUrl, GetCardProduct, GetCardSettlementById, GetCardSettlements, GetCards, GetClient, GetClientAddress, GetClientClassification, GetClients, GetCompletedTransactions, GetConfigurationByName, GetConfigurations, GetFixedDepositAccount, GetPayment, GetPayments, GetPendingTransactions, GetPermittedDocumentTypes, GetPrepaidCardById, GetPrepaidCardsByAccountId, GetRecentTransactions, GetRecipient, GetRecipients, GetStatusOfVerifyClient, GetTransactionById, GetTransfer, GetTransfers, GetUserDetail, GraphQL, HoldAmount, ListCardProduct, ListClientDocument, OrderPhysicalCard, ReactivateCard, RenewCard, ReplaceCard, ScheduleAccountClosure, SetClientAddressStatus, SetPIN, SuspendCard, SwitchClientClassification, TerminateCard, UpdateAccount, UpdateAccountProduct, UpdateCardFeature, UpdateCardLimit, UpdateCardProduct, UpdateClient, UpdateClientAddress, UpdateClientIdentifier, UpdateFixedDepositAccount, UpdatePayment, UpdateRecipientGQL as UpdateRecipient, UpdateSelfServiceUser, UploadClientIdentifierDocument, VerifyWithActivateClients };
+export { ActivateCard, ActivatePhysicalCard, AddAcquiredCard, AddCardToMobileWallet, ApproveRejectClientDocument, BlockAccount, ChangeCardType, CloseAccount, CreateAccountProduct, CreateAndActivateAccount, CreateCard, CreateCardProduct, CreateClient, CreateClientAddress, CreateClientIdentifier, CreateFixedDepositAccount, CreatePayment, CreatePrepaidCard, CreateRecipient, CreateTransfer, CustomCreate, CustomGet, CustomUpdate, DeactivatePrepaidCard, DeleteAccount, DeleteClient, DeleteClientDocument, DeleteFixedDepositAccount, DeletePayment, DeleteRecipient, DeleteSelfServiceUser, DownloadAccountStatement, EnableDisableConfiguration, EnableSelfServiceAccess, GenerateAccountStatement, GetAccount, GetAccountDocumentsDetails, GetAccountProductById, GetAccountsOfClient, GetAcquiredCards, GetAllAccountProducts, GetBankDetailsFromRoutingCode, GetCardAuthorizationById, GetCardAuthorizations, GetCardById, GetCardImageUrl, GetCardProduct, GetCardSettlementById, GetCardSettlements, GetCards, GetClient, GetClientAddress, GetClientClassification, GetClients, GetCompletedTransactions, GetConfigurationByName, GetConfigurations, GetFixedDepositAccount, GetPayment, GetPayments, GetPendingTransactions, GetPermittedDocumentTypes, GetPrepaidCardById, GetPrepaidCardsByAccountId, GetRecentTransactions, GetRecipient, GetRecipients, GetStatusOfVerifyClient, GetTransactionById, GetTransfer, GetTransfers, GetUserDetail, GraphQL, HoldAmount, ListCardProduct, ListClientDocument, OrderPhysicalCard, ReactivateCard, RenewCard, ReplaceCard, ScheduleAccountClosure, SetClientAddressStatus, SetPIN, SuspendCard, SwitchClientClassification, TerminateCard, UpdateAccount, UpdateAccountProduct, UpdateCardFeature, UpdateCardLimit, UpdateCardProduct, UpdateClient, UpdateClientAddress, UpdateClientIdentifier, UpdateFixedDepositAccount, UpdatePayment, UpdateRecipientGQL as UpdateRecipient, UpdateSelfServiceUser, UploadClientIdentifierDocument, VerifyWithActivateClients, getAcquiredCardById };