paykit-bd 0.1.0

package/dist/index.cjs

@@ -0,0 +1,369 @@
+'use strict';
+
+// 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";
+}
+
+exports.ConfigError = ConfigError;
+exports.MemoryTokenStore = MemoryTokenStore;
+exports.NetworkError = NetworkError;
+exports.PaykitError = PaykitError;
+exports.ProviderError = ProviderError;
+exports.RateLimitError = RateLimitError;
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.addAmount = addAmount;
+exports.brandCheckFor = brandCheckFor;
+exports.compareAmount = compareAmount;
+exports.createKvTokenStore = createKvTokenStore;
+exports.fromPoisha = fromPoisha;
+exports.isPaymentProvider = isPaymentProvider;
+exports.noopLogger = noopLogger;
+exports.redactHeaders = redactHeaders;
+exports.requestJson = requestJson;
+exports.subtractAmount = subtractAmount;
+exports.sumAmounts = sumAmounts;
+exports.toAmountString = toAmountString;
+exports.toPoisha = toPoisha;

package/dist/index.d.cts

@@ -0,0 +1,20 @@
+export { C as ConfigError, N as NetworkError, a as PaykitError, P as ProviderError, R as RateLimitError, W as WebhookVerificationError, b as brandCheckFor } from './errors-CleuZfqT.cjs';
+export { C as CreatePaymentInput, a as CreatedPayment, H as HttpResponse, K as KvLike, L as Logger, M as MemoryTokenStore, b as Payment, e as PaymentIntent, P as PaymentProvider, f as PaymentStatus, R as RawWebhookRequest, d as Refund, c as RefundInput, g as RequestOptions, h as TokenRecord, T as TokenStore, W as WebhookEvent, i as WebhookEventType, j as createKvTokenStore, k as isPaymentProvider, n as noopLogger, r as redactHeaders, l as requestJson } from './token-store-C8IMMLPJ.cjs';
+
+/** Parse a BDT decimal string or number into integer poisha. */
+declare function toPoisha(amount: string | number): bigint;
+/** Format integer poisha back into the 2-decimal string the gateway expects. */
+declare function fromPoisha(poisha: bigint): string;
+/**
+ * Normalise any accepted amount into the canonical "123.45" form.
+ * Use this on every amount before it goes into a request body.
+ */
+declare function toAmountString(amount: string | number): string;
+/** -1, 0 or 1 — a total order on amounts that does not go through floats. */
+declare function compareAmount(a: string | number, b: string | number): -1 | 0 | 1;
+declare function addAmount(a: string | number, b: string | number): string;
+declare function subtractAmount(a: string | number, b: string | number): string;
+/** Sum a list of amounts. Useful for checking partial refunds against a total. */
+declare function sumAmounts(amounts: Array<string | number>): string;
+
+export { addAmount, compareAmount, fromPoisha, subtractAmount, sumAmounts, toAmountString, toPoisha };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { C as ConfigError, N as NetworkError, a as PaykitError, P as ProviderError, R as RateLimitError, W as WebhookVerificationError, b as brandCheckFor } from './errors-CleuZfqT.js';
+export { C as CreatePaymentInput, a as CreatedPayment, H as HttpResponse, K as KvLike, L as Logger, M as MemoryTokenStore, b as Payment, e as PaymentIntent, P as PaymentProvider, f as PaymentStatus, R as RawWebhookRequest, d as Refund, c as RefundInput, g as RequestOptions, h as TokenRecord, T as TokenStore, W as WebhookEvent, i as WebhookEventType, j as createKvTokenStore, k as isPaymentProvider, n as noopLogger, r as redactHeaders, l as requestJson } from './token-store-C8IMMLPJ.js';
+
+/** Parse a BDT decimal string or number into integer poisha. */
+declare function toPoisha(amount: string | number): bigint;
+/** Format integer poisha back into the 2-decimal string the gateway expects. */
+declare function fromPoisha(poisha: bigint): string;
+/**
+ * Normalise any accepted amount into the canonical "123.45" form.
+ * Use this on every amount before it goes into a request body.
+ */
+declare function toAmountString(amount: string | number): string;
+/** -1, 0 or 1 — a total order on amounts that does not go through floats. */
+declare function compareAmount(a: string | number, b: string | number): -1 | 0 | 1;
+declare function addAmount(a: string | number, b: string | number): string;
+declare function subtractAmount(a: string | number, b: string | number): string;
+/** Sum a list of amounts. Useful for checking partial refunds against a total. */
+declare function sumAmounts(amounts: Array<string | number>): string;
+
+export { addAmount, compareAmount, fromPoisha, subtractAmount, sumAmounts, toAmountString, toPoisha };