paykit-bd 0.1.0

package/dist/index.js

@@ -0,0 +1,348 @@
+// src/core/errors.ts
+var BRANDS = /* @__PURE__ */ Symbol.for("paykit-bd.error.brands");
+function brandedInstanceOf(tag) {
+  return (value) => {
+    if (typeof value !== "object" || value === null) return false;
+    const brands = value[BRANDS];
+    return Array.isArray(brands) && brands.includes(tag);
+  };
+}
+var PaykitError = class extends Error {
+  static [Symbol.hasInstance] = brandedInstanceOf("PaykitError");
+  /** Class lineage, innermost last. Read `instanceof` instead of this. */
+  [BRANDS];
+  /** Gateway this came from — `"bkash"`, or `"paykit"` for local failures. */
+  provider;
+  /** Stable machine-readable code. Gateway codes are passed through verbatim. */
+  code;
+  /** True when retrying the identical request could plausibly succeed. */
+  retryable;
+  /** Untouched gateway response body, for logging. */
+  raw;
+  constructor(message, opts, brands = []) {
+    super(message, { cause: opts.cause });
+    this.name = new.target.name;
+    this[BRANDS] = ["PaykitError", ...brands];
+    this.provider = opts.provider;
+    this.code = opts.code;
+    this.retryable = opts.retryable ?? false;
+    this.raw = opts.raw;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      provider: this.provider,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable
+    };
+  }
+};
+var ProviderError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("ProviderError");
+  constructor(message, opts, brands = []) {
+    super(message, opts, ["ProviderError", ...brands]);
+  }
+};
+var NetworkError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("NetworkError");
+  /** HTTP status, when there was one. */
+  status;
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "network_error",
+        retryable: true,
+        raw: opts.raw,
+        cause: opts.cause
+      },
+      ["NetworkError"]
+    );
+    this.status = opts.status;
+  }
+};
+var ConfigError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("ConfigError");
+  constructor(message, opts = {}) {
+    super(
+      message,
+      {
+        provider: opts.provider ?? "paykit",
+        code: opts.code ?? "config_error",
+        retryable: false
+      },
+      ["ConfigError"]
+    );
+  }
+};
+var WebhookVerificationError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("WebhookVerificationError");
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "webhook_verification_failed",
+        retryable: false,
+        raw: opts.raw,
+        cause: opts.cause
+      },
+      ["WebhookVerificationError"]
+    );
+  }
+};
+var RateLimitError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("RateLimitError");
+  /** Epoch ms when the guard will let the call through. */
+  retryAt;
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "rate_limited",
+        retryable: true
+      },
+      ["RateLimitError"]
+    );
+    this.retryAt = opts.retryAt;
+  }
+};
+function brandCheckFor(tag) {
+  return brandedInstanceOf(tag);
+}
+
+// src/core/money.ts
+var AMOUNT_RE = /^-?\d+(\.\d{1,2})?$/;
+function toPoisha(amount) {
+  const text = typeof amount === "number" ? formatNumber(amount) : amount.trim();
+  if (!AMOUNT_RE.test(text)) {
+    throw new ConfigError(
+      `Invalid BDT amount ${JSON.stringify(amount)}: expected a decimal with at most 2 places, e.g. "12.50".`,
+      { code: "invalid_amount" }
+    );
+  }
+  const negative = text.startsWith("-");
+  const [whole = "0", fraction = ""] = (negative ? text.slice(1) : text).split(".");
+  const poisha = BigInt(whole) * 100n + BigInt(fraction.padEnd(2, "0"));
+  return negative ? -poisha : poisha;
+}
+function fromPoisha(poisha) {
+  const negative = poisha < 0n;
+  const abs = negative ? -poisha : poisha;
+  const whole = abs / 100n;
+  const fraction = (abs % 100n).toString().padStart(2, "0");
+  return `${negative ? "-" : ""}${whole}.${fraction}`;
+}
+function toAmountString(amount) {
+  return fromPoisha(toPoisha(amount));
+}
+function compareAmount(a, b) {
+  const left = toPoisha(a);
+  const right = toPoisha(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function addAmount(a, b) {
+  return fromPoisha(toPoisha(a) + toPoisha(b));
+}
+function subtractAmount(a, b) {
+  return fromPoisha(toPoisha(a) - toPoisha(b));
+}
+function sumAmounts(amounts) {
+  return fromPoisha(amounts.reduce((total, a) => total + toPoisha(a), 0n));
+}
+function formatNumber(value) {
+  if (!Number.isFinite(value)) {
+    throw new ConfigError(`Invalid BDT amount ${value}: not a finite number.`, { code: "invalid_amount" });
+  }
+  return value.toFixed(2);
+}
+
+// src/core/http.ts
+var noopLogger = {
+  debug() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SECRET_HEADERS = /* @__PURE__ */ new Set(["authorization", "password", "username", "x-app-key", "x-app-secret"]);
+function redactHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key] = SECRET_HEADERS.has(key.toLowerCase()) ? "[redacted]" : value;
+  }
+  return out;
+}
+async function requestJson(url, options = {}, ctx = { provider: "paykit" }) {
+  const {
+    method = "POST",
+    headers = {},
+    json,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retries = 0,
+    retryBaseMs = 300,
+    signal
+  } = options;
+  const logger = ctx.logger ?? noopLogger;
+  const requestHeaders = { Accept: "application/json", ...headers };
+  let payload;
+  if (json !== void 0) {
+    payload = JSON.stringify(json);
+    requestHeaders["Content-Type"] ??= "application/json";
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      const delay = retryBaseMs * 2 ** (attempt - 1) + Math.floor(Math.random() * retryBaseMs);
+      logger.warn("paykit: retrying request", { url, attempt, delay });
+      await sleep(delay, signal);
+    }
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: payload,
+        signal: mergeSignals(signal, AbortSignal.timeout(timeoutMs))
+      });
+      const text = await response.text();
+      if (response.status >= 500) {
+        lastError = new NetworkError(`${ctx.provider}: gateway returned HTTP ${response.status}`, {
+          provider: ctx.provider,
+          code: "upstream_error",
+          status: response.status,
+          raw: text.slice(0, 2e3)
+        });
+        if (attempt < retries) continue;
+        throw lastError;
+      }
+      let body;
+      try {
+        body = text ? JSON.parse(text) : {};
+      } catch (cause) {
+        throw new NetworkError(
+          `${ctx.provider}: expected JSON but got ${describeBody(text)} (HTTP ${response.status})`,
+          { provider: ctx.provider, code: "invalid_json", status: response.status, raw: text.slice(0, 2e3), cause }
+        );
+      }
+      logger.debug("paykit: request complete", {
+        url,
+        method,
+        status: response.status,
+        headers: redactHeaders(requestHeaders)
+      });
+      return { status: response.status, headers: response.headers, body, text };
+    } catch (error) {
+      if (error instanceof NetworkError && error.code === "invalid_json") throw error;
+      lastError = error;
+      const aborted = signal?.aborted === true;
+      if (aborted || attempt >= retries) {
+        if (error instanceof NetworkError) throw error;
+        throw new NetworkError(`${ctx.provider}: request to ${url} failed`, {
+          provider: ctx.provider,
+          code: isTimeout(error) ? "timeout" : "network_error",
+          cause: error
+        });
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new NetworkError(`${ctx.provider}: request to ${url} failed`, { provider: ctx.provider });
+}
+function describeBody(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return "an empty body";
+  if (trimmed.startsWith("<")) return "HTML (usually a proxy or WAF page)";
+  return `${JSON.stringify(trimmed.slice(0, 80))}\u2026`;
+}
+function isTimeout(error) {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+function mergeSignals(...signals) {
+  const present = signals.filter((s) => s !== void 0);
+  return present.length === 1 ? present[0] : AbortSignal.any(present);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/core/token-store.ts
+var MemoryTokenStore = class {
+  #records = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.#records.get(key) ?? null;
+  }
+  async set(key, record) {
+    this.#records.set(key, record);
+  }
+  async delete(key) {
+    this.#records.delete(key);
+  }
+};
+function createKvTokenStore(kv, opts = {}) {
+  const prefix = opts.prefix ?? "paykit:token:";
+  const store = {
+    async get(key) {
+      const raw = await kv.get(prefix + key);
+      if (!raw) return null;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async set(key, record) {
+      const ttlSeconds = Math.max(60, Math.ceil((record.expiresAt - Date.now()) / 1e3) + 3600);
+      await kv.set(prefix + key, JSON.stringify(record), ttlSeconds);
+    },
+    async delete(key) {
+      await kv.del(prefix + key);
+    }
+  };
+  if (kv.setIfAbsent) {
+    const setIfAbsent = kv.setIfAbsent.bind(kv);
+    store.withLock = async function withLock(key, ttlMs, fn) {
+      const lockKey = `${prefix}lock:${key}`;
+      const ttlSeconds = Math.max(1, Math.ceil(ttlMs / 1e3));
+      const deadline = Date.now() + ttlMs;
+      while (Date.now() < deadline) {
+        if (await setIfAbsent(lockKey, String(Date.now()), ttlSeconds)) {
+          try {
+            return await fn();
+          } finally {
+            await kv.del(lockKey);
+          }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50 + Math.floor(Math.random() * 100)));
+      }
+      return fn();
+    };
+  }
+  return store;
+}
+
+// src/core/provider.ts
+function isPaymentProvider(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate["id"] === "string" && typeof candidate["createPayment"] === "function" && typeof candidate["executePayment"] === "function" && typeof candidate["getPayment"] === "function" && typeof candidate["refund"] === "function" && typeof candidate["verifyWebhook"] === "function";
+}
+
+export { ConfigError, MemoryTokenStore, NetworkError, PaykitError, ProviderError, RateLimitError, WebhookVerificationError, addAmount, brandCheckFor, compareAmount, createKvTokenStore, fromPoisha, isPaymentProvider, noopLogger, redactHeaders, requestJson, subtractAmount, sumAmounts, toAmountString, toPoisha };

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

@@ -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 };