paykit-bd 0.1.0

package/dist/token-store-C8IMMLPJ.d.ts

@@ -0,0 +1,240 @@
+/**
+ * The provider-neutral shapes. Every gateway client normalises into these, so
+ * application code can switch bKash for Nagad without rewriting order handling,
+ * while `raw` always keeps the untouched gateway response for the cases where
+ * the normalisation is not enough.
+ */
+type PaymentStatus = "initiated" | "pending" | "completed" | "failed" | "cancelled";
+type PaymentIntent = "sale" | "authorization";
+interface CreatePaymentInput {
+    /** BDT. Accepts "12.50" or 12.5; normalised to a 2-decimal string. */
+    amount: string | number;
+    /** Your order or invoice id. Reaches the gateway and comes back on the webhook. */
+    reference: string;
+    /**
+     * Identifies the payer to the gateway. For bKash, passing the wallet number
+     * pre-fills it on the bKash entry screen.
+     */
+    payerReference?: string;
+    /** Overrides the client's configured callback URL for this payment only. */
+    callbackUrl?: string;
+    /** `"sale"` captures immediately; `"authorization"` holds funds for later capture. */
+    intent?: PaymentIntent;
+    currency?: "BDT";
+    /** Provider-specific extras, passed through untouched. */
+    extra?: Record<string, string>;
+}
+interface CreatedPayment {
+    provider: string;
+    /** Gateway id for this attempt. Store it against your order before redirecting. */
+    paymentId: string;
+    /**
+     * Where to send the customer. `null` when the flow needs no redirect — a bKash
+     * agreement payment, for instance, is authorised with a PIN alone.
+     */
+    redirectUrl: string | null;
+    status: PaymentStatus;
+    amount: string;
+    currency: string;
+    reference?: string;
+    /** When the gateway stops accepting this payment id. bKash: 24 hours. */
+    expiresAt?: Date;
+    raw: unknown;
+}
+interface Payment {
+    provider: string;
+    paymentId: string;
+    /** The financial transaction id, present once money has actually moved. */
+    transactionId: string | null;
+    status: PaymentStatus;
+    amount: string;
+    currency: string;
+    reference?: string;
+    /** Payer's wallet or account number, when the gateway discloses it. */
+    payerAccount?: string;
+    completedAt?: Date;
+    raw: unknown;
+}
+interface RefundInput {
+    paymentId: string;
+    /** The original transaction id, not the payment id. */
+    transactionId: string;
+    /** Omit for a full refund — the provider reads the refundable balance itself. */
+    amount?: string | number;
+    /** Free text kept on the refund record. A default is substituted if omitted. */
+    reason?: string;
+    /** Item identifier. A default is substituted if omitted. */
+    sku?: string;
+}
+interface Refund {
+    provider: string;
+    refundTransactionId: string;
+    originalTransactionId: string;
+    status: PaymentStatus;
+    amount: string;
+    currency: string;
+    completedAt?: Date;
+    raw: unknown;
+}
+type WebhookEventType = "payment.completed" | "payment.failed" | "subscription.confirmation" | "unknown";
+interface WebhookEvent {
+    provider: string;
+    type: WebhookEventType;
+    /** Gateway id for this message. Use it to make your handler idempotent. */
+    eventId?: string;
+    transactionId?: string;
+    reference?: string;
+    amount?: string;
+    currency?: string;
+    payerAccount?: string;
+    occurredAt?: Date;
+    raw: unknown;
+}
+/** What a verifier needs from an inbound HTTP request, framework-independent. */
+interface RawWebhookRequest {
+    /** The exact bytes of the body. Parsing it before verification breaks the signature. */
+    body: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+
+interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+declare const noopLogger: Logger;
+interface HttpResponse<T> {
+    status: number;
+    headers: Headers;
+    body: T;
+    text: string;
+}
+interface RequestOptions {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    /** Serialised as JSON. Omit for GET. */
+    json?: unknown;
+    /** Per-request timeout. Default 30s — bKash PIN flows are genuinely slow. */
+    timeoutMs?: number;
+    /**
+     * Retry count for transport failures and 5xx.
+     *
+     * Defaults to 0 and should stay 0 for anything that moves money. A create or
+     * execute call that times out may still have succeeded at the gateway, so the
+     * safe recovery is to query the payment, not to fire it again.
+     */
+    retries?: number;
+    /** Base backoff in ms; each attempt waits base * 2^n plus jitter. */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * JSON-over-HTTP with a timeout, optional bounded retry and no dependencies.
+ *
+ * Resolves for any HTTP status that produced a parseable JSON body, including
+ * 4xx — gateways signal business errors with a 200 and an errorCode as often as
+ * with a status, so status interpretation belongs to the caller. Throws only
+ * when there is no usable answer at all.
+ */
+declare function requestJson<T = unknown>(url: string, options?: RequestOptions, ctx?: {
+    provider: string;
+    logger?: Logger;
+}): Promise<HttpResponse<T>>;
+
+/**
+ * The seam every gateway implements.
+ *
+ * Deliberately small: the five things an order flow actually needs. Anything a
+ * gateway does beyond this — bKash agreements, for one — stays on that
+ * gateway's own client rather than being forced into a lowest common
+ * denominator that fits nobody.
+ */
+interface PaymentProvider {
+    /** Stable id, e.g. `"bkash"`. Appears on every returned object and error. */
+    readonly id: string;
+    /** Start a payment. The customer is sent to `redirectUrl` when there is one. */
+    createPayment(input: CreatePaymentInput): Promise<CreatedPayment>;
+    /**
+     * Finalise a payment after the customer returns. Call this exactly once per
+     * payment id: gateways typically allow one execution only.
+     */
+    executePayment(paymentId: string): Promise<Payment>;
+    /** Read current state. Safe to call repeatedly — this is the recovery path. */
+    getPayment(paymentId: string): Promise<Payment>;
+    refund(input: RefundInput): Promise<Refund>;
+    /**
+     * Prove an inbound webhook came from the gateway and normalise it.
+     * Throws {@link import("./errors.ts").WebhookVerificationError} if it did not.
+     */
+    verifyWebhook(request: RawWebhookRequest): Promise<WebhookEvent>;
+}
+/** Narrow an unknown object to a PaymentProvider at a plugin boundary. */
+declare function isPaymentProvider(value: unknown): value is PaymentProvider;
+
+/**
+ * Where an access token lives between requests.
+ *
+ * This matters more than it looks. bKash blocks a merchant for an hour if the
+ * Refresh Token API is called more than twice in one hour, and the budget is
+ * counted per merchant account — not per process. A single-process memory store
+ * is therefore only correct while exactly one instance is running. Two pods, or
+ * a serverless function that cold-starts per request, will each believe they
+ * have a fresh budget and between them blow through it.
+ *
+ * For anything beyond one process, back this with something shared: Redis, a
+ * database row, or any KV — see {@link createKvTokenStore}.
+ */
+interface TokenRecord {
+    idToken: string;
+    refreshToken: string;
+    /** Epoch ms at which the gateway stops accepting `idToken`. */
+    expiresAt: number;
+    /**
+     * Epoch ms of every token acquisition still inside the rolling window,
+     * oldest first — grants and refreshes alike.
+     */
+    acquisitions: number[];
+    /**
+     * The subset of {@link acquisitions} that were refreshes. This is what the
+     * gateway's refresh budget is actually counted against.
+     */
+    refreshes: number[];
+}
+interface TokenStore {
+    get(key: string): Promise<TokenRecord | null>;
+    set(key: string, record: TokenRecord): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Optional mutual exclusion around a token acquisition. Implement it on a
+     * shared store to stop N instances refreshing at the same moment; without it
+     * the client still de-duplicates in-flight refreshes within its own process.
+     */
+    withLock?<T>(key: string, ttlMs: number, fn: () => Promise<T>): Promise<T>;
+}
+/** Per-process store. Correct for a single long-lived instance, and nothing else. */
+declare class MemoryTokenStore implements TokenStore {
+    #private;
+    get(key: string): Promise<TokenRecord | null>;
+    set(key: string, record: TokenRecord): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface KvLike {
+    get(key: string): Promise<string | null | undefined>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    /**
+     * Set only if absent, returning whether the write happened. Supplying this
+     * turns on cross-instance locking; without it, locking is skipped.
+     */
+    setIfAbsent?(key: string, value: string, ttlSeconds: number): Promise<boolean>;
+}
+/**
+ * Wrap any string KV — Redis, Upstash, Cloudflare KV, a Prisma table behind
+ * three functions — into a TokenStore.
+ */
+declare function createKvTokenStore(kv: KvLike, opts?: {
+    prefix?: string;
+}): TokenStore;
+
+export { type CreatePaymentInput as C, type HttpResponse as H, type KvLike as K, type Logger as L, MemoryTokenStore as M, type PaymentProvider as P, type RawWebhookRequest as R, type TokenStore as T, type WebhookEvent as W, type CreatedPayment as a, type Payment as b, type RefundInput as c, type Refund as d, type PaymentIntent as e, type PaymentStatus as f, type RequestOptions as g, type TokenRecord as h, type WebhookEventType as i, createKvTokenStore as j, isPaymentProvider as k, requestJson as l, noopLogger as n, redactHeaders as r };

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "paykit-bd",
+  "version": "0.1.0",
+  "description": "Typed, zero-dependency payment clients for Bangladeshi gateways. bKash tokenized checkout with a correct token lifecycle and real AWS SNS webhook verification.",
+  "keywords": [
+    "bkash",
+    "bangladesh",
+    "payment",
+    "payment-gateway",
+    "tokenized-checkout",
+    "webhook",
+    "sns",
+    "nagad",
+    "sslcommerz",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "joarder97",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joarder97/paykit-bd.git"
+  },
+  "homepage": "https://github.com/joarder97/paykit-bd#readme",
+  "bugs": {
+    "url": "https://github.com/joarder97/paykit-bd/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./bkash": {
+      "types": "./dist/bkash/index.d.ts",
+      "import": "./dist/bkash/index.js",
+      "require": "./dist/bkash/index.cjs"
+    },
+    "./bkash/next": {
+      "types": "./dist/bkash/adapters/next.d.ts",
+      "import": "./dist/bkash/adapters/next.js",
+      "require": "./dist/bkash/adapters/next.cjs"
+    },
+    "./bkash/express": {
+      "types": "./dist/bkash/adapters/express.d.ts",
+      "import": "./dist/bkash/adapters/express.js",
+      "require": "./dist/bkash/adapters/express.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts",
+    "smoke": "node scripts/sandbox-smoke.ts",
+    "check": "npm run typecheck && npm run test && npm run build",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run verify:package",
+    "verify:package": "node scripts/verify-package.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "packageManager": "pnpm@11.22.0"
+}