@crediblemark/buayar 0.6.2 → 0.7.0

package/README.md

@@ -61,12 +61,15 @@
 
 #### Universal (Recommended)
 ```env
-# Active provider: any of the 19 supported names
-PROVIDER_PG=midtrans
+# (optional) Active provider: any of the 19 supported names
+# If empty, the provider is AUTO-DETECTED from filled credentials.
+BUAYAR_PROVIDER=midtrans
 
-# Universal credentials (auto-mapped per provider)
+# Universal credentials (auto-mapped per provider — same set for ALL providers)
 BUAYAR_API_KEY=your-server-key-or-secret
 BUAYAR_MERCHANT_CODE=your-merchant-id-or-username
+BUAYAR_CLIENT_KEY=your-client-or-public-key
+BUAYAR_MERCHANT_ID=your-merchant-id
 BUAYAR_SANDBOX=true
 
 # Callback & Return URLs
@@ -74,6 +77,22 @@ BUAYAR_CALLBACK_URL=https://myapp.com/api/payment/webhook
 BUAYAR_RETURN_URL=https://myapp.com/payment/finish
 ```
 
+#### Build-time introspection (portability helpers)
+
+Check what a provider actually supports — no docs digging:
+
+```ts
+import { buayar } from "@crediblemark/buayar";
+
+buayar.listProviders();                    // all 19 registered providers
+buayar.detectProviderFromEnv(process.env); // guess active provider from .env
+buayar.detectProviderFromPayload(payload); // guess provider from webhook payload
+buayar.getCapabilities("duitku");
+// { methods: [...], operations: { refund: false, checkBalance: true, disburse: true } }
+buayar.supports("xendit", "checkBalance"); // true
+buayar.supportsMethod("qris", "stripe");   // true
+```
+
 #### Provider-Specific Variables
 
 | Variable | Provider | Description |
@@ -174,9 +193,10 @@ app.post("/api/payment/webhook", async (req, res) => {
 #### 5. Zero-Code PG Switch
 ```env
 # Switch from Midtrans to Stripe — zero code change required
-PROVIDER_PG=stripe
-STRIPE_SECRET_KEY=sk_live_...
-STRIPE_WEBHOOK_SECRET=whsec_...
+BUAYAR_PROVIDER=stripe
+BUAYAR_API_KEY=sk_live_...
+BUAYAR_WEBHOOK_SECRET=whsec_...
+# (or omit BUAYAR_PROVIDER entirely — provider auto-detected from the credentials)
 ```
 
 ---
@@ -230,12 +250,15 @@ STRIPE_WEBHOOK_SECRET=whsec_...
 
 #### Universal (Direkomendasikan)
 ```env
-# Provider aktif (19 pilihan tersedia)
-PROVIDER_PG=midtrans
+# (opsional) Provider aktif (19 pilihan). Bila kosong, AUTO-DIDETEKSI
+# dari kredensial yang terisi. Set var ini sama untuk semua provider.
+BUAYAR_PROVIDER=midtrans
 
 # Kredensial Universal (dipetakan otomatis per provider)
 BUAYAR_API_KEY=server-key-atau-secret
 BUAYAR_MERCHANT_CODE=merchant-id-atau-username
+BUAYAR_CLIENT_KEY=client-atau-public-key
+BUAYAR_MERCHANT_ID=merchant-id
 BUAYAR_SANDBOX=true
 
 # Callback & Return URL
@@ -336,9 +359,10 @@ app.post("/api/payment/webhook", async (req, res) => {
 #### 5. Zero-Code PG Switch
 ```env
 # Ganti dari Midtrans ke Stripe — tanpa ubah satu baris kode pun
-PROVIDER_PG=stripe
-STRIPE_SECRET_KEY=sk_live_...
-STRIPE_WEBHOOK_SECRET=whsec_...
+BUAYAR_PROVIDER=stripe
+BUAYAR_API_KEY=sk_live_...
+BUAYAR_WEBHOOK_SECRET=whsec_...
+# (atau hapus BUAYAR_PROVIDER — provider auto-dideteksi dari kredensial)
 ```
 
 ### 🏷️ Daftar Canonical Payment Methods

package/dist/cli/index.js

@@ -30,21 +30,30 @@ var p2 = __toESM(require("@clack/prompts"));
 
 // src/cli/templates.ts
 var DOT_ENV_TEMPLATE = `# \u2500\u2500 @crediblemark/buayar \xB7 Konfigurasi \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-# Provider aktif (salah satu dari 19): midtrans, duitku, ipaymu, xendit, doku,
-# prismalink, faspay, finpay, nicepay, oy, stripe, paypal, adyen, checkoutcom,
-# razorpay, square, payu, braintree, twocheckout
-PROVIDER_PG=midtrans
-
-# Kredensial Universal (dipetakan otomatis per provider)
-BUAYAR_API_KEY=your-server-key-atau-secret
+# CUKUP isi blok universal di bawah. Provider aktif bisa DITENTUKAN sendiri
+# (BUAYAR_PROVIDER) atau DI-AUTODETECT dari kunci kredensial yang terisi.
+# Saat pindah provider, umumnya kode TIDAK berubah \u2014 cukup isi key-nya.
+
+# (opsional) Nama provider aktif. Bila dikosongkan, otomatis dideteksi.
+# midtrans | duitku | ipaymu | xendit | doku | prismalink | faspay | finpay
+# nicepay | oy | stripe | paypal | adyen | checkoutcom | razorpay | square
+# payu | braintree | twocheckout
+# BUAYAR_PROVIDER=midtrans
+
+# Kredensial Universal \u2014 dipetakan otomatis sesuai provider aktif.
+# Isi sesuai kredensial yang diminta provider itu (umumnya: secret/key/password).
+BUAYAR_API_KEY=server-key-atau-secret
 BUAYAR_MERCHANT_CODE=merchant-id-atau-username
+BUAYAR_CLIENT_KEY=client-atau-public-key
+BUAYAR_MERCHANT_ID=merchant-id
 BUAYAR_SANDBOX=true
 
 # Callback & Return URL
 BUAYAR_CALLBACK_URL=http://localhost:3000/api/payment/webhook
 BUAYAR_RETURN_URL=http://localhost:3000/payment/success
 
-# \u2500\u2500 Kredensial Spesifik Provider (isi sesuai yang aktif saja) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# \u2500\u2500 Kredensial Spesifik Provider (opsional & lanjutan) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Bisa diisi bila ingin eksplisit; bila kosong, nilai universal di atas dipakai.
 # MIDTRANS_SERVER_KEY=
 # MIDTRANS_CLIENT_KEY=
 # DUITKU_API_KEY=
@@ -76,6 +85,7 @@ BUAYAR_RETURN_URL=http://localhost:3000/payment/success
 # ADYEN_MERCHANT_ACCOUNT=
 # ADYEN_HMAC_KEY=
 # CHECKOUTCOM_SECRET_KEY=
+# CHECKOUTCOM_PUBLIC_KEY=
 # CHECKOUTCOM_WEBHOOK_SECRET=
 # RAZORPAY_KEY_ID=
 # RAZORPAY_KEY_SECRET=
@@ -290,7 +300,7 @@ var README_PAYMENT_TEMPLATE = (framework, provider) => `# \u{1F4B3} Payment \u20
 
 Scaffold dibuat otomatis oleh \`buayar init\`.
 
-- **Provider aktif:** \`${provider}\` (ganti di \`.env\` \u2192 \`PROVIDER_PG\`)
+- **Provider aktif:** \`${provider}\` (ganti di \`.env\` \u2192 \`BUAYAR_PROVIDER\`)
 - **Framework route:** \`${framework}\`
 
 ## Struktur
@@ -308,7 +318,7 @@ src/payment/
 4. Notifikasi masuk ke \`POST /api/payment/webhook\` \u2192 diverifikasi otomatis.
 
 ## Ganti Provider
-Ubah \`PROVIDER_PG\` + kredensial di \`.env\`. Kode \`service.ts\`/route **tidak berubah**.
+Ubah \`BUAYAR_PROVIDER\` + kredensial di \`.env\`. Kode \`service.ts\`/route **tidak berubah**.
 
 > Dokumentasi lengkap: https://github.com/crediblemark-official/Buayar#readme
 `;
@@ -474,7 +484,7 @@ function printScaffoldSummary(result) {
 }
 
 // src/cli/index.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 function parseArgs(argv) {
   const flags = [];
   const rest = [];

package/dist/index.d.mts

@@ -33,7 +33,7 @@ interface MandiriBillInfo {
 }
 interface InvoiceResponse {
     success: boolean;
-    /** Provider yang memproses invoice ini ('midtrans' | 'duitku') */
+    /** Provider yang memproses invoice ini ('midtrans' | 'duitku' | 'doku' ...) */
     provider?: string;
     /** Order ID unik dari merchant */
     orderId?: string;
@@ -43,6 +43,8 @@ interface InvoiceResponse {
     paymentUrl?: string;
     /** Reference number dari Payment Gateway */
     reference?: string;
+    /** Dimensi hasil kanal spesifik (VA / QRIS / e-Wallet / Checkout) untuk typing strict. */
+    mode?: PaymentMode;
     /** Nomor Virtual Account (untuk metode Bank Transfer / VA) */
     vaNumber?: string;
     /** Nama Bank dari Virtual Account (misal: "bca", "bni", "bri", "mandiri", "permata") */
@@ -59,11 +61,32 @@ interface InvoiceResponse {
     billInfo?: MandiriBillInfo;
     /** Waktu kedaluwarsa tagihan pembayaran */
     expiresAt?: Date | string;
-    /** Raw response asli dari API provider */
+    /** Raw response asli dari API provider (termasuk saat gagal) */
     rawResponse: any;
     /** Pesan error jika gagal */
     error?: string;
 }
+/** Kanal pembayaran hasil invoice — membantu typing strict dan rendering UI. */
+type PaymentMode = "checkout" | "va" | "qris" | "ewallet" | "retail" | "other";
+/** Hasil invoice khusus Virtual Account (mode === 'va'). */
+interface VirtualAccountResponse extends InvoiceResponse {
+    mode: "va";
+    vaNumber: string;
+    vaBank?: string;
+}
+/** Hasil invoice khusus QRIS (mode === 'qris'). */
+interface QrisResponse extends InvoiceResponse {
+    mode: "qris";
+    qrString: string;
+    qrCodeUrl?: string;
+}
+/** Hasil invoice khusus e-Wallet (mode === 'ewallet'). */
+interface EWalletResponse extends InvoiceResponse {
+    mode: "ewallet";
+    checkoutUrl?: string;
+    paymentUrl?: string;
+    deeplink?: string;
+}
 interface VerifyCallbackResult {
     isValid: boolean;
     provider?: string;
@@ -1026,10 +1049,52 @@ declare class PaymentManager {
 }
 declare const paymentManager: PaymentManager;
 
+interface ProviderCapability {
+    /** Metode pembayaran kanonik yang didukung provider ini */
+    methods: string[];
+    /** Operasi lanjutan yang didukung */
+    operations: {
+        refund: boolean;
+        checkBalance: boolean;
+        disburse: boolean;
+    };
+}
+interface ProviderDescriptor extends ProviderCapability {
+    name: string;
+    /** Kunci env kredensial yang menandakan provider ini aktif (untuk autodetect) */
+    envKeys: string[];
+}
 /**
- * Resolver konfigurasi kredensial otomatis dari Environment Variables.
- * Mendukung variabel universal Buayar / PG serta variabel spesifik masing-masing provider.
- */
+ * Pendeteksi / registrar provider dinamis.
+ * Metadata provider terpusat di sini sehingga:
+ *  - Daftar provider bisa ditambah tanpa ubah core (register(...)).
+ *  - Provider aktif bisa di-autodetect dari kredensial .env.
+ *  - Provider pengirim webhook bisa ditebak dari struktur payload.
+ *  - Capability (metode + operasi) bisa di-query secara runtime.
+ */
+declare class ProviderRegistry {
+    private descriptors;
+    constructor(initial?: ProviderDescriptor[]);
+    register(desc: ProviderDescriptor): void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    get(name: string): ProviderDescriptor | undefined;
+    names(): string[];
+    /**
+     * Autodetect provider aktif dari variabel lingkungan.
+     * Mengembalikan nama provider yang kredensial .env-nya terisi penuh,
+     * atau undefined jika tidak ada / ambigu.
+     */
+    detectFromEnv(env: Record<string, string | undefined>): string | undefined;
+    /**
+     * Autodetect provider dari struktur payload webhook.
+     * Mengembalikan nama provider jika dikenali, else undefined.
+     */
+    detectFromWebhook(payload: any): string | undefined;
+}
+declare function buildDefaultDescriptors(): ProviderDescriptor[];
+declare const providerRegistry: ProviderRegistry;
+
 declare function resolveConfigFromEnv(customConfig?: BuayarConfig): BuayarConfig;
 
 /**
@@ -1045,7 +1110,8 @@ declare function resolveConfigFromEnv(customConfig?: BuayarConfig): BuayarConfig
 declare class Buayar {
     private manager;
     private config;
-    constructor(config?: BuayarConfig, manager?: PaymentManager);
+    private registry;
+    constructor(config?: BuayarConfig, manager?: PaymentManager, registry?: ProviderRegistry);
     /**
      * Dapatkan salinan konfigurasi aktif saat ini
      */
@@ -1066,6 +1132,40 @@ declare class Buayar {
      * Ambil instance provider kelas dasar
      */
     getProvider(name?: string): BasePaymentProvider;
+    /**
+     * Daftar nama provider yang terdaftar (bawaan + kustom).
+     */
+    listProviders(): string[];
+    /**
+     * Registrasi metadata provider kustom untuk deteksi & capability.
+     * Contoh: buayar.registerProviderDescriptor({ name, envKeys, methods, operations })
+     */
+    registerProviderDescriptor(desc: ProviderDescriptor): void;
+    /**
+     * Cek capability (metode + operasi) provider tertentu — atau provider aktif bila kosong.
+     * Jawab pertanyaan "provider ini dukung apa?" secara runtime, tanpa bongkar dokumen.
+     */
+    getCapabilities(name?: string): ProviderCapability | undefined;
+    /**
+     * Deteksi nama provider dari struktur payload webhook.
+     */
+    detectProviderFromPayload(payload: any): string | undefined;
+    /**
+     * Deteksi nama provider aktif dari variabel lingkungan (kredensial yang terisi).
+     */
+    detectProviderFromEnv(env?: Record<string, string | undefined>): string | undefined;
+    /**
+     * Logika "bisa pakai X dengan provider Y?" — helper untuk portabilitas.
+     */
+    supports(name: string, operation: "refund" | "checkBalance" | "disburse"): boolean;
+    /**
+     * Daftar metode pembayaran yang benar2 tersedia untuk provider aktif.
+     */
+    getSupportedMethods(name?: string): string[];
+    /**
+     * Iterasi CEPAT: apakah provider aktif mendukung method kanonik tertentu?
+     */
+    supportsMethod(method: string, name?: string): boolean;
     /**
      * Buat transaksi pembayaran baru (Mendukung Semi dan Full Integrasi)
      */
@@ -1391,6 +1491,11 @@ declare function snapExternalId(prefix?: string): string;
  * @returns true when the X-SIGNATURE matches.
  */
 declare function verifySnapWebhookSignature(headers: Record<string, string | string[] | undefined>, body: any, clientSecret: string, endpointUrl?: string): boolean;
+/**
+ * Map a DOKU SNAP error (responseMessage/responseCode) to an actionable hint
+ * for developers, so config gaps (missing BIN / merchantId / keys) are obvious.
+ */
+declare function snapErrorHint(message: string, code?: string): string | undefined;
 
 /**
  * Generate signature PrismaLink
@@ -1585,6 +1690,21 @@ declare class SnapClient {
         extraHeaders?: Record<string, string>;
     }): Promise<any>;
 }
+/** DOKU SNAP API error with structured diagnostics (status code + raw response). */
+declare class SnapApiError extends Error {
+    readonly status: number;
+    readonly responseCode?: string;
+    readonly raw: any;
+    readonly endpoint?: string;
+    readonly method?: string;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string;
+        raw?: any;
+        endpoint?: string;
+        method?: string;
+    });
+}
 
 /**
  * Generate MD5 hash string (lowercase)
@@ -1615,4 +1735,4 @@ declare function safeCompare(a: string, b: string): boolean;
  */
 declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
 
-export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SnapClient, type SnapClientOptions, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, generateSnapAsymmetricSignature, generateSnapSymmetricSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, minifyJson, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha256Hex, sha512, snapExternalId, snapTimestamp, snapUtcTimestamp, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySnapWebhookSignature, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };
+export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, type EWalletResponse, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, type PaymentMode, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderCapability, type ProviderConfig, type ProviderDescriptor, ProviderRegistry, type QrisResponse, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SnapApiError, SnapClient, type SnapClientOptions, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, type VirtualAccountResponse, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildDefaultDescriptors, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, generateSnapAsymmetricSignature, generateSnapSymmetricSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, minifyJson, parseCoreChargeResponse, paymentManager, providerRegistry, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha256Hex, sha512, snapErrorHint, snapExternalId, snapTimestamp, snapUtcTimestamp, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySnapWebhookSignature, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };

package/dist/index.d.ts

@@ -33,7 +33,7 @@ interface MandiriBillInfo {
 }
 interface InvoiceResponse {
     success: boolean;
-    /** Provider yang memproses invoice ini ('midtrans' | 'duitku') */
+    /** Provider yang memproses invoice ini ('midtrans' | 'duitku' | 'doku' ...) */
     provider?: string;
     /** Order ID unik dari merchant */
     orderId?: string;
@@ -43,6 +43,8 @@ interface InvoiceResponse {
     paymentUrl?: string;
     /** Reference number dari Payment Gateway */
     reference?: string;
+    /** Dimensi hasil kanal spesifik (VA / QRIS / e-Wallet / Checkout) untuk typing strict. */
+    mode?: PaymentMode;
     /** Nomor Virtual Account (untuk metode Bank Transfer / VA) */
     vaNumber?: string;
     /** Nama Bank dari Virtual Account (misal: "bca", "bni", "bri", "mandiri", "permata") */
@@ -59,11 +61,32 @@ interface InvoiceResponse {
     billInfo?: MandiriBillInfo;
     /** Waktu kedaluwarsa tagihan pembayaran */
     expiresAt?: Date | string;
-    /** Raw response asli dari API provider */
+    /** Raw response asli dari API provider (termasuk saat gagal) */
     rawResponse: any;
     /** Pesan error jika gagal */
     error?: string;
 }
+/** Kanal pembayaran hasil invoice — membantu typing strict dan rendering UI. */
+type PaymentMode = "checkout" | "va" | "qris" | "ewallet" | "retail" | "other";
+/** Hasil invoice khusus Virtual Account (mode === 'va'). */
+interface VirtualAccountResponse extends InvoiceResponse {
+    mode: "va";
+    vaNumber: string;
+    vaBank?: string;
+}
+/** Hasil invoice khusus QRIS (mode === 'qris'). */
+interface QrisResponse extends InvoiceResponse {
+    mode: "qris";
+    qrString: string;
+    qrCodeUrl?: string;
+}
+/** Hasil invoice khusus e-Wallet (mode === 'ewallet'). */
+interface EWalletResponse extends InvoiceResponse {
+    mode: "ewallet";
+    checkoutUrl?: string;
+    paymentUrl?: string;
+    deeplink?: string;
+}
 interface VerifyCallbackResult {
     isValid: boolean;
     provider?: string;
@@ -1026,10 +1049,52 @@ declare class PaymentManager {
 }
 declare const paymentManager: PaymentManager;
 
+interface ProviderCapability {
+    /** Metode pembayaran kanonik yang didukung provider ini */
+    methods: string[];
+    /** Operasi lanjutan yang didukung */
+    operations: {
+        refund: boolean;
+        checkBalance: boolean;
+        disburse: boolean;
+    };
+}
+interface ProviderDescriptor extends ProviderCapability {
+    name: string;
+    /** Kunci env kredensial yang menandakan provider ini aktif (untuk autodetect) */
+    envKeys: string[];
+}
 /**
- * Resolver konfigurasi kredensial otomatis dari Environment Variables.
- * Mendukung variabel universal Buayar / PG serta variabel spesifik masing-masing provider.
- */
+ * Pendeteksi / registrar provider dinamis.
+ * Metadata provider terpusat di sini sehingga:
+ *  - Daftar provider bisa ditambah tanpa ubah core (register(...)).
+ *  - Provider aktif bisa di-autodetect dari kredensial .env.
+ *  - Provider pengirim webhook bisa ditebak dari struktur payload.
+ *  - Capability (metode + operasi) bisa di-query secara runtime.
+ */
+declare class ProviderRegistry {
+    private descriptors;
+    constructor(initial?: ProviderDescriptor[]);
+    register(desc: ProviderDescriptor): void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    get(name: string): ProviderDescriptor | undefined;
+    names(): string[];
+    /**
+     * Autodetect provider aktif dari variabel lingkungan.
+     * Mengembalikan nama provider yang kredensial .env-nya terisi penuh,
+     * atau undefined jika tidak ada / ambigu.
+     */
+    detectFromEnv(env: Record<string, string | undefined>): string | undefined;
+    /**
+     * Autodetect provider dari struktur payload webhook.
+     * Mengembalikan nama provider jika dikenali, else undefined.
+     */
+    detectFromWebhook(payload: any): string | undefined;
+}
+declare function buildDefaultDescriptors(): ProviderDescriptor[];
+declare const providerRegistry: ProviderRegistry;
+
 declare function resolveConfigFromEnv(customConfig?: BuayarConfig): BuayarConfig;
 
 /**
@@ -1045,7 +1110,8 @@ declare function resolveConfigFromEnv(customConfig?: BuayarConfig): BuayarConfig
 declare class Buayar {
     private manager;
     private config;
-    constructor(config?: BuayarConfig, manager?: PaymentManager);
+    private registry;
+    constructor(config?: BuayarConfig, manager?: PaymentManager, registry?: ProviderRegistry);
     /**
      * Dapatkan salinan konfigurasi aktif saat ini
      */
@@ -1066,6 +1132,40 @@ declare class Buayar {
      * Ambil instance provider kelas dasar
      */
     getProvider(name?: string): BasePaymentProvider;
+    /**
+     * Daftar nama provider yang terdaftar (bawaan + kustom).
+     */
+    listProviders(): string[];
+    /**
+     * Registrasi metadata provider kustom untuk deteksi & capability.
+     * Contoh: buayar.registerProviderDescriptor({ name, envKeys, methods, operations })
+     */
+    registerProviderDescriptor(desc: ProviderDescriptor): void;
+    /**
+     * Cek capability (metode + operasi) provider tertentu — atau provider aktif bila kosong.
+     * Jawab pertanyaan "provider ini dukung apa?" secara runtime, tanpa bongkar dokumen.
+     */
+    getCapabilities(name?: string): ProviderCapability | undefined;
+    /**
+     * Deteksi nama provider dari struktur payload webhook.
+     */
+    detectProviderFromPayload(payload: any): string | undefined;
+    /**
+     * Deteksi nama provider aktif dari variabel lingkungan (kredensial yang terisi).
+     */
+    detectProviderFromEnv(env?: Record<string, string | undefined>): string | undefined;
+    /**
+     * Logika "bisa pakai X dengan provider Y?" — helper untuk portabilitas.
+     */
+    supports(name: string, operation: "refund" | "checkBalance" | "disburse"): boolean;
+    /**
+     * Daftar metode pembayaran yang benar2 tersedia untuk provider aktif.
+     */
+    getSupportedMethods(name?: string): string[];
+    /**
+     * Iterasi CEPAT: apakah provider aktif mendukung method kanonik tertentu?
+     */
+    supportsMethod(method: string, name?: string): boolean;
     /**
      * Buat transaksi pembayaran baru (Mendukung Semi dan Full Integrasi)
      */
@@ -1391,6 +1491,11 @@ declare function snapExternalId(prefix?: string): string;
  * @returns true when the X-SIGNATURE matches.
  */
 declare function verifySnapWebhookSignature(headers: Record<string, string | string[] | undefined>, body: any, clientSecret: string, endpointUrl?: string): boolean;
+/**
+ * Map a DOKU SNAP error (responseMessage/responseCode) to an actionable hint
+ * for developers, so config gaps (missing BIN / merchantId / keys) are obvious.
+ */
+declare function snapErrorHint(message: string, code?: string): string | undefined;
 
 /**
  * Generate signature PrismaLink
@@ -1585,6 +1690,21 @@ declare class SnapClient {
         extraHeaders?: Record<string, string>;
     }): Promise<any>;
 }
+/** DOKU SNAP API error with structured diagnostics (status code + raw response). */
+declare class SnapApiError extends Error {
+    readonly status: number;
+    readonly responseCode?: string;
+    readonly raw: any;
+    readonly endpoint?: string;
+    readonly method?: string;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string;
+        raw?: any;
+        endpoint?: string;
+        method?: string;
+    });
+}
 
 /**
  * Generate MD5 hash string (lowercase)
@@ -1615,4 +1735,4 @@ declare function safeCompare(a: string, b: string): boolean;
  */
 declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
 
-export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderConfig, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SnapClient, type SnapClientOptions, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, generateSnapAsymmetricSignature, generateSnapSymmetricSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, minifyJson, parseCoreChargeResponse, paymentManager, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha256Hex, sha512, snapExternalId, snapTimestamp, snapUtcTimestamp, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySnapWebhookSignature, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };
+export { AdyenClient, AdyenProvider, BasePaymentProvider, BraintreeClient, BraintreeProvider, Buayar, type BuayarConfig, CANONICAL_TO_DOKU, CANONICAL_TO_DUITKU, CANONICAL_TO_FASPAY, CANONICAL_TO_FINPAY, CANONICAL_TO_IPAYMU, CANONICAL_TO_MIDTRANS, CANONICAL_TO_NICEPAY, CANONICAL_TO_OY, CANONICAL_TO_PRISMALINK, CANONICAL_TO_STRIPE, CANONICAL_TO_XENDIT, CORE_API_METHODS, type CanonicalPaymentMethod, type CheckBalanceResult, type CheckTransactionParams, type CheckTransactionResult, CheckoutComClient, CheckoutComProvider, type CreateInvoiceParams, type CustomerDetails, DUITKU_TO_CANONICAL, type DisburseParams, type DisburseResult, DokuClient, DokuProvider, DuitkuClient, type DuitkuDisbursementParams, DuitkuProvider, type EWalletResponse, FaspayClient, FaspayProvider, FinpayClient, FinpayProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, IpaymuClient, IpaymuProvider, MIDTRANS_PROBE_PAYLOADS, MIDTRANS_STATIC_METHODS, type MandiriBillInfo, MidtransClient, MidtransProvider, NicepayClient, NicepayProvider, OyClient, OyProvider, PaymentManager, type PaymentMethod, type PaymentMethodItem, type PaymentMode, PaypalClient, PaypalProvider, PayuClient, PayuProvider, PrismalinkClient, PrismalinkProvider, type ProviderCapability, type ProviderConfig, type ProviderDescriptor, ProviderRegistry, type QrisResponse, RazorpayClient, RazorpayProvider, type RefundParams, type RefundResult, SnapApiError, SnapClient, type SnapClientOptions, SquareClient, SquareProvider, StripeClient, StripeProvider, TwoCheckoutClient, TwoCheckoutProvider, type VerifyCallbackResult, type VirtualAccountResponse, XenditClient, type XenditDisbursementParams, XenditProvider, buayar, buildBraintreeBasicAuth, buildCoreChargePayload, buildDefaultDescriptors, buildPaypalBasicAuth, buildPayuBasicAuth, buildRazorpayBasicAuth, buildTwoCheckoutAuth, formatNicepayTimestamp, generateDokuHeaders, generateFaspaySignature, generateFinpaySignature, generateIpaymuSignature, generateNicepayToken, generateOyHeaders, generatePrismalinkSignature, generateSnapAsymmetricSignature, generateSnapSymmetricSignature, getDuitkuInquirySignatures, getDuitkuPaymentMethodsSignature, getDuitkuStatusSignatures, getPaymentMethodCategory, getXenditAuthHeader, hmacSha256, md5, minifyJson, parseCoreChargeResponse, paymentManager, providerRegistry, resolveConfigFromEnv, safeCompare, serializePaypalParams, serializeStripeParams, sha256, sha256Hex, sha512, snapErrorHint, snapExternalId, snapTimestamp, snapUtcTimestamp, toCanonicalPaymentMethod, toDokuPaymentMethod, toDuitkuPaymentMethod, toFaspayPaymentMethod, toFinpayPaymentMethod, toIpaymuPaymentMethod, toNicepayPaymentMethod, toOyPaymentMethod, toPrismalinkPaymentMethod, toStripePaymentMethod, toXenditPaymentMethod, verifyAdyenWebhook, verifyBraintreeWebhook, verifyCheckoutComWebhook, verifyDokuWebhookSignature, verifyDuitkuCallbackSignature, verifyFaspaySignature, verifyFinpaySignature, verifyIpaymuCallback, verifyNicepayWebhook, verifyOyWebhook, verifyPaypalWebhookSimple, verifyPayuWebhook, verifyPrismalinkSignature, verifyRazorpayWebhook, verifySnapWebhookSignature, verifySquareWebhook, verifyStripeWebhook, verifyTwoCheckoutWebhook, verifyXenditWebhookToken };