aba-payway 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,7 +1,13 @@
+type Environment = "sandbox" | "production";
 interface PayWayConfig {
-    merchantId: string;
-    apiKey: string;
-    production?: boolean;
+    readonly merchantId: string;
+    readonly apiKey: string;
+    /** Target environment. Default: `"sandbox"`. */
+    readonly environment?: Environment;
+    /** Override the base URL directly. Takes priority over `environment`. */
+    readonly baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 (30s). */
+    readonly timeout?: number;
 }
 type PaymentOption = "cards" | "abapay_khqr" | "abapay_khqr_deeplink" | "alipay" | "wechat" | "google_pay";
 type Currency = "USD" | "KHR";
@@ -70,15 +76,13 @@ interface CheckoutParams {
     view_type: string;
     payment_gate: string;
 }
-interface CheckTransactionOptions {
-    transactionId: string;
-}
 interface ListTransactionsOptions {
     fromDate?: string;
     toDate?: string;
     fromAmount?: number;
     toAmount?: number;
-    status?: string;
+    /** Single status or comma-separated: e.g. `"APPROVED"` or `"APPROVED,DECLINED"` */
+    status?: TransactionStatus | (string & {});
     page?: number;
     pagination?: number;
 }
@@ -99,24 +103,24 @@ interface CheckTransactionData {
     refund_amount: number;
     discount_amount: number;
     payment_amount: number;
-    payment_currency: string;
+    payment_currency: Currency;
     apv: string;
-    payment_status: string;
+    payment_status: TransactionStatus;
     transaction_date: string;
 }
 interface TransactionListItem {
     transaction_id: string;
     transaction_date: string;
     apv: string;
-    payment_status: string;
+    payment_status: TransactionStatus;
     payment_status_code: number;
     original_amount: number;
-    original_currency: string;
+    original_currency: Currency;
     total_amount: number;
     discount_amount: number;
     refund_amount: number;
     payment_amount: number;
-    payment_currency: string;
+    payment_currency: Currency;
     first_name: string;
     last_name: string;
     email: string;
@@ -127,61 +131,217 @@ interface TransactionListItem {
     card_source: string;
     payment_type: string;
 }
-interface ListTransactionsData {
-    data: TransactionListItem[];
-    page: string;
-    pagination: string;
-}
 interface ListTransactionsResponse {
     data: TransactionListItem[];
     page: string;
     pagination: string;
     status: PayWayResponseStatus;
 }
+interface CloseTransactionResponse {
+    status: PayWayResponseStatus;
+}
+interface TransactionOperation {
+    status: string;
+    amount: number;
+    transaction_date: string;
+    bank_ref: string;
+}
+interface TransactionDetailData {
+    transaction_id: string;
+    payment_status_code: number;
+    payment_status: TransactionStatus;
+    original_amount: number;
+    original_currency: Currency;
+    payment_amount: number;
+    payment_currency: Currency;
+    total_amount: number;
+    refund_amount: number;
+    discount_amount: number;
+    apv: string;
+    transaction_date: string;
+    first_name: string;
+    last_name: string;
+    email: string;
+    phone: string;
+    bank_ref: string;
+    payment_type: string;
+    payer_account: string;
+    bank_name: string;
+    card_source: string;
+    transaction_operations: TransactionOperation[];
+}
+type ExchangeRateCurrency = "aud" | "sgd" | "eur" | "gbp" | "myr" | "thb" | "hkd" | "cny" | "cad" | "krw" | "jpy" | "vnd";
+interface ExchangeRate {
+    sell: string;
+    buy: string;
+}
+interface ExchangeRateResponse {
+    status: PayWayResponseStatus;
+    exchange_rates: Partial<Record<ExchangeRateCurrency, ExchangeRate>>;
+}
+type QRPaymentOption = "abapay_khqr" | "wechat" | "alipay";
+interface GenerateQROptions {
+    transactionId: string;
+    amount: number;
+    currency?: Currency;
+    paymentOption: QRPaymentOption;
+    lifetime?: number;
+    qrImageTemplate: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    purchaseType?: TransactionType;
+    items?: string;
+    callbackUrl?: string;
+    returnDeeplink?: string;
+    customFields?: string;
+    returnParams?: string;
+    payout?: string;
+}
+interface GenerateQRResponse {
+    status: PayWayResponseStatus & {
+        trace_id?: string;
+    };
+    amount: number;
+    currency: Currency;
+    qrString: string;
+    qrImage: string;
+    abapay_deeplink: string;
+    app_store: string;
+    play_store: string;
+}
+interface TransactionByRefItem {
+    transaction_id: string;
+    transaction_date: string;
+    apv: string;
+    payment_status: TransactionStatus;
+    payment_status_code: number;
+    original_amount: number;
+    original_currency: Currency;
+    total_amount: number;
+    discount_amount: number;
+    refund_amount: number;
+    payment_amount: number;
+    payment_currency: Currency;
+    bank_ref: string;
+    payer_account: string;
+    bank_name: string;
+    payment_type: string;
+    merchant_ref: string;
+}
+interface GetTransactionsByRefResponse {
+    data: TransactionByRefItem[];
+    status: PayWayResponseStatus;
+}
 
+/**
+ * Main SDK client for ABA PayWay.
+ * Provides methods for creating transactions, checking status, and listing transactions.
+ */
 declare class PayWay {
     private readonly merchantId;
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * @param config - Merchant credentials and environment selection.
+     * @throws {PayWayConfigError} If `merchantId` or `apiKey` is empty.
+     */
     constructor(config: PayWayConfig);
     /**
      * Generate checkout parameters for a transaction.
      * Returns form params to be submitted from the browser via ABA's checkout JS SDK.
      */
     createTransaction(options: CreateTransactionOptions): CheckoutParams;
+    /**
+     * Check the status of a transaction.
+     * @param transactionId - The unique transaction ID to look up.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
     checkTransaction(transactionId: string): Promise<PayWayResponse<CheckTransactionData>>;
+    /**
+     * List transactions with optional filters. Max 3-day date range.
+     * @param options - Filter and pagination options.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
     listTransactions(options?: ListTransactionsOptions): Promise<ListTransactionsResponse>;
+    /**
+     * Get detailed information about a transaction, including its operation history.
+     * @param transactionId - The unique transaction ID to look up.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getTransactionDetails(transactionId: string): Promise<PayWayResponse<TransactionDetailData>>;
+    /**
+     * Close (cancel) a pending transaction.
+     * @param transactionId - The transaction ID to close.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    closeTransaction(transactionId: string): Promise<CloseTransactionResponse>;
+    /**
+     * Fetch the latest exchange rates from ABA Bank.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getExchangeRate(): Promise<ExchangeRateResponse>;
+    /**
+     * Generate a QR code for payment via ABA KHQR, WeChat Pay, or Alipay.
+     * @param options - QR generation options.
+     * @throws {PayWayConfigError} If required options are missing or invalid.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    generateQR(options: GenerateQROptions): Promise<GenerateQRResponse>;
+    /**
+     * Get transactions by merchant reference. Returns up to the last 50 transactions.
+     * @param merchantRef - Your merchant reference number.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getTransactionsByRef(merchantRef: string): Promise<GetTransactionsByRefResponse>;
     private request;
 }
 
-declare const SANDBOX_BASE_URL = "https://checkout-sandbox.payway.com.kh";
-declare const PRODUCTION_BASE_URL = "https://checkout.payway.com.kh";
+declare const BASE_URLS: Record<Environment, string>;
+declare const SANDBOX_BASE_URL: string;
+declare const PRODUCTION_BASE_URL: string;
 declare const ENDPOINTS: {
     readonly purchase: "/api/payment-gateway/v1/payments/purchase";
     readonly checkTransaction: "/api/payment-gateway/v1/payments/check-transaction-2";
     readonly transactionList: "/api/payment-gateway/v1/payments/transaction-list-2";
+    readonly transactionDetail: "/api/payment-gateway/v1/payments/transaction-detail";
+    readonly closeTransaction: "/api/payment-gateway/v1/payments/close-transaction";
+    readonly exchangeRate: "/api/payment-gateway/v1/exchange-rate";
+    readonly generateQR: "/api/payment-gateway/v1/payments/generate-qr";
+    readonly getTransactionsByRef: "/api/payment-gateway/v1/payments/get-transactions-by-mc-ref";
 };
 
+/** Base error class for all PayWay SDK errors. */
 declare class PayWayError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
+/** Thrown when the ABA PayWay API returns a non-2xx HTTP response. */
 declare class PayWayAPIError extends PayWayError {
     readonly statusCode: number;
     readonly responseBody: unknown;
     constructor(message: string, statusCode: number, responseBody?: unknown);
 }
+/** Thrown when the SDK is constructed with missing or invalid configuration. */
 declare class PayWayConfigError extends PayWayError {
     constructor(message: string);
 }
+/** Thrown when HMAC hash generation fails. */
 declare class PayWayHashError extends PayWayError {
     constructor(message: string);
 }
 
-declare function createHash(values: string[], apiKey: string): string;
+/** Generate an HMAC-SHA512 hash from concatenated values, returned as a base64 string. */
+declare function createHash(values: readonly string[], apiKey: string): string;
 
+/** Format a Date as `yyyyMMddHHmmss` in UTC, used for ABA's `req_time` parameter. */
 declare function formatRequestTime(date?: Date): string;
-declare function buildFormData(params: Record<string, string | undefined>): FormData;
-declare function formatAmount(amount: number, currency?: string): string;
+/** Build a FormData object from a record, skipping `undefined`, `null`, and empty string values. */
+declare function buildFormData(params: object): FormData;
+/** Format a numeric amount as a string: 2 decimal places for USD, rounded integer for KHR. */
+declare function formatAmount(amount: number, currency?: Currency): string;
+/** Base64-encode a string value using Node.js Buffer. */
 declare function toBase64(value: string): string;
 
-export { type CheckTransactionData, type CheckTransactionOptions, type CheckoutParams, type CreateTransactionOptions, type Currency, ENDPOINTS, type ItemEntry, type ListTransactionsData, type ListTransactionsOptions, type ListTransactionsResponse, PRODUCTION_BASE_URL, PayWay, PayWayAPIError, type PayWayConfig, PayWayConfigError, PayWayError, PayWayHashError, type PayWayResponse, type PayWayResponseStatus, type PaymentOption, SANDBOX_BASE_URL, type TransactionListItem, type TransactionStatus, type TransactionType, buildFormData, createHash, formatAmount, formatRequestTime, toBase64 };
+export { BASE_URLS, type CheckTransactionData, type CheckoutParams, type CloseTransactionResponse, type CreateTransactionOptions, type Currency, ENDPOINTS, type Environment, type ExchangeRate, type ExchangeRateCurrency, type ExchangeRateResponse, type GenerateQROptions, type GenerateQRResponse, type GetTransactionsByRefResponse, type ItemEntry, type ListTransactionsOptions, type ListTransactionsResponse, PRODUCTION_BASE_URL, PayWay, PayWayAPIError, type PayWayConfig, PayWayConfigError, PayWayError, PayWayHashError, type PayWayResponse, type PayWayResponseStatus, type PaymentOption, type QRPaymentOption, SANDBOX_BASE_URL, type TransactionByRefItem, type TransactionDetailData, type TransactionListItem, type TransactionOperation, type TransactionStatus, type TransactionType, buildFormData, createHash, formatAmount, formatRequestTime, toBase64 };

package/dist/index.d.ts

@@ -1,7 +1,13 @@
+type Environment = "sandbox" | "production";
 interface PayWayConfig {
-    merchantId: string;
-    apiKey: string;
-    production?: boolean;
+    readonly merchantId: string;
+    readonly apiKey: string;
+    /** Target environment. Default: `"sandbox"`. */
+    readonly environment?: Environment;
+    /** Override the base URL directly. Takes priority over `environment`. */
+    readonly baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30000 (30s). */
+    readonly timeout?: number;
 }
 type PaymentOption = "cards" | "abapay_khqr" | "abapay_khqr_deeplink" | "alipay" | "wechat" | "google_pay";
 type Currency = "USD" | "KHR";
@@ -70,15 +76,13 @@ interface CheckoutParams {
     view_type: string;
     payment_gate: string;
 }
-interface CheckTransactionOptions {
-    transactionId: string;
-}
 interface ListTransactionsOptions {
     fromDate?: string;
     toDate?: string;
     fromAmount?: number;
     toAmount?: number;
-    status?: string;
+    /** Single status or comma-separated: e.g. `"APPROVED"` or `"APPROVED,DECLINED"` */
+    status?: TransactionStatus | (string & {});
     page?: number;
     pagination?: number;
 }
@@ -99,24 +103,24 @@ interface CheckTransactionData {
     refund_amount: number;
     discount_amount: number;
     payment_amount: number;
-    payment_currency: string;
+    payment_currency: Currency;
     apv: string;
-    payment_status: string;
+    payment_status: TransactionStatus;
     transaction_date: string;
 }
 interface TransactionListItem {
     transaction_id: string;
     transaction_date: string;
     apv: string;
-    payment_status: string;
+    payment_status: TransactionStatus;
     payment_status_code: number;
     original_amount: number;
-    original_currency: string;
+    original_currency: Currency;
     total_amount: number;
     discount_amount: number;
     refund_amount: number;
     payment_amount: number;
-    payment_currency: string;
+    payment_currency: Currency;
     first_name: string;
     last_name: string;
     email: string;
@@ -127,61 +131,217 @@ interface TransactionListItem {
     card_source: string;
     payment_type: string;
 }
-interface ListTransactionsData {
-    data: TransactionListItem[];
-    page: string;
-    pagination: string;
-}
 interface ListTransactionsResponse {
     data: TransactionListItem[];
     page: string;
     pagination: string;
     status: PayWayResponseStatus;
 }
+interface CloseTransactionResponse {
+    status: PayWayResponseStatus;
+}
+interface TransactionOperation {
+    status: string;
+    amount: number;
+    transaction_date: string;
+    bank_ref: string;
+}
+interface TransactionDetailData {
+    transaction_id: string;
+    payment_status_code: number;
+    payment_status: TransactionStatus;
+    original_amount: number;
+    original_currency: Currency;
+    payment_amount: number;
+    payment_currency: Currency;
+    total_amount: number;
+    refund_amount: number;
+    discount_amount: number;
+    apv: string;
+    transaction_date: string;
+    first_name: string;
+    last_name: string;
+    email: string;
+    phone: string;
+    bank_ref: string;
+    payment_type: string;
+    payer_account: string;
+    bank_name: string;
+    card_source: string;
+    transaction_operations: TransactionOperation[];
+}
+type ExchangeRateCurrency = "aud" | "sgd" | "eur" | "gbp" | "myr" | "thb" | "hkd" | "cny" | "cad" | "krw" | "jpy" | "vnd";
+interface ExchangeRate {
+    sell: string;
+    buy: string;
+}
+interface ExchangeRateResponse {
+    status: PayWayResponseStatus;
+    exchange_rates: Partial<Record<ExchangeRateCurrency, ExchangeRate>>;
+}
+type QRPaymentOption = "abapay_khqr" | "wechat" | "alipay";
+interface GenerateQROptions {
+    transactionId: string;
+    amount: number;
+    currency?: Currency;
+    paymentOption: QRPaymentOption;
+    lifetime?: number;
+    qrImageTemplate: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    purchaseType?: TransactionType;
+    items?: string;
+    callbackUrl?: string;
+    returnDeeplink?: string;
+    customFields?: string;
+    returnParams?: string;
+    payout?: string;
+}
+interface GenerateQRResponse {
+    status: PayWayResponseStatus & {
+        trace_id?: string;
+    };
+    amount: number;
+    currency: Currency;
+    qrString: string;
+    qrImage: string;
+    abapay_deeplink: string;
+    app_store: string;
+    play_store: string;
+}
+interface TransactionByRefItem {
+    transaction_id: string;
+    transaction_date: string;
+    apv: string;
+    payment_status: TransactionStatus;
+    payment_status_code: number;
+    original_amount: number;
+    original_currency: Currency;
+    total_amount: number;
+    discount_amount: number;
+    refund_amount: number;
+    payment_amount: number;
+    payment_currency: Currency;
+    bank_ref: string;
+    payer_account: string;
+    bank_name: string;
+    payment_type: string;
+    merchant_ref: string;
+}
+interface GetTransactionsByRefResponse {
+    data: TransactionByRefItem[];
+    status: PayWayResponseStatus;
+}
 
+/**
+ * Main SDK client for ABA PayWay.
+ * Provides methods for creating transactions, checking status, and listing transactions.
+ */
 declare class PayWay {
     private readonly merchantId;
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * @param config - Merchant credentials and environment selection.
+     * @throws {PayWayConfigError} If `merchantId` or `apiKey` is empty.
+     */
     constructor(config: PayWayConfig);
     /**
      * Generate checkout parameters for a transaction.
      * Returns form params to be submitted from the browser via ABA's checkout JS SDK.
      */
     createTransaction(options: CreateTransactionOptions): CheckoutParams;
+    /**
+     * Check the status of a transaction.
+     * @param transactionId - The unique transaction ID to look up.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
     checkTransaction(transactionId: string): Promise<PayWayResponse<CheckTransactionData>>;
+    /**
+     * List transactions with optional filters. Max 3-day date range.
+     * @param options - Filter and pagination options.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
     listTransactions(options?: ListTransactionsOptions): Promise<ListTransactionsResponse>;
+    /**
+     * Get detailed information about a transaction, including its operation history.
+     * @param transactionId - The unique transaction ID to look up.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getTransactionDetails(transactionId: string): Promise<PayWayResponse<TransactionDetailData>>;
+    /**
+     * Close (cancel) a pending transaction.
+     * @param transactionId - The transaction ID to close.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    closeTransaction(transactionId: string): Promise<CloseTransactionResponse>;
+    /**
+     * Fetch the latest exchange rates from ABA Bank.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getExchangeRate(): Promise<ExchangeRateResponse>;
+    /**
+     * Generate a QR code for payment via ABA KHQR, WeChat Pay, or Alipay.
+     * @param options - QR generation options.
+     * @throws {PayWayConfigError} If required options are missing or invalid.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    generateQR(options: GenerateQROptions): Promise<GenerateQRResponse>;
+    /**
+     * Get transactions by merchant reference. Returns up to the last 50 transactions.
+     * @param merchantRef - Your merchant reference number.
+     * @throws {PayWayAPIError} If the API returns a non-2xx response.
+     */
+    getTransactionsByRef(merchantRef: string): Promise<GetTransactionsByRefResponse>;
     private request;
 }
 
-declare const SANDBOX_BASE_URL = "https://checkout-sandbox.payway.com.kh";
-declare const PRODUCTION_BASE_URL = "https://checkout.payway.com.kh";
+declare const BASE_URLS: Record<Environment, string>;
+declare const SANDBOX_BASE_URL: string;
+declare const PRODUCTION_BASE_URL: string;
 declare const ENDPOINTS: {
     readonly purchase: "/api/payment-gateway/v1/payments/purchase";
     readonly checkTransaction: "/api/payment-gateway/v1/payments/check-transaction-2";
     readonly transactionList: "/api/payment-gateway/v1/payments/transaction-list-2";
+    readonly transactionDetail: "/api/payment-gateway/v1/payments/transaction-detail";
+    readonly closeTransaction: "/api/payment-gateway/v1/payments/close-transaction";
+    readonly exchangeRate: "/api/payment-gateway/v1/exchange-rate";
+    readonly generateQR: "/api/payment-gateway/v1/payments/generate-qr";
+    readonly getTransactionsByRef: "/api/payment-gateway/v1/payments/get-transactions-by-mc-ref";
 };
 
+/** Base error class for all PayWay SDK errors. */
 declare class PayWayError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
+/** Thrown when the ABA PayWay API returns a non-2xx HTTP response. */
 declare class PayWayAPIError extends PayWayError {
     readonly statusCode: number;
     readonly responseBody: unknown;
     constructor(message: string, statusCode: number, responseBody?: unknown);
 }
+/** Thrown when the SDK is constructed with missing or invalid configuration. */
 declare class PayWayConfigError extends PayWayError {
     constructor(message: string);
 }
+/** Thrown when HMAC hash generation fails. */
 declare class PayWayHashError extends PayWayError {
     constructor(message: string);
 }
 
-declare function createHash(values: string[], apiKey: string): string;
+/** Generate an HMAC-SHA512 hash from concatenated values, returned as a base64 string. */
+declare function createHash(values: readonly string[], apiKey: string): string;
 
+/** Format a Date as `yyyyMMddHHmmss` in UTC, used for ABA's `req_time` parameter. */
 declare function formatRequestTime(date?: Date): string;
-declare function buildFormData(params: Record<string, string | undefined>): FormData;
-declare function formatAmount(amount: number, currency?: string): string;
+/** Build a FormData object from a record, skipping `undefined`, `null`, and empty string values. */
+declare function buildFormData(params: object): FormData;
+/** Format a numeric amount as a string: 2 decimal places for USD, rounded integer for KHR. */
+declare function formatAmount(amount: number, currency?: Currency): string;
+/** Base64-encode a string value using Node.js Buffer. */
 declare function toBase64(value: string): string;
 
-export { type CheckTransactionData, type CheckTransactionOptions, type CheckoutParams, type CreateTransactionOptions, type Currency, ENDPOINTS, type ItemEntry, type ListTransactionsData, type ListTransactionsOptions, type ListTransactionsResponse, PRODUCTION_BASE_URL, PayWay, PayWayAPIError, type PayWayConfig, PayWayConfigError, PayWayError, PayWayHashError, type PayWayResponse, type PayWayResponseStatus, type PaymentOption, SANDBOX_BASE_URL, type TransactionListItem, type TransactionStatus, type TransactionType, buildFormData, createHash, formatAmount, formatRequestTime, toBase64 };
+export { BASE_URLS, type CheckTransactionData, type CheckoutParams, type CloseTransactionResponse, type CreateTransactionOptions, type Currency, ENDPOINTS, type Environment, type ExchangeRate, type ExchangeRateCurrency, type ExchangeRateResponse, type GenerateQROptions, type GenerateQRResponse, type GetTransactionsByRefResponse, type ItemEntry, type ListTransactionsOptions, type ListTransactionsResponse, PRODUCTION_BASE_URL, PayWay, PayWayAPIError, type PayWayConfig, PayWayConfigError, PayWayError, PayWayHashError, type PayWayResponse, type PayWayResponseStatus, type PaymentOption, type QRPaymentOption, SANDBOX_BASE_URL, type TransactionByRefItem, type TransactionDetailData, type TransactionListItem, type TransactionOperation, type TransactionStatus, type TransactionType, buildFormData, createHash, formatAmount, formatRequestTime, toBase64 };