@lacspace/esewa 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+
+# @lacspace/esewa
+
+**eSewa ePay v2 (Nepal) — HMAC-SHA256 signing, checkout-form building, response verification & status checks, over Web Crypto.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/esewa?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/esewa)
+[![install size](https://packagephobia.com/badge?p=@lacspace/esewa)](https://packagephobia.com/result?p=@lacspace/esewa)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/esewa?label=minzip)](https://bundlephobia.com/package/@lacspace/esewa)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/esewa)
+[![license](https://img.shields.io/npm/l/@lacspace/esewa?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Integrate **eSewa** — Nepal's most-used payment gateway — the correct way. The signature eSewa demands (`HMAC-SHA256` over `total_amount,transaction_uuid,product_code`, base64) is trivial to get subtly wrong. This gets it right, builds the whole checkout form for you, verifies the signed response, and checks transaction status. Zero dependencies, isomorphic, fully typed.
+
+- ✍️ **Correct signatures** — the exact `signed_field_names` message order, HMAC-SHA256, standard base64
+- 🧾 **Form builder** — a ready-to-POST `{ action, method, fields }` with every field + a valid signature
+- 🔎 **Verify responses** — decode & timing-safe-verify the base64 `data` payload eSewa returns on success
+- 📡 **Status API** — query the transaction-status endpoint with an injectable `fetch`
+- ⚡ Isomorphic — Node 20+, edge runtimes & browsers · Web Crypto only · 📦 ESM + CJS · zero deps
+
+## Install
+
+```bash
+npm install @lacspace/esewa      # or pnpm add / yarn add / bun add
+```
+
+## Build & post the checkout form
+
+```ts
+import { buildForm, ESEWA_TEST_SECRET, ESEWA_TEST_PRODUCT_CODE } from "@lacspace/esewa";
+
+const form = await buildForm(
+  {
+    amount: 100,
+    taxAmount: 0,
+    transactionUuid: crypto.randomUUID(),
+    productCode: ESEWA_TEST_PRODUCT_CODE,
+    successUrl: "https://myshop.np/esewa/success",
+    failureUrl: "https://myshop.np/esewa/failure",
+  },
+  { secret: ESEWA_TEST_SECRET, env: "test" },
+);
+
+// form.action → the eSewa endpoint, form.method → "POST"
+// render form.fields as hidden <input>s and auto-submit.
+```
+
+`total_amount` defaults to `amount + taxAmount + productServiceCharge + productDeliveryCharge`.
+
+## Verify the success redirect
+
+```ts
+import { verifyResponse } from "@lacspace/esewa";
+
+// eSewa redirects to your success_url with ?data=<base64 JSON>
+const { valid, data } = await verifyResponse(url.searchParams.get("data")!, secret);
+if (valid && data.status === "COMPLETE") {
+  fulfilOrder(data.transaction_uuid);
+}
+```
+
+`verifyResponse()` recomputes the signature over the fields named in the payload's own `signed_field_names` and compares it **timing-safe** — it never throws.
+
+## Check transaction status
+
+```ts
+import { checkStatus } from "@lacspace/esewa";
+
+const status = await checkStatus(
+  { product_code: "EPAYTEST", total_amount: 100, transaction_uuid: "11-201" },
+  { env: "test" },
+);
+// → { status: "COMPLETE", ... }
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `signPayment({ total_amount, transaction_uuid, product_code }, secret)` | base64 HMAC-SHA256 signature |
+| `buildForm(input, { secret, env? })` | `{ action, method, fields }` ready to POST |
+| `verifyResponse(base64Data, secret)` | `{ valid, data }` — decode + timing-safe verify |
+| `checkStatus(params, { env?, fetch? })` | GET the status API, returns parsed JSON |
+| `ESEWA_FORM_URLS` / `ESEWA_STATUS_URLS` | `{ test, prod }` endpoint maps |
+| `ESEWA_TEST_SECRET` / `ESEWA_TEST_PRODUCT_CODE` | sandbox credentials |
+| `ESEWA_SIGNED_FIELD_NAMES` | `"total_amount,transaction_uuid,product_code"` |
+
+`env` is `"test"` (default) or `"prod"`. Signatures use standard base64 (not url-safe), exactly as eSewa expects.
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+<!-- LACSPACE-DEV-PLATFORM -->
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/esewa` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,137 @@
+'use strict';
+
+// src/index.ts
+var ESEWA_FORM_URLS = {
+  test: "https://rc-epay.esewa.com.np/api/epay/main/v2/form",
+  prod: "https://epay.esewa.com.np/api/epay/main/v2/form"
+};
+var ESEWA_STATUS_URLS = {
+  test: "https://rc.esewa.com.np/api/epay/transaction/status/",
+  prod: "https://epay.esewa.com.np/api/epay/transaction/status/"
+};
+var ESEWA_TEST_SECRET = "8gBm/:&EnhH.1/q@K@";
+var ESEWA_TEST_PRODUCT_CODE = "EPAYTEST";
+var ESEWA_SIGNED_FIELD_NAMES = "total_amount,transaction_uuid,product_code";
+var enc = new TextEncoder();
+var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function toBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += B64[b0 >> 2];
+    out += B64[(b0 & 3) << 4 | b1 >> 4];
+    out += i + 1 < bytes.length ? B64[(b1 & 15) << 2 | b2 >> 6] : "=";
+    out += i + 2 < bytes.length ? B64[b2 & 63] : "=";
+  }
+  return out;
+}
+function fromBase64(b64) {
+  const clean = b64.replace(/[^A-Za-z0-9+/]/g, "");
+  const len = Math.floor(clean.length * 3 / 4);
+  const bytes = new Uint8Array(len);
+  let p = 0;
+  for (let i = 0; i < clean.length; i += 4) {
+    const c0 = B64.indexOf(clean[i]);
+    const c1 = B64.indexOf(clean[i + 1]);
+    const c2 = i + 2 < clean.length ? B64.indexOf(clean[i + 2]) : -1;
+    const c3 = i + 3 < clean.length ? B64.indexOf(clean[i + 3]) : -1;
+    if (p < len) bytes[p++] = c0 << 2 | c1 >> 4;
+    if (c2 >= 0 && p < len) bytes[p++] = (c1 & 15) << 4 | c2 >> 2;
+    if (c3 >= 0 && p < len) bytes[p++] = (c2 & 3) << 6 | c3;
+  }
+  return bytes;
+}
+async function hmacSha256Base64(secret, message) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("@lacspace/esewa: Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime.");
+  const key = await subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await subtle.sign("HMAC", key, enc.encode(message));
+  return toBase64(new Uint8Array(sig));
+}
+function timingSafeEqual(a, b) {
+  const ab = enc.encode(a);
+  const bb = enc.encode(b);
+  let diff = ab.length ^ bb.length;
+  const n = Math.max(ab.length, bb.length);
+  for (let i = 0; i < n; i++) diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);
+  return diff === 0;
+}
+async function signPayment(fields, secret) {
+  const message = `total_amount=${fields.total_amount},transaction_uuid=${fields.transaction_uuid},product_code=${fields.product_code}`;
+  return hmacSha256Base64(secret, message);
+}
+async function buildForm(input, opts) {
+  const tax = input.taxAmount ?? 0;
+  const service = input.productServiceCharge ?? 0;
+  const delivery = input.productDeliveryCharge ?? 0;
+  const total = input.totalAmount ?? input.amount + tax + service + delivery;
+  const signature = await signPayment(
+    {
+      total_amount: total,
+      transaction_uuid: input.transactionUuid,
+      product_code: input.productCode
+    },
+    opts.secret
+  );
+  const fields = {
+    amount: String(input.amount),
+    tax_amount: String(tax),
+    total_amount: String(total),
+    transaction_uuid: input.transactionUuid,
+    product_code: input.productCode,
+    product_service_charge: String(service),
+    product_delivery_charge: String(delivery),
+    success_url: input.successUrl,
+    failure_url: input.failureUrl,
+    signed_field_names: ESEWA_SIGNED_FIELD_NAMES,
+    signature
+  };
+  return { action: ESEWA_FORM_URLS[opts.env ?? "test"], method: "POST", fields };
+}
+async function verifyResponse(base64Data, secret) {
+  let data;
+  try {
+    data = JSON.parse(new TextDecoder().decode(fromBase64(base64Data)));
+  } catch {
+    return { valid: false, data: {} };
+  }
+  const names = typeof data.signed_field_names === "string" ? data.signed_field_names : "";
+  const provided = typeof data.signature === "string" ? data.signature : "";
+  if (!names || !provided) return { valid: false, data };
+  const message = names.split(",").map((name) => `${name}=${data[name] ?? ""}`).join(",");
+  const expected = await hmacSha256Base64(secret, message);
+  return { valid: timingSafeEqual(expected, provided), data };
+}
+async function checkStatus(params, opts) {
+  const base = ESEWA_STATUS_URLS[opts?.env ?? "test"];
+  const qs = new URLSearchParams({
+    product_code: params.product_code,
+    total_amount: String(params.total_amount),
+    transaction_uuid: params.transaction_uuid
+  }).toString();
+  const url = `${base}?${qs}`;
+  const doFetch = opts?.fetch ?? globalThis.fetch;
+  if (!doFetch) throw new Error("@lacspace/esewa: global fetch is unavailable; pass opts.fetch.");
+  const res = await doFetch(url, { method: "GET" });
+  return res.json();
+}
+
+exports.ESEWA_FORM_URLS = ESEWA_FORM_URLS;
+exports.ESEWA_SIGNED_FIELD_NAMES = ESEWA_SIGNED_FIELD_NAMES;
+exports.ESEWA_STATUS_URLS = ESEWA_STATUS_URLS;
+exports.ESEWA_TEST_PRODUCT_CODE = ESEWA_TEST_PRODUCT_CODE;
+exports.ESEWA_TEST_SECRET = ESEWA_TEST_SECRET;
+exports.buildForm = buildForm;
+exports.checkStatus = checkStatus;
+exports.signPayment = signPayment;
+exports.verifyResponse = verifyResponse;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/esewa\n *\n * eSewa ePay v2 (Nepal) — the correct, tiny way to integrate Nepal's most-used\n * payment gateway. Handles the three things every integration re-implements:\n *\n *   1. **Signing** — the HMAC-SHA256 signature eSewa requires on the checkout\n *      form, computed over `total_amount,transaction_uuid,product_code` in the\n *      exact order of `signed_field_names`, base64-encoded.\n *   2. **Form building** — a ready-to-POST `{ action, method, fields }` object\n *      with every field eSewa expects, including a valid `signature`.\n *   3. **Verification & status** — decode and verify the signed base64 `data`\n *      payload eSewa returns on success (timing-safe), and query the\n *      transaction-status API.\n *\n * Built on Web Crypto (`globalThis.crypto.subtle`) — never hand-rolled\n * cryptography. Isomorphic: Node 20+, edge runtimes and browsers. Zero deps.\n */\n\n/* ------------------------------------------------------------------ *\n * Endpoints & test credentials\n * ------------------------------------------------------------------ */\n\nexport type EsewaEnv = \"test\" | \"prod\";\n\n/** eSewa checkout form endpoints (the URL you POST the form to). */\nexport const ESEWA_FORM_URLS: Record<EsewaEnv, string> = {\n  test: \"https://rc-epay.esewa.com.np/api/epay/main/v2/form\",\n  prod: \"https://epay.esewa.com.np/api/epay/main/v2/form\",\n};\n\n/** eSewa transaction-status API endpoints. */\nexport const ESEWA_STATUS_URLS: Record<EsewaEnv, string> = {\n  test: \"https://rc.esewa.com.np/api/epay/transaction/status/\",\n  prod: \"https://epay.esewa.com.np/api/epay/transaction/status/\",\n};\n\n/** eSewa-published sandbox secret key (test environment only). */\nexport const ESEWA_TEST_SECRET = \"8gBm/:&EnhH.1/q@K@\";\n\n/** eSewa-published sandbox merchant/product code (test environment only). */\nexport const ESEWA_TEST_PRODUCT_CODE = \"EPAYTEST\";\n\n/** The fields eSewa signs, in the required order. */\nexport const ESEWA_SIGNED_FIELD_NAMES = \"total_amount,transaction_uuid,product_code\";\n\n/* ------------------------------------------------------------------ *\n * Web Crypto + base64 helpers (isomorphic, zero-dependency)\n * ------------------------------------------------------------------ */\n\nconst enc = new TextEncoder();\nconst B64 = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/\";\n\n/** Standard base64 (NOT url-safe) encode of raw bytes. */\nfunction toBase64(bytes: Uint8Array): string {\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i]!;\n    const b1 = i + 1 < bytes.length ? bytes[i + 1]! : 0;\n    const b2 = i + 2 < bytes.length ? bytes[i + 2]! : 0;\n    out += B64[b0 >> 2];\n    out += B64[((b0 & 3) << 4) | (b1 >> 4)];\n    out += i + 1 < bytes.length ? B64[((b1 & 15) << 2) | (b2 >> 6)] : \"=\";\n    out += i + 2 < bytes.length ? B64[b2 & 63] : \"=\";\n  }\n  return out;\n}\n\n/** Standard base64 decode to raw bytes. */\nfunction fromBase64(b64: string): Uint8Array {\n  const clean = b64.replace(/[^A-Za-z0-9+/]/g, \"\");\n  const len = Math.floor((clean.length * 3) / 4);\n  const bytes = new Uint8Array(len);\n  let p = 0;\n  for (let i = 0; i < clean.length; i += 4) {\n    const c0 = B64.indexOf(clean[i]!);\n    const c1 = B64.indexOf(clean[i + 1]!);\n    const c2 = i + 2 < clean.length ? B64.indexOf(clean[i + 2]!) : -1;\n    const c3 = i + 3 < clean.length ? B64.indexOf(clean[i + 3]!) : -1;\n    if (p < len) bytes[p++] = (c0 << 2) | (c1 >> 4);\n    if (c2 >= 0 && p < len) bytes[p++] = ((c1 & 15) << 4) | (c2 >> 2);\n    if (c3 >= 0 && p < len) bytes[p++] = ((c2 & 3) << 6) | c3;\n  }\n  return bytes;\n}\n\n/** HMAC-SHA256 over `message` with `secret`, returned as standard base64. */\nasync function hmacSha256Base64(secret: string, message: string): Promise<string> {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) throw new Error(\"@lacspace/esewa: Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime.\");\n  const key = await subtle.importKey(\n    \"raw\",\n    enc.encode(secret),\n    { name: \"HMAC\", hash: \"SHA-256\" },\n    false,\n    [\"sign\"],\n  );\n  const sig = await subtle.sign(\"HMAC\", key, enc.encode(message));\n  return toBase64(new Uint8Array(sig));\n}\n\n/** Constant-time comparison of two strings (avoids signature-timing leaks). */\nfunction timingSafeEqual(a: string, b: string): boolean {\n  const ab = enc.encode(a);\n  const bb = enc.encode(b);\n  // Compare a fixed number of bytes; length mismatch still fails.\n  let diff = ab.length ^ bb.length;\n  const n = Math.max(ab.length, bb.length);\n  for (let i = 0; i < n; i++) diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);\n  return diff === 0;\n}\n\n/* ------------------------------------------------------------------ *\n * Signing\n * ------------------------------------------------------------------ */\n\nexport interface SignFields {\n  total_amount: string | number;\n  transaction_uuid: string;\n  product_code: string;\n}\n\n/**\n * Compute the eSewa signature for the required signed fields. The message is\n * `total_amount=<v>,transaction_uuid=<v>,product_code=<v>` (the exact order of\n * `signed_field_names`), HMAC-SHA256'd with the merchant secret and returned as\n * standard base64.\n *\n * @example\n * const sig = await signPayment(\n *   { total_amount: 100, transaction_uuid: \"11-201\", product_code: \"EPAYTEST\" },\n *   ESEWA_TEST_SECRET,\n * );\n */\nexport async function signPayment(fields: SignFields, secret: string): Promise<string> {\n  const message =\n    `total_amount=${fields.total_amount},` +\n    `transaction_uuid=${fields.transaction_uuid},` +\n    `product_code=${fields.product_code}`;\n  return hmacSha256Base64(secret, message);\n}\n\n/* ------------------------------------------------------------------ *\n * Form building\n * ------------------------------------------------------------------ */\n\nexport interface BuildFormInput {\n  /** Base product amount. */\n  amount: number;\n  /** Tax amount. Default 0. */\n  taxAmount?: number;\n  /** Grand total. Defaults to amount + tax + service + delivery. */\n  totalAmount?: number;\n  /** Unique transaction id you generate. */\n  transactionUuid: string;\n  /** Merchant product code (e.g. \"EPAYTEST\" in test). */\n  productCode: string;\n  /** Where eSewa redirects on success. */\n  successUrl: string;\n  /** Where eSewa redirects on failure. */\n  failureUrl: string;\n  /** Product service charge. Default 0. */\n  productServiceCharge?: number;\n  /** Product delivery charge. Default 0. */\n  productDeliveryCharge?: number;\n}\n\nexport interface EsewaForm {\n  /** URL to POST the form to. */\n  action: string;\n  method: \"POST\";\n  /** All fields eSewa expects, as strings ready for form inputs. */\n  fields: Record<string, string>;\n}\n\n/**\n * Build a ready-to-POST eSewa checkout form: `{ action, method, fields }`. The\n * `total_amount` defaults to `amount + taxAmount + serviceCharge + deliveryCharge`,\n * and a valid `signature` is computed for you.\n *\n * @example\n * const form = await buildForm(\n *   { amount: 100, transactionUuid: \"11-201\", productCode: ESEWA_TEST_PRODUCT_CODE,\n *     successUrl: \"https://me/ok\", failureUrl: \"https://me/fail\" },\n *   { secret: ESEWA_TEST_SECRET, env: \"test\" },\n * );\n * // render form.fields as hidden inputs and auto-submit to form.action\n */\nexport async function buildForm(\n  input: BuildFormInput,\n  opts: { secret: string; env?: EsewaEnv },\n): Promise<EsewaForm> {\n  const tax = input.taxAmount ?? 0;\n  const service = input.productServiceCharge ?? 0;\n  const delivery = input.productDeliveryCharge ?? 0;\n  const total = input.totalAmount ?? input.amount + tax + service + delivery;\n\n  const signature = await signPayment(\n    {\n      total_amount: total,\n      transaction_uuid: input.transactionUuid,\n      product_code: input.productCode,\n    },\n    opts.secret,\n  );\n\n  const fields: Record<string, string> = {\n    amount: String(input.amount),\n    tax_amount: String(tax),\n    total_amount: String(total),\n    transaction_uuid: input.transactionUuid,\n    product_code: input.productCode,\n    product_service_charge: String(service),\n    product_delivery_charge: String(delivery),\n    success_url: input.successUrl,\n    failure_url: input.failureUrl,\n    signed_field_names: ESEWA_SIGNED_FIELD_NAMES,\n    signature,\n  };\n\n  return { action: ESEWA_FORM_URLS[opts.env ?? \"test\"], method: \"POST\", fields };\n}\n\n/* ------------------------------------------------------------------ *\n * Response verification\n * ------------------------------------------------------------------ */\n\nexport interface VerifyResult {\n  valid: boolean;\n  /** The decoded response fields. */\n  data: Record<string, unknown>;\n}\n\n/**\n * Verify the signed base64 `data` payload eSewa appends to the success redirect.\n * Decodes the JSON, recomputes the signature over the fields named in its own\n * `signed_field_names`, and compares (timing-safe) against its `signature`.\n * Never throws — returns `{ valid, data }`.\n *\n * @example\n * const { valid, data } = await verifyResponse(url.searchParams.get(\"data\")!, secret);\n * if (valid && data.status === \"COMPLETE\") fulfilOrder(data.transaction_uuid);\n */\nexport async function verifyResponse(base64Data: string, secret: string): Promise<VerifyResult> {\n  let data: Record<string, unknown>;\n  try {\n    data = JSON.parse(new TextDecoder().decode(fromBase64(base64Data))) as Record<string, unknown>;\n  } catch {\n    return { valid: false, data: {} };\n  }\n\n  const names = typeof data.signed_field_names === \"string\" ? data.signed_field_names : \"\";\n  const provided = typeof data.signature === \"string\" ? data.signature : \"\";\n  if (!names || !provided) return { valid: false, data };\n\n  const message = names\n    .split(\",\")\n    .map((name) => `${name}=${data[name] ?? \"\"}`)\n    .join(\",\");\n  const expected = await hmacSha256Base64(secret, message);\n\n  return { valid: timingSafeEqual(expected, provided), data };\n}\n\n/* ------------------------------------------------------------------ *\n * Transaction status\n * ------------------------------------------------------------------ */\n\nexport interface StatusParams {\n  product_code: string;\n  total_amount: string | number;\n  transaction_uuid: string;\n}\n\n/**\n * Query the eSewa transaction-status API. GETs the status endpoint with\n * `product_code`, `total_amount` and `transaction_uuid` as query params and\n * returns the parsed JSON. Inject a custom `fetch` for tests or non-global\n * runtimes.\n *\n * @example\n * const status = await checkStatus(\n *   { product_code: \"EPAYTEST\", total_amount: 100, transaction_uuid: \"11-201\" },\n *   { env: \"test\" },\n * );\n */\nexport async function checkStatus(\n  params: StatusParams,\n  opts?: { env?: EsewaEnv; fetch?: typeof fetch },\n): Promise<unknown> {\n  const base = ESEWA_STATUS_URLS[opts?.env ?? \"test\"];\n  const qs = new URLSearchParams({\n    product_code: params.product_code,\n    total_amount: String(params.total_amount),\n    transaction_uuid: params.transaction_uuid,\n  }).toString();\n  const url = `${base}?${qs}`;\n\n  const doFetch = opts?.fetch ?? globalThis.fetch;\n  if (!doFetch) throw new Error(\"@lacspace/esewa: global fetch is unavailable; pass opts.fetch.\");\n  const res = await doFetch(url, { method: \"GET\" });\n  return res.json();\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+/**
+ * @lacspace/esewa
+ *
+ * eSewa ePay v2 (Nepal) — the correct, tiny way to integrate Nepal's most-used
+ * payment gateway. Handles the three things every integration re-implements:
+ *
+ *   1. **Signing** — the HMAC-SHA256 signature eSewa requires on the checkout
+ *      form, computed over `total_amount,transaction_uuid,product_code` in the
+ *      exact order of `signed_field_names`, base64-encoded.
+ *   2. **Form building** — a ready-to-POST `{ action, method, fields }` object
+ *      with every field eSewa expects, including a valid `signature`.
+ *   3. **Verification & status** — decode and verify the signed base64 `data`
+ *      payload eSewa returns on success (timing-safe), and query the
+ *      transaction-status API.
+ *
+ * Built on Web Crypto (`globalThis.crypto.subtle`) — never hand-rolled
+ * cryptography. Isomorphic: Node 20+, edge runtimes and browsers. Zero deps.
+ */
+type EsewaEnv = "test" | "prod";
+/** eSewa checkout form endpoints (the URL you POST the form to). */
+declare const ESEWA_FORM_URLS: Record<EsewaEnv, string>;
+/** eSewa transaction-status API endpoints. */
+declare const ESEWA_STATUS_URLS: Record<EsewaEnv, string>;
+/** eSewa-published sandbox secret key (test environment only). */
+declare const ESEWA_TEST_SECRET = "8gBm/:&EnhH.1/q@K@";
+/** eSewa-published sandbox merchant/product code (test environment only). */
+declare const ESEWA_TEST_PRODUCT_CODE = "EPAYTEST";
+/** The fields eSewa signs, in the required order. */
+declare const ESEWA_SIGNED_FIELD_NAMES = "total_amount,transaction_uuid,product_code";
+interface SignFields {
+    total_amount: string | number;
+    transaction_uuid: string;
+    product_code: string;
+}
+/**
+ * Compute the eSewa signature for the required signed fields. The message is
+ * `total_amount=<v>,transaction_uuid=<v>,product_code=<v>` (the exact order of
+ * `signed_field_names`), HMAC-SHA256'd with the merchant secret and returned as
+ * standard base64.
+ *
+ * @example
+ * const sig = await signPayment(
+ *   { total_amount: 100, transaction_uuid: "11-201", product_code: "EPAYTEST" },
+ *   ESEWA_TEST_SECRET,
+ * );
+ */
+declare function signPayment(fields: SignFields, secret: string): Promise<string>;
+interface BuildFormInput {
+    /** Base product amount. */
+    amount: number;
+    /** Tax amount. Default 0. */
+    taxAmount?: number;
+    /** Grand total. Defaults to amount + tax + service + delivery. */
+    totalAmount?: number;
+    /** Unique transaction id you generate. */
+    transactionUuid: string;
+    /** Merchant product code (e.g. "EPAYTEST" in test). */
+    productCode: string;
+    /** Where eSewa redirects on success. */
+    successUrl: string;
+    /** Where eSewa redirects on failure. */
+    failureUrl: string;
+    /** Product service charge. Default 0. */
+    productServiceCharge?: number;
+    /** Product delivery charge. Default 0. */
+    productDeliveryCharge?: number;
+}
+interface EsewaForm {
+    /** URL to POST the form to. */
+    action: string;
+    method: "POST";
+    /** All fields eSewa expects, as strings ready for form inputs. */
+    fields: Record<string, string>;
+}
+/**
+ * Build a ready-to-POST eSewa checkout form: `{ action, method, fields }`. The
+ * `total_amount` defaults to `amount + taxAmount + serviceCharge + deliveryCharge`,
+ * and a valid `signature` is computed for you.
+ *
+ * @example
+ * const form = await buildForm(
+ *   { amount: 100, transactionUuid: "11-201", productCode: ESEWA_TEST_PRODUCT_CODE,
+ *     successUrl: "https://me/ok", failureUrl: "https://me/fail" },
+ *   { secret: ESEWA_TEST_SECRET, env: "test" },
+ * );
+ * // render form.fields as hidden inputs and auto-submit to form.action
+ */
+declare function buildForm(input: BuildFormInput, opts: {
+    secret: string;
+    env?: EsewaEnv;
+}): Promise<EsewaForm>;
+interface VerifyResult {
+    valid: boolean;
+    /** The decoded response fields. */
+    data: Record<string, unknown>;
+}
+/**
+ * Verify the signed base64 `data` payload eSewa appends to the success redirect.
+ * Decodes the JSON, recomputes the signature over the fields named in its own
+ * `signed_field_names`, and compares (timing-safe) against its `signature`.
+ * Never throws — returns `{ valid, data }`.
+ *
+ * @example
+ * const { valid, data } = await verifyResponse(url.searchParams.get("data")!, secret);
+ * if (valid && data.status === "COMPLETE") fulfilOrder(data.transaction_uuid);
+ */
+declare function verifyResponse(base64Data: string, secret: string): Promise<VerifyResult>;
+interface StatusParams {
+    product_code: string;
+    total_amount: string | number;
+    transaction_uuid: string;
+}
+/**
+ * Query the eSewa transaction-status API. GETs the status endpoint with
+ * `product_code`, `total_amount` and `transaction_uuid` as query params and
+ * returns the parsed JSON. Inject a custom `fetch` for tests or non-global
+ * runtimes.
+ *
+ * @example
+ * const status = await checkStatus(
+ *   { product_code: "EPAYTEST", total_amount: 100, transaction_uuid: "11-201" },
+ *   { env: "test" },
+ * );
+ */
+declare function checkStatus(params: StatusParams, opts?: {
+    env?: EsewaEnv;
+    fetch?: typeof fetch;
+}): Promise<unknown>;
+
+export { type BuildFormInput, ESEWA_FORM_URLS, ESEWA_SIGNED_FIELD_NAMES, ESEWA_STATUS_URLS, ESEWA_TEST_PRODUCT_CODE, ESEWA_TEST_SECRET, type EsewaEnv, type EsewaForm, type SignFields, type StatusParams, type VerifyResult, buildForm, checkStatus, signPayment, verifyResponse };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @lacspace/esewa
+ *
+ * eSewa ePay v2 (Nepal) — the correct, tiny way to integrate Nepal's most-used
+ * payment gateway. Handles the three things every integration re-implements:
+ *
+ *   1. **Signing** — the HMAC-SHA256 signature eSewa requires on the checkout
+ *      form, computed over `total_amount,transaction_uuid,product_code` in the
+ *      exact order of `signed_field_names`, base64-encoded.
+ *   2. **Form building** — a ready-to-POST `{ action, method, fields }` object
+ *      with every field eSewa expects, including a valid `signature`.
+ *   3. **Verification & status** — decode and verify the signed base64 `data`
+ *      payload eSewa returns on success (timing-safe), and query the
+ *      transaction-status API.
+ *
+ * Built on Web Crypto (`globalThis.crypto.subtle`) — never hand-rolled
+ * cryptography. Isomorphic: Node 20+, edge runtimes and browsers. Zero deps.
+ */
+type EsewaEnv = "test" | "prod";
+/** eSewa checkout form endpoints (the URL you POST the form to). */
+declare const ESEWA_FORM_URLS: Record<EsewaEnv, string>;
+/** eSewa transaction-status API endpoints. */
+declare const ESEWA_STATUS_URLS: Record<EsewaEnv, string>;
+/** eSewa-published sandbox secret key (test environment only). */
+declare const ESEWA_TEST_SECRET = "8gBm/:&EnhH.1/q@K@";
+/** eSewa-published sandbox merchant/product code (test environment only). */
+declare const ESEWA_TEST_PRODUCT_CODE = "EPAYTEST";
+/** The fields eSewa signs, in the required order. */
+declare const ESEWA_SIGNED_FIELD_NAMES = "total_amount,transaction_uuid,product_code";
+interface SignFields {
+    total_amount: string | number;
+    transaction_uuid: string;
+    product_code: string;
+}
+/**
+ * Compute the eSewa signature for the required signed fields. The message is
+ * `total_amount=<v>,transaction_uuid=<v>,product_code=<v>` (the exact order of
+ * `signed_field_names`), HMAC-SHA256'd with the merchant secret and returned as
+ * standard base64.
+ *
+ * @example
+ * const sig = await signPayment(
+ *   { total_amount: 100, transaction_uuid: "11-201", product_code: "EPAYTEST" },
+ *   ESEWA_TEST_SECRET,
+ * );
+ */
+declare function signPayment(fields: SignFields, secret: string): Promise<string>;
+interface BuildFormInput {
+    /** Base product amount. */
+    amount: number;
+    /** Tax amount. Default 0. */
+    taxAmount?: number;
+    /** Grand total. Defaults to amount + tax + service + delivery. */
+    totalAmount?: number;
+    /** Unique transaction id you generate. */
+    transactionUuid: string;
+    /** Merchant product code (e.g. "EPAYTEST" in test). */
+    productCode: string;
+    /** Where eSewa redirects on success. */
+    successUrl: string;
+    /** Where eSewa redirects on failure. */
+    failureUrl: string;
+    /** Product service charge. Default 0. */
+    productServiceCharge?: number;
+    /** Product delivery charge. Default 0. */
+    productDeliveryCharge?: number;
+}
+interface EsewaForm {
+    /** URL to POST the form to. */
+    action: string;
+    method: "POST";
+    /** All fields eSewa expects, as strings ready for form inputs. */
+    fields: Record<string, string>;
+}
+/**
+ * Build a ready-to-POST eSewa checkout form: `{ action, method, fields }`. The
+ * `total_amount` defaults to `amount + taxAmount + serviceCharge + deliveryCharge`,
+ * and a valid `signature` is computed for you.
+ *
+ * @example
+ * const form = await buildForm(
+ *   { amount: 100, transactionUuid: "11-201", productCode: ESEWA_TEST_PRODUCT_CODE,
+ *     successUrl: "https://me/ok", failureUrl: "https://me/fail" },
+ *   { secret: ESEWA_TEST_SECRET, env: "test" },
+ * );
+ * // render form.fields as hidden inputs and auto-submit to form.action
+ */
+declare function buildForm(input: BuildFormInput, opts: {
+    secret: string;
+    env?: EsewaEnv;
+}): Promise<EsewaForm>;
+interface VerifyResult {
+    valid: boolean;
+    /** The decoded response fields. */
+    data: Record<string, unknown>;
+}
+/**
+ * Verify the signed base64 `data` payload eSewa appends to the success redirect.
+ * Decodes the JSON, recomputes the signature over the fields named in its own
+ * `signed_field_names`, and compares (timing-safe) against its `signature`.
+ * Never throws — returns `{ valid, data }`.
+ *
+ * @example
+ * const { valid, data } = await verifyResponse(url.searchParams.get("data")!, secret);
+ * if (valid && data.status === "COMPLETE") fulfilOrder(data.transaction_uuid);
+ */
+declare function verifyResponse(base64Data: string, secret: string): Promise<VerifyResult>;
+interface StatusParams {
+    product_code: string;
+    total_amount: string | number;
+    transaction_uuid: string;
+}
+/**
+ * Query the eSewa transaction-status API. GETs the status endpoint with
+ * `product_code`, `total_amount` and `transaction_uuid` as query params and
+ * returns the parsed JSON. Inject a custom `fetch` for tests or non-global
+ * runtimes.
+ *
+ * @example
+ * const status = await checkStatus(
+ *   { product_code: "EPAYTEST", total_amount: 100, transaction_uuid: "11-201" },
+ *   { env: "test" },
+ * );
+ */
+declare function checkStatus(params: StatusParams, opts?: {
+    env?: EsewaEnv;
+    fetch?: typeof fetch;
+}): Promise<unknown>;
+
+export { type BuildFormInput, ESEWA_FORM_URLS, ESEWA_SIGNED_FIELD_NAMES, ESEWA_STATUS_URLS, ESEWA_TEST_PRODUCT_CODE, ESEWA_TEST_SECRET, type EsewaEnv, type EsewaForm, type SignFields, type StatusParams, type VerifyResult, buildForm, checkStatus, signPayment, verifyResponse };

package/dist/index.js

@@ -0,0 +1,127 @@
+// src/index.ts
+var ESEWA_FORM_URLS = {
+  test: "https://rc-epay.esewa.com.np/api/epay/main/v2/form",
+  prod: "https://epay.esewa.com.np/api/epay/main/v2/form"
+};
+var ESEWA_STATUS_URLS = {
+  test: "https://rc.esewa.com.np/api/epay/transaction/status/",
+  prod: "https://epay.esewa.com.np/api/epay/transaction/status/"
+};
+var ESEWA_TEST_SECRET = "8gBm/:&EnhH.1/q@K@";
+var ESEWA_TEST_PRODUCT_CODE = "EPAYTEST";
+var ESEWA_SIGNED_FIELD_NAMES = "total_amount,transaction_uuid,product_code";
+var enc = new TextEncoder();
+var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function toBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += B64[b0 >> 2];
+    out += B64[(b0 & 3) << 4 | b1 >> 4];
+    out += i + 1 < bytes.length ? B64[(b1 & 15) << 2 | b2 >> 6] : "=";
+    out += i + 2 < bytes.length ? B64[b2 & 63] : "=";
+  }
+  return out;
+}
+function fromBase64(b64) {
+  const clean = b64.replace(/[^A-Za-z0-9+/]/g, "");
+  const len = Math.floor(clean.length * 3 / 4);
+  const bytes = new Uint8Array(len);
+  let p = 0;
+  for (let i = 0; i < clean.length; i += 4) {
+    const c0 = B64.indexOf(clean[i]);
+    const c1 = B64.indexOf(clean[i + 1]);
+    const c2 = i + 2 < clean.length ? B64.indexOf(clean[i + 2]) : -1;
+    const c3 = i + 3 < clean.length ? B64.indexOf(clean[i + 3]) : -1;
+    if (p < len) bytes[p++] = c0 << 2 | c1 >> 4;
+    if (c2 >= 0 && p < len) bytes[p++] = (c1 & 15) << 4 | c2 >> 2;
+    if (c3 >= 0 && p < len) bytes[p++] = (c2 & 3) << 6 | c3;
+  }
+  return bytes;
+}
+async function hmacSha256Base64(secret, message) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("@lacspace/esewa: Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime.");
+  const key = await subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await subtle.sign("HMAC", key, enc.encode(message));
+  return toBase64(new Uint8Array(sig));
+}
+function timingSafeEqual(a, b) {
+  const ab = enc.encode(a);
+  const bb = enc.encode(b);
+  let diff = ab.length ^ bb.length;
+  const n = Math.max(ab.length, bb.length);
+  for (let i = 0; i < n; i++) diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);
+  return diff === 0;
+}
+async function signPayment(fields, secret) {
+  const message = `total_amount=${fields.total_amount},transaction_uuid=${fields.transaction_uuid},product_code=${fields.product_code}`;
+  return hmacSha256Base64(secret, message);
+}
+async function buildForm(input, opts) {
+  const tax = input.taxAmount ?? 0;
+  const service = input.productServiceCharge ?? 0;
+  const delivery = input.productDeliveryCharge ?? 0;
+  const total = input.totalAmount ?? input.amount + tax + service + delivery;
+  const signature = await signPayment(
+    {
+      total_amount: total,
+      transaction_uuid: input.transactionUuid,
+      product_code: input.productCode
+    },
+    opts.secret
+  );
+  const fields = {
+    amount: String(input.amount),
+    tax_amount: String(tax),
+    total_amount: String(total),
+    transaction_uuid: input.transactionUuid,
+    product_code: input.productCode,
+    product_service_charge: String(service),
+    product_delivery_charge: String(delivery),
+    success_url: input.successUrl,
+    failure_url: input.failureUrl,
+    signed_field_names: ESEWA_SIGNED_FIELD_NAMES,
+    signature
+  };
+  return { action: ESEWA_FORM_URLS[opts.env ?? "test"], method: "POST", fields };
+}
+async function verifyResponse(base64Data, secret) {
+  let data;
+  try {
+    data = JSON.parse(new TextDecoder().decode(fromBase64(base64Data)));
+  } catch {
+    return { valid: false, data: {} };
+  }
+  const names = typeof data.signed_field_names === "string" ? data.signed_field_names : "";
+  const provided = typeof data.signature === "string" ? data.signature : "";
+  if (!names || !provided) return { valid: false, data };
+  const message = names.split(",").map((name) => `${name}=${data[name] ?? ""}`).join(",");
+  const expected = await hmacSha256Base64(secret, message);
+  return { valid: timingSafeEqual(expected, provided), data };
+}
+async function checkStatus(params, opts) {
+  const base = ESEWA_STATUS_URLS[opts?.env ?? "test"];
+  const qs = new URLSearchParams({
+    product_code: params.product_code,
+    total_amount: String(params.total_amount),
+    transaction_uuid: params.transaction_uuid
+  }).toString();
+  const url = `${base}?${qs}`;
+  const doFetch = opts?.fetch ?? globalThis.fetch;
+  if (!doFetch) throw new Error("@lacspace/esewa: global fetch is unavailable; pass opts.fetch.");
+  const res = await doFetch(url, { method: "GET" });
+  return res.json();
+}
+
+export { ESEWA_FORM_URLS, ESEWA_SIGNED_FIELD_NAMES, ESEWA_STATUS_URLS, ESEWA_TEST_PRODUCT_CODE, ESEWA_TEST_SECRET, buildForm, checkStatus, signPayment, verifyResponse };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/esewa\n *\n * eSewa ePay v2 (Nepal) — the correct, tiny way to integrate Nepal's most-used\n * payment gateway. Handles the three things every integration re-implements:\n *\n *   1. **Signing** — the HMAC-SHA256 signature eSewa requires on the checkout\n *      form, computed over `total_amount,transaction_uuid,product_code` in the\n *      exact order of `signed_field_names`, base64-encoded.\n *   2. **Form building** — a ready-to-POST `{ action, method, fields }` object\n *      with every field eSewa expects, including a valid `signature`.\n *   3. **Verification & status** — decode and verify the signed base64 `data`\n *      payload eSewa returns on success (timing-safe), and query the\n *      transaction-status API.\n *\n * Built on Web Crypto (`globalThis.crypto.subtle`) — never hand-rolled\n * cryptography. Isomorphic: Node 20+, edge runtimes and browsers. Zero deps.\n */\n\n/* ------------------------------------------------------------------ *\n * Endpoints & test credentials\n * ------------------------------------------------------------------ */\n\nexport type EsewaEnv = \"test\" | \"prod\";\n\n/** eSewa checkout form endpoints (the URL you POST the form to). */\nexport const ESEWA_FORM_URLS: Record<EsewaEnv, string> = {\n  test: \"https://rc-epay.esewa.com.np/api/epay/main/v2/form\",\n  prod: \"https://epay.esewa.com.np/api/epay/main/v2/form\",\n};\n\n/** eSewa transaction-status API endpoints. */\nexport const ESEWA_STATUS_URLS: Record<EsewaEnv, string> = {\n  test: \"https://rc.esewa.com.np/api/epay/transaction/status/\",\n  prod: \"https://epay.esewa.com.np/api/epay/transaction/status/\",\n};\n\n/** eSewa-published sandbox secret key (test environment only). */\nexport const ESEWA_TEST_SECRET = \"8gBm/:&EnhH.1/q@K@\";\n\n/** eSewa-published sandbox merchant/product code (test environment only). */\nexport const ESEWA_TEST_PRODUCT_CODE = \"EPAYTEST\";\n\n/** The fields eSewa signs, in the required order. */\nexport const ESEWA_SIGNED_FIELD_NAMES = \"total_amount,transaction_uuid,product_code\";\n\n/* ------------------------------------------------------------------ *\n * Web Crypto + base64 helpers (isomorphic, zero-dependency)\n * ------------------------------------------------------------------ */\n\nconst enc = new TextEncoder();\nconst B64 = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/\";\n\n/** Standard base64 (NOT url-safe) encode of raw bytes. */\nfunction toBase64(bytes: Uint8Array): string {\n  let out = \"\";\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i]!;\n    const b1 = i + 1 < bytes.length ? bytes[i + 1]! : 0;\n    const b2 = i + 2 < bytes.length ? bytes[i + 2]! : 0;\n    out += B64[b0 >> 2];\n    out += B64[((b0 & 3) << 4) | (b1 >> 4)];\n    out += i + 1 < bytes.length ? B64[((b1 & 15) << 2) | (b2 >> 6)] : \"=\";\n    out += i + 2 < bytes.length ? B64[b2 & 63] : \"=\";\n  }\n  return out;\n}\n\n/** Standard base64 decode to raw bytes. */\nfunction fromBase64(b64: string): Uint8Array {\n  const clean = b64.replace(/[^A-Za-z0-9+/]/g, \"\");\n  const len = Math.floor((clean.length * 3) / 4);\n  const bytes = new Uint8Array(len);\n  let p = 0;\n  for (let i = 0; i < clean.length; i += 4) {\n    const c0 = B64.indexOf(clean[i]!);\n    const c1 = B64.indexOf(clean[i + 1]!);\n    const c2 = i + 2 < clean.length ? B64.indexOf(clean[i + 2]!) : -1;\n    const c3 = i + 3 < clean.length ? B64.indexOf(clean[i + 3]!) : -1;\n    if (p < len) bytes[p++] = (c0 << 2) | (c1 >> 4);\n    if (c2 >= 0 && p < len) bytes[p++] = ((c1 & 15) << 4) | (c2 >> 2);\n    if (c3 >= 0 && p < len) bytes[p++] = ((c2 & 3) << 6) | c3;\n  }\n  return bytes;\n}\n\n/** HMAC-SHA256 over `message` with `secret`, returned as standard base64. */\nasync function hmacSha256Base64(secret: string, message: string): Promise<string> {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) throw new Error(\"@lacspace/esewa: Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime.\");\n  const key = await subtle.importKey(\n    \"raw\",\n    enc.encode(secret),\n    { name: \"HMAC\", hash: \"SHA-256\" },\n    false,\n    [\"sign\"],\n  );\n  const sig = await subtle.sign(\"HMAC\", key, enc.encode(message));\n  return toBase64(new Uint8Array(sig));\n}\n\n/** Constant-time comparison of two strings (avoids signature-timing leaks). */\nfunction timingSafeEqual(a: string, b: string): boolean {\n  const ab = enc.encode(a);\n  const bb = enc.encode(b);\n  // Compare a fixed number of bytes; length mismatch still fails.\n  let diff = ab.length ^ bb.length;\n  const n = Math.max(ab.length, bb.length);\n  for (let i = 0; i < n; i++) diff |= (ab[i] ?? 0) ^ (bb[i] ?? 0);\n  return diff === 0;\n}\n\n/* ------------------------------------------------------------------ *\n * Signing\n * ------------------------------------------------------------------ */\n\nexport interface SignFields {\n  total_amount: string | number;\n  transaction_uuid: string;\n  product_code: string;\n}\n\n/**\n * Compute the eSewa signature for the required signed fields. The message is\n * `total_amount=<v>,transaction_uuid=<v>,product_code=<v>` (the exact order of\n * `signed_field_names`), HMAC-SHA256'd with the merchant secret and returned as\n * standard base64.\n *\n * @example\n * const sig = await signPayment(\n *   { total_amount: 100, transaction_uuid: \"11-201\", product_code: \"EPAYTEST\" },\n *   ESEWA_TEST_SECRET,\n * );\n */\nexport async function signPayment(fields: SignFields, secret: string): Promise<string> {\n  const message =\n    `total_amount=${fields.total_amount},` +\n    `transaction_uuid=${fields.transaction_uuid},` +\n    `product_code=${fields.product_code}`;\n  return hmacSha256Base64(secret, message);\n}\n\n/* ------------------------------------------------------------------ *\n * Form building\n * ------------------------------------------------------------------ */\n\nexport interface BuildFormInput {\n  /** Base product amount. */\n  amount: number;\n  /** Tax amount. Default 0. */\n  taxAmount?: number;\n  /** Grand total. Defaults to amount + tax + service + delivery. */\n  totalAmount?: number;\n  /** Unique transaction id you generate. */\n  transactionUuid: string;\n  /** Merchant product code (e.g. \"EPAYTEST\" in test). */\n  productCode: string;\n  /** Where eSewa redirects on success. */\n  successUrl: string;\n  /** Where eSewa redirects on failure. */\n  failureUrl: string;\n  /** Product service charge. Default 0. */\n  productServiceCharge?: number;\n  /** Product delivery charge. Default 0. */\n  productDeliveryCharge?: number;\n}\n\nexport interface EsewaForm {\n  /** URL to POST the form to. */\n  action: string;\n  method: \"POST\";\n  /** All fields eSewa expects, as strings ready for form inputs. */\n  fields: Record<string, string>;\n}\n\n/**\n * Build a ready-to-POST eSewa checkout form: `{ action, method, fields }`. The\n * `total_amount` defaults to `amount + taxAmount + serviceCharge + deliveryCharge`,\n * and a valid `signature` is computed for you.\n *\n * @example\n * const form = await buildForm(\n *   { amount: 100, transactionUuid: \"11-201\", productCode: ESEWA_TEST_PRODUCT_CODE,\n *     successUrl: \"https://me/ok\", failureUrl: \"https://me/fail\" },\n *   { secret: ESEWA_TEST_SECRET, env: \"test\" },\n * );\n * // render form.fields as hidden inputs and auto-submit to form.action\n */\nexport async function buildForm(\n  input: BuildFormInput,\n  opts: { secret: string; env?: EsewaEnv },\n): Promise<EsewaForm> {\n  const tax = input.taxAmount ?? 0;\n  const service = input.productServiceCharge ?? 0;\n  const delivery = input.productDeliveryCharge ?? 0;\n  const total = input.totalAmount ?? input.amount + tax + service + delivery;\n\n  const signature = await signPayment(\n    {\n      total_amount: total,\n      transaction_uuid: input.transactionUuid,\n      product_code: input.productCode,\n    },\n    opts.secret,\n  );\n\n  const fields: Record<string, string> = {\n    amount: String(input.amount),\n    tax_amount: String(tax),\n    total_amount: String(total),\n    transaction_uuid: input.transactionUuid,\n    product_code: input.productCode,\n    product_service_charge: String(service),\n    product_delivery_charge: String(delivery),\n    success_url: input.successUrl,\n    failure_url: input.failureUrl,\n    signed_field_names: ESEWA_SIGNED_FIELD_NAMES,\n    signature,\n  };\n\n  return { action: ESEWA_FORM_URLS[opts.env ?? \"test\"], method: \"POST\", fields };\n}\n\n/* ------------------------------------------------------------------ *\n * Response verification\n * ------------------------------------------------------------------ */\n\nexport interface VerifyResult {\n  valid: boolean;\n  /** The decoded response fields. */\n  data: Record<string, unknown>;\n}\n\n/**\n * Verify the signed base64 `data` payload eSewa appends to the success redirect.\n * Decodes the JSON, recomputes the signature over the fields named in its own\n * `signed_field_names`, and compares (timing-safe) against its `signature`.\n * Never throws — returns `{ valid, data }`.\n *\n * @example\n * const { valid, data } = await verifyResponse(url.searchParams.get(\"data\")!, secret);\n * if (valid && data.status === \"COMPLETE\") fulfilOrder(data.transaction_uuid);\n */\nexport async function verifyResponse(base64Data: string, secret: string): Promise<VerifyResult> {\n  let data: Record<string, unknown>;\n  try {\n    data = JSON.parse(new TextDecoder().decode(fromBase64(base64Data))) as Record<string, unknown>;\n  } catch {\n    return { valid: false, data: {} };\n  }\n\n  const names = typeof data.signed_field_names === \"string\" ? data.signed_field_names : \"\";\n  const provided = typeof data.signature === \"string\" ? data.signature : \"\";\n  if (!names || !provided) return { valid: false, data };\n\n  const message = names\n    .split(\",\")\n    .map((name) => `${name}=${data[name] ?? \"\"}`)\n    .join(\",\");\n  const expected = await hmacSha256Base64(secret, message);\n\n  return { valid: timingSafeEqual(expected, provided), data };\n}\n\n/* ------------------------------------------------------------------ *\n * Transaction status\n * ------------------------------------------------------------------ */\n\nexport interface StatusParams {\n  product_code: string;\n  total_amount: string | number;\n  transaction_uuid: string;\n}\n\n/**\n * Query the eSewa transaction-status API. GETs the status endpoint with\n * `product_code`, `total_amount` and `transaction_uuid` as query params and\n * returns the parsed JSON. Inject a custom `fetch` for tests or non-global\n * runtimes.\n *\n * @example\n * const status = await checkStatus(\n *   { product_code: \"EPAYTEST\", total_amount: 100, transaction_uuid: \"11-201\" },\n *   { env: \"test\" },\n * );\n */\nexport async function checkStatus(\n  params: StatusParams,\n  opts?: { env?: EsewaEnv; fetch?: typeof fetch },\n): Promise<unknown> {\n  const base = ESEWA_STATUS_URLS[opts?.env ?? \"test\"];\n  const qs = new URLSearchParams({\n    product_code: params.product_code,\n    total_amount: String(params.total_amount),\n    transaction_uuid: params.transaction_uuid,\n  }).toString();\n  const url = `${base}?${qs}`;\n\n  const doFetch = opts?.fetch ?? globalThis.fetch;\n  if (!doFetch) throw new Error(\"@lacspace/esewa: global fetch is unavailable; pass opts.fetch.\");\n  const res = await doFetch(url, { method: \"GET\" });\n  return res.json();\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/esewa",
+  "version": "1.0.0",
+  "description": "eSewa ePay v2 (Nepal) payment gateway toolkit over Web Crypto — HMAC-SHA256 signing, form building, response verification and transaction status checks. Zero-dependency, isomorphic (Node, edge, browser).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nepal",
+    "payment",
+    "payment-gateway",
+    "esewa",
+    "epay",
+    "epay-v2",
+    "hmac-sha256",
+    "web-crypto",
+    "khalti",
+    "edge",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/esewa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "esewa"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}