paykit-bd 0.1.0

package/dist/bkash/index.d.cts

@@ -0,0 +1,104 @@
+import { R as ResolvedBkashConfig } from '../client-UNDtdWhu.cjs';
+export { A as Agreement, b as AgreementHandle, c as AgreementResponse, d as BKASH_API_VERSION, e as BKASH_HOSTS, f as BKASH_MODE, g as BKASH_TRANSACTION_TYPES, h as BkashCallbackQuery, B as BkashClient, i as BkashClientOptions, j as BkashConfig, k as BkashEnvironment, l as BkashIntent, m as BkashIpnMessage, n as BkashMode, a as BkashWebhookVerifier, C as CreateAgreementInput, o as CreatePaymentRequest, p as CreatePaymentResponse, E as ExecutePaymentResponse, G as GrantTokenResponse, Q as QueryPaymentResponse, q as RefundRequest, r as RefundResponse, s as RefundStatusResponse, S as SnsEnvelope, W as WebhookVerifierOptions, t as assertSnsUrl, u as canonicalString, v as configFromEnv, w as endpoints, x as resolveConfig } from '../client-UNDtdWhu.cjs';
+import { P as ProviderError, N as NetworkError } from '../errors-CleuZfqT.cjs';
+import { T as TokenStore, L as Logger } from '../token-store-C8IMMLPJ.cjs';
+
+/** Every documented bKash status code, verbatim from the developer portal. */
+declare const BKASH_ERROR_CODES: Record<string, string>;
+/**
+ * Codes meaning "this already happened". Not failures: the right response is to
+ * read current state with getPayment rather than to treat the order as broken.
+ */
+declare const ALREADY_SETTLED_CODES: Set<string>;
+/** Codes caused by the customer, not by your integration. Show them, don't alert on them. */
+declare const CUSTOMER_FAULT_CODES: Set<string>;
+declare class BkashError extends ProviderError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** True when bKash considers the payment already settled — re-query, don't retry. */
+    readonly alreadySettled: boolean;
+    /** True when the customer caused it (wrong PIN, no balance). */
+    readonly customerFault: boolean;
+    /** Bangla message, on the v2 refund API only. */
+    readonly messageBn?: string;
+    constructor(opts: {
+        code: string;
+        message: string;
+        raw?: unknown;
+        messageBn?: string;
+        retryable?: boolean;
+    });
+}
+/**
+ * bKash signals failure in four different envelopes depending on which endpoint
+ * and which API version you hit. All four were observed against the sandbox:
+ *
+ *   1. `{ statusCode: "2002", statusMessage: "Invalid Payment ID" }` with HTTP 200
+ *      — the tokenized checkout endpoints. A 200 here is not success.
+ *   2. `{ errorCode, errorMessage }` — documented for create and execute.
+ *   3. `{ internalCode, externalCode, errorMessageEn, errorMessageBn }` with HTTP 400
+ *      — the v2 refund API only.
+ *   4. `{ message: "Unauthorized" }` with HTTP 401/403 — the AWS API Gateway in
+ *      front of bKash, reached before any bKash logic runs.
+ *
+ * Returns the error to throw, or null when the body represents success.
+ */
+declare function toBkashError(body: unknown, status: number): BkashError | NetworkError | null;
+/**
+ * bKash timestamps are not ISO 8601 and `new Date()` returns Invalid Date for
+ * them. Two formats appear on the wire:
+ *
+ *   "2026-09-18T06:00:19:952 GMT+0600"  — note the colon before milliseconds
+ *   "2024-06-13T16:27:24:000"           — refund API, no offset at all
+ *
+ * A missing offset is read as Bangladesh time (UTC+6), which is what bKash means.
+ */
+declare function parseBkashTime(value: string | undefined | null): Date | undefined;
+/**
+ * Webhook payloads carry a compact `dateTime` of "20180419122246"
+ * (YYYYMMDDHHmmss), in Bangladesh time.
+ */
+declare function parseBkashCompactTime(value: string | undefined | null): Date | undefined;
+
+/**
+ * Keeps exactly one valid bKash access token alive.
+ *
+ * The constraint worth knowing: bKash blocks the merchant account for an hour
+ * if the Refresh Token API is called more than twice within an hour. The budget
+ * belongs to the merchant account, not to your process, so:
+ *
+ *   - refreshes are counted in a rolling window and capped;
+ *   - when the refresh budget runs out, a fresh Grant is used instead, which
+ *     bKash's own token guide names as the alternative;
+ *   - concurrent callers share one in-flight acquisition rather than each
+ *     starting their own;
+ *   - the count lives in the TokenStore, so a shared store makes it correct
+ *     across instances. The default in-process store does not.
+ */
+declare class BkashTokenManager {
+    #private;
+    constructor(config: ResolvedBkashConfig, options?: {
+        store?: TokenStore;
+        logger?: Logger;
+    });
+    /** A token that is valid now, acquiring one only if the cached one will not do. */
+    getToken(): Promise<string>;
+    /**
+     * Drop the cached token so the next call acquires a new one. Use this when
+     * bKash answers 401 — it means the token died earlier than advertised.
+     */
+    invalidate(): Promise<void>;
+    /**
+     * Force one refresh, spending a unit of the hourly budget. Only useful for
+     * proving the refresh path works — normal use should let {@link getToken}
+     * decide. Throws if the budget is already spent.
+     */
+    refreshNow(): Promise<string>;
+    /** What the budget looks like right now. Useful for a health endpoint. */
+    budget(): Promise<{
+        refreshesUsed: number;
+        refreshesAllowed: number;
+        acquisitionsUsed: number;
+    }>;
+}
+
+export { ALREADY_SETTLED_CODES, BKASH_ERROR_CODES, BkashError, BkashTokenManager, CUSTOMER_FAULT_CODES, ResolvedBkashConfig, parseBkashCompactTime, parseBkashTime, toBkashError };

package/dist/bkash/index.d.ts

@@ -0,0 +1,104 @@
+import { R as ResolvedBkashConfig } from '../client-Y9603twG.js';
+export { A as Agreement, b as AgreementHandle, c as AgreementResponse, d as BKASH_API_VERSION, e as BKASH_HOSTS, f as BKASH_MODE, g as BKASH_TRANSACTION_TYPES, h as BkashCallbackQuery, B as BkashClient, i as BkashClientOptions, j as BkashConfig, k as BkashEnvironment, l as BkashIntent, m as BkashIpnMessage, n as BkashMode, a as BkashWebhookVerifier, C as CreateAgreementInput, o as CreatePaymentRequest, p as CreatePaymentResponse, E as ExecutePaymentResponse, G as GrantTokenResponse, Q as QueryPaymentResponse, q as RefundRequest, r as RefundResponse, s as RefundStatusResponse, S as SnsEnvelope, W as WebhookVerifierOptions, t as assertSnsUrl, u as canonicalString, v as configFromEnv, w as endpoints, x as resolveConfig } from '../client-Y9603twG.js';
+import { P as ProviderError, N as NetworkError } from '../errors-CleuZfqT.js';
+import { T as TokenStore, L as Logger } from '../token-store-C8IMMLPJ.js';
+
+/** Every documented bKash status code, verbatim from the developer portal. */
+declare const BKASH_ERROR_CODES: Record<string, string>;
+/**
+ * Codes meaning "this already happened". Not failures: the right response is to
+ * read current state with getPayment rather than to treat the order as broken.
+ */
+declare const ALREADY_SETTLED_CODES: Set<string>;
+/** Codes caused by the customer, not by your integration. Show them, don't alert on them. */
+declare const CUSTOMER_FAULT_CODES: Set<string>;
+declare class BkashError extends ProviderError {
+    static [Symbol.hasInstance]: (value: unknown) => boolean;
+    /** True when bKash considers the payment already settled — re-query, don't retry. */
+    readonly alreadySettled: boolean;
+    /** True when the customer caused it (wrong PIN, no balance). */
+    readonly customerFault: boolean;
+    /** Bangla message, on the v2 refund API only. */
+    readonly messageBn?: string;
+    constructor(opts: {
+        code: string;
+        message: string;
+        raw?: unknown;
+        messageBn?: string;
+        retryable?: boolean;
+    });
+}
+/**
+ * bKash signals failure in four different envelopes depending on which endpoint
+ * and which API version you hit. All four were observed against the sandbox:
+ *
+ *   1. `{ statusCode: "2002", statusMessage: "Invalid Payment ID" }` with HTTP 200
+ *      — the tokenized checkout endpoints. A 200 here is not success.
+ *   2. `{ errorCode, errorMessage }` — documented for create and execute.
+ *   3. `{ internalCode, externalCode, errorMessageEn, errorMessageBn }` with HTTP 400
+ *      — the v2 refund API only.
+ *   4. `{ message: "Unauthorized" }` with HTTP 401/403 — the AWS API Gateway in
+ *      front of bKash, reached before any bKash logic runs.
+ *
+ * Returns the error to throw, or null when the body represents success.
+ */
+declare function toBkashError(body: unknown, status: number): BkashError | NetworkError | null;
+/**
+ * bKash timestamps are not ISO 8601 and `new Date()` returns Invalid Date for
+ * them. Two formats appear on the wire:
+ *
+ *   "2026-09-18T06:00:19:952 GMT+0600"  — note the colon before milliseconds
+ *   "2024-06-13T16:27:24:000"           — refund API, no offset at all
+ *
+ * A missing offset is read as Bangladesh time (UTC+6), which is what bKash means.
+ */
+declare function parseBkashTime(value: string | undefined | null): Date | undefined;
+/**
+ * Webhook payloads carry a compact `dateTime` of "20180419122246"
+ * (YYYYMMDDHHmmss), in Bangladesh time.
+ */
+declare function parseBkashCompactTime(value: string | undefined | null): Date | undefined;
+
+/**
+ * Keeps exactly one valid bKash access token alive.
+ *
+ * The constraint worth knowing: bKash blocks the merchant account for an hour
+ * if the Refresh Token API is called more than twice within an hour. The budget
+ * belongs to the merchant account, not to your process, so:
+ *
+ *   - refreshes are counted in a rolling window and capped;
+ *   - when the refresh budget runs out, a fresh Grant is used instead, which
+ *     bKash's own token guide names as the alternative;
+ *   - concurrent callers share one in-flight acquisition rather than each
+ *     starting their own;
+ *   - the count lives in the TokenStore, so a shared store makes it correct
+ *     across instances. The default in-process store does not.
+ */
+declare class BkashTokenManager {
+    #private;
+    constructor(config: ResolvedBkashConfig, options?: {
+        store?: TokenStore;
+        logger?: Logger;
+    });
+    /** A token that is valid now, acquiring one only if the cached one will not do. */
+    getToken(): Promise<string>;
+    /**
+     * Drop the cached token so the next call acquires a new one. Use this when
+     * bKash answers 401 — it means the token died earlier than advertised.
+     */
+    invalidate(): Promise<void>;
+    /**
+     * Force one refresh, spending a unit of the hourly budget. Only useful for
+     * proving the refresh path works — normal use should let {@link getToken}
+     * decide. Throws if the budget is already spent.
+     */
+    refreshNow(): Promise<string>;
+    /** What the budget looks like right now. Useful for a health endpoint. */
+    budget(): Promise<{
+        refreshesUsed: number;
+        refreshesAllowed: number;
+        acquisitionsUsed: number;
+    }>;
+}
+
+export { ALREADY_SETTLED_CODES, BKASH_ERROR_CODES, BkashError, BkashTokenManager, CUSTOMER_FAULT_CODES, ResolvedBkashConfig, parseBkashCompactTime, parseBkashTime, toBkashError };