@keytd/manat 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,351 @@
+type Currency = 'AZN' | 'USD' | 'EUR' | 'RUB' | 'TRY' | 'GBP';
+/** Integer amount in minor units: 2550 = 25.50 AZN. */
+interface Money {
+    amount: number;
+    currency: Currency;
+}
+type PaymentStatus = 'pending' | 'authorized' | 'paid' | 'failed' | 'cancelled' | 'refunded' | 'partially_refunded';
+type Language = 'az' | 'en' | 'ru';
+interface CreatePaymentRequest {
+    orderId: string;
+    amount: Money;
+    returnUrl: string;
+    callbackUrl?: string;
+    description?: string;
+    language?: Language;
+    intent?: 'purchase' | 'authorize';
+    customer?: {
+        email?: string;
+        phone?: string;
+    };
+    metadata?: Record<string, string>;
+}
+type NextAction = {
+    type: 'redirect';
+    url: string;
+} | {
+    type: 'form';
+    url: string;
+    method: 'POST';
+    fields: Record<string, string>;
+} | {
+    type: 'none';
+};
+interface CreatePaymentResult {
+    paymentId: string;
+    status: PaymentStatus;
+    next: NextAction;
+    raw: unknown;
+}
+interface IncomingCallback {
+    method: string;
+    query?: Record<string, string | string[] | undefined>;
+    body?: Record<string, unknown> | string;
+    headers?: Record<string, string | string[] | undefined>;
+}
+interface PaymentEvent {
+    paymentId: string;
+    orderId?: string;
+    status: PaymentStatus;
+    amount?: Money;
+    /**
+     * Opaque provider data needed for later operations (e.g. Azericard's RRN and INT_REF).
+     * Store it with the order and pass it back to refund/capture/cancel unchanged.
+     */
+    providerRef?: string;
+    raw: unknown;
+}
+interface PaymentState {
+    paymentId: string;
+    status: PaymentStatus;
+    amount?: Money;
+    refundedAmount?: Money;
+    providerRef?: string;
+    raw: unknown;
+}
+/** Input for capture/cancel. */
+interface PaymentAction {
+    paymentId: string;
+    /** From PaymentEvent.providerRef, for providers that need it. */
+    providerRef?: string;
+    amount?: Money;
+}
+interface RefundRequest {
+    paymentId: string;
+    /** From PaymentEvent.providerRef, for providers that need it. */
+    providerRef?: string;
+    /** Omit for a full refund. */
+    amount?: Money;
+}
+interface RefundResult {
+    paymentId: string;
+    refundId?: string;
+    status: PaymentStatus;
+    raw: unknown;
+}
+type Capability = 'createPayment' | 'verifyCallback' | 'getStatus' | 'refund' | 'capture' | 'cancel';
+/** What every provider adapter implements. Optional operations may be absent. */
+interface PaymentProvider {
+    readonly name: string;
+    readonly capabilities: ReadonlySet<Capability>;
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus?(input: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund?(request: RefundRequest): Promise<RefundResult>;
+    capture?(input: PaymentAction): Promise<PaymentState>;
+    cancel?(input: PaymentAction): Promise<PaymentState>;
+}
+
+/**
+ * Provider-neutral facade. Validates input once, then delegates to the adapter,
+ * so every provider gets the same checks and the same errors.
+ */
+declare class Manat {
+    readonly provider: PaymentProvider;
+    constructor(provider: PaymentProvider);
+    get capabilities(): ReadonlySet<Capability>;
+    supports(capability: Capability): boolean;
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus(input: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture(input: PaymentAction): Promise<PaymentState>;
+    cancel(input: PaymentAction): Promise<PaymentState>;
+    private call;
+}
+
+type ManatErrorCode = 'invalid_request' | 'invalid_signature' | 'provider_error' | 'network_error' | 'unsupported_operation';
+declare class ManatError extends Error {
+    readonly code: ManatErrorCode;
+    readonly provider: string | undefined;
+    readonly providerCode: string | undefined;
+    readonly providerMessage: string | undefined;
+    readonly raw: unknown;
+    constructor(code: ManatErrorCode, message: string, details?: {
+        provider?: string;
+        providerCode?: string;
+        providerMessage?: string;
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
+declare function isManatError(error: unknown, code?: ManatErrorCode): error is ManatError;
+
+/** 2550 AZN → "25.50" (no floats involved). */
+declare function toDecimalString(money: Money): string;
+/** "25.5" / "25.50" / 25.5 → 2550. Rejects more decimals than the currency has. */
+declare function fromDecimal(value: string | number, currency: Currency): Money;
+/** Convenience for callers: Manat.azn(25.5) → { amount: 2550, currency: 'AZN' }. */
+declare function azn(value: string | number): Money;
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface HttpOptions {
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. Default 30 000. */
+    timeoutMs?: number;
+}
+
+interface KapitalBankConfig {
+    /** API user issued by the bank, e.g. "TerminalSys/xxxx". */
+    username: string;
+    password: string;
+    environment?: 'test' | 'production';
+    /** Override the API base URL (ends with /api). */
+    baseUrl?: string;
+}
+declare class KapitalBankProvider implements PaymentProvider {
+    readonly name = "kapitalbank";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    private readonly authHeader;
+    constructor(config: KapitalBankConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture({ paymentId, amount }: PaymentAction): Promise<PaymentState>;
+    cancel({ paymentId }: PaymentAction): Promise<PaymentState>;
+    private remainingRefundable;
+    private fetchOrder;
+    private toState;
+    private exec;
+    private call;
+}
+declare function kapitalBank(config: KapitalBankConfig, options?: HttpOptions): KapitalBankProvider;
+
+type AzericardMessage = 'purchase' | 'completion' | 'reversal' | 'callback' | 'status';
+interface AzericardConfig {
+    /** TERMINAL id assigned by the bank (8 characters). */
+    terminal: string;
+    /** Merchant RSA private key (PEM, at least 2048-bit) used to sign requests. */
+    privateKey: string;
+    /** Gateway (MPI) public key (PEM) used to verify callbacks. Required for verifyCallback. */
+    gatewayPublicKey?: string;
+    /** MERCH_NAME shown to the cardholder (1–50 chars). */
+    merchantName: string;
+    /** MERCH_URL: the shop's main website. */
+    merchantUrl: string;
+    environment?: 'test' | 'production';
+    /** Override the cgi_link URL. */
+    gatewayUrl?: string;
+    /** EMAIL: where the gateway may send result notifications. */
+    email?: string;
+    /** COUNTRY: only if the shop is outside Azerbaijan. */
+    country?: string;
+    /** MERCH_GMT: only if the shop's time zone differs from the gateway's (e.g. "+4"). */
+    merchantGmt?: string;
+    /** Override MAC field orders if your terminal was configured differently. */
+    macFields?: Partial<Record<AzericardMessage, string[]>>;
+    /** Testing hooks: fixed clock and nonce. */
+    clock?: () => Date;
+    nonce?: () => string;
+}
+/** MAC field orders per message type. */
+declare const AZERICARD_MAC_FIELDS: Readonly<Record<AzericardMessage, readonly string[]>>;
+declare class AzericardProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "azericard";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly url;
+    private readonly privateKey;
+    private readonly gatewayKey;
+    private readonly macFields;
+    private readonly clock;
+    private readonly makeNonce;
+    constructor(config: AzericardConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    /** TRTYPE 90 answers for one transaction type, so the purchase (or pre-auth), completion and reversals are each queried. */
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    private relatedTransactions;
+    private queryStatus;
+    capture(input: PaymentAction): Promise<PaymentState>;
+    cancel(input: PaymentAction): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    private send;
+    private sign;
+}
+declare function azericard(config: AzericardConfig, options?: HttpOptions): AzericardProvider;
+
+interface PayriffConfig {
+    /** Application secret key from the Payriff dashboard. */
+    secretKey: string;
+    /** Override the API host (default https://api.payriff.com). */
+    baseUrl?: string;
+}
+declare class PayriffProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "payriff";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: PayriffConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture({ paymentId, amount }: PaymentAction): Promise<PaymentState>;
+    private call;
+    private callEnvelope;
+}
+declare function payriff(config: PayriffConfig, options?: HttpOptions): PayriffProvider;
+
+interface EpointConfig {
+    /** Merchant public key, e.g. "i000000001". */
+    publicKey: string;
+    /** Merchant private key from the Epoint panel; signs requests and verifies callbacks. */
+    privateKey: string;
+    /** Override the API base (default https://epoint.az/api/1). */
+    baseUrl?: string;
+}
+declare class EpointProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "epoint";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: EpointConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    private call;
+    private error;
+}
+declare function epoint(config: EpointConfig, options?: HttpOptions): EpointProvider;
+
+interface GoldenPayConfig {
+    /** Auth key from the GoldenPay merchant panel; signs every request. */
+    authKey: string;
+    /** Merchant name issued by GoldenPay. */
+    merchantName: string;
+    environment?: 'test' | 'production';
+    /** Override the API host (also used for the payment page). */
+    baseUrl?: string;
+}
+declare class GoldenPayProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "goldenpay";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: GoldenPayConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    private call;
+    private error;
+}
+declare function goldenPay(config: GoldenPayConfig, options?: HttpOptions): GoldenPayProvider;
+
+interface YigimConfig {
+    /** Merchant name issued by Yığım (`X-Merchant`). */
+    merchant: string;
+    /** API key issued by Yığım (`X-API-Key`). */
+    apiKey: string;
+    /** Biller name provided by the acquirer. */
+    biller: string;
+    /** Payment page template; default `TPL0001`. */
+    template?: string;
+    environment?: 'test' | 'production';
+    /** Override the API host. */
+    baseUrl?: string;
+}
+declare class YigimProvider implements PaymentProvider {
+    private readonly config;
+    readonly name = "yigim";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    private readonly baseUrl;
+    constructor(config: YigimConfig, options?: HttpOptions);
+    createPayment(request: CreatePaymentRequest): Promise<CreatePaymentResult>;
+    verifyCallback(callback: IncomingCallback): Promise<PaymentEvent>;
+    getStatus({ paymentId }: {
+        paymentId: string;
+    }): Promise<PaymentState>;
+    refund(request: RefundRequest): Promise<RefundResult>;
+    capture({ paymentId, amount }: PaymentAction): Promise<PaymentState>;
+    cancel({ paymentId }: PaymentAction): Promise<PaymentState>;
+    private call;
+    private error;
+}
+declare function yigim(config: YigimConfig, options?: HttpOptions): YigimProvider;
+
+export { AZERICARD_MAC_FIELDS, type AzericardConfig, type AzericardMessage, AzericardProvider, type Capability, type CreatePaymentRequest, type CreatePaymentResult, type Currency, type EpointConfig, EpointProvider, type FetchLike, type GoldenPayConfig, GoldenPayProvider, type HttpOptions, type IncomingCallback, type KapitalBankConfig, KapitalBankProvider, type Language, Manat, ManatError, type ManatErrorCode, type Money, type NextAction, type PaymentAction, type PaymentEvent, type PaymentProvider, type PaymentState, type PaymentStatus, type PayriffConfig, PayriffProvider, type RefundRequest, type RefundResult, type YigimConfig, YigimProvider, azericard, azn, epoint, fromDecimal, goldenPay, isManatError, kapitalBank, payriff, toDecimalString, yigim };