@lacspace/khalti 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,107 @@
+<div align="center">
+
+# @lacspace/khalti
+
+**Khalti KPG-2 (ePayment API v2, Nepal) — initiate payments, look up status, typed errors and `Key` auth over `fetch`.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/khalti?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/khalti)
+[![install size](https://packagephobia.com/badge?p=@lacspace/khalti)](https://packagephobia.com/result?p=@lacspace/khalti)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/khalti?label=minzip)](https://bundlephobia.com/package/@lacspace/khalti)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/khalti)
+[![license](https://img.shields.io/npm/l/@lacspace/khalti?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> A tiny, fully-typed client for **Khalti**'s KPG-2 (ePayment API v2) — Nepal's leading digital wallet. Two calls: `initiate()` to start a payment and get a redirect URL, and `lookup()` to verify the real status by `pidx`. Amounts in **paisa**, `Authorization: Key` auth, and Khalti's error bodies surfaced as a typed `KhaltiError`. Zero dependencies, isomorphic, injectable `fetch`.
+
+- 🚀 **`initiate()`** — create a payment, get back `pidx` + `payment_url` to redirect to
+- 🔎 **`lookup()`** — the source of truth: verify status by `pidx` after the customer returns
+- 🧨 **Typed errors** — non-2xx responses throw `KhaltiError` with `status` + parsed `detail`
+- 🔑 Server-side `Authorization: Key <secretKey>` · amounts in paisa (integer)
+- ⚡ Isomorphic — Node 20+, edge runtimes & browsers via global `fetch` (injectable) · 📦 ESM + CJS · zero deps
+
+## Install
+
+```bash
+npm install @lacspace/khalti      # or pnpm add / yarn add / bun add
+```
+
+## Initiate a payment
+
+```ts
+import { initiate } from "@lacspace/khalti";
+
+const { payment_url, pidx } = await initiate(
+  {
+    return_url: "https://myshop.np/khalti/return",
+    website_url: "https://myshop.np",
+    amount: 1000, // NPR 10, in paisa
+    purchase_order_id: "order-42",
+    purchase_order_name: "Test order",
+    customer_info: { name: "Ram", email: "ram@example.com", phone: "9800000000" },
+  },
+  { secretKey: process.env.KHALTI_SECRET!, env: "test" },
+);
+
+// redirect the customer to payment_url; keep pidx to verify later.
+```
+
+## Verify with lookup (never trust the callback alone)
+
+```ts
+import { lookup } from "@lacspace/khalti";
+
+const r = await lookup(pidx, { secretKey: process.env.KHALTI_SECRET!, env: "test" });
+if (r.status === "Completed") {
+  fulfilOrder(r.transaction_id);
+}
+// status: "Completed" | "Pending" | "Initiated" | "Refunded" | "Expired" | "User canceled" | "Partially Refunded"
+```
+
+## Handle errors
+
+```ts
+import { initiate, KhaltiError } from "@lacspace/khalti";
+
+try {
+  await initiate(payload, { secretKey });
+} catch (e) {
+  if (e instanceof KhaltiError) {
+    console.error(e.status, e.detail); // e.g. 400, "Amount should be greater than Rs. 1."
+  }
+}
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `initiate(payload, { secretKey, env?, fetch? })` | POST `/epayment/initiate/` → `{ pidx, payment_url, expires_at, expires_in }` |
+| `lookup(pidx, { secretKey, env?, fetch? })` | POST `/epayment/lookup/` → `{ pidx, total_amount, status, transaction_id, fee, refunded }` |
+| `KhaltiError` | thrown on non-2xx — `status` + parsed `detail` |
+| `KhaltiStatus` | union of Khalti payment statuses |
+| `KHALTI_BASE_URLS` | `{ test, prod }` base-URL map |
+
+`env` is `"test"` (default, `a.khalti.com`) or `"prod"` (`khalti.com`). All amounts are in **paisa** (NPR 10 → `1000`).
+
+## 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/khalti` 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,57 @@
+'use strict';
+
+// src/index.ts
+var KHALTI_BASE_URLS = {
+  test: "https://a.khalti.com/api/v2",
+  prod: "https://khalti.com/api/v2"
+};
+var KhaltiError = class _KhaltiError extends Error {
+  constructor(message, status, detail) {
+    super(message);
+    this.name = "KhaltiError";
+    this.status = status;
+    this.detail = detail;
+    Object.setPrototypeOf(this, _KhaltiError.prototype);
+  }
+};
+async function post(path, body, opts) {
+  const base = KHALTI_BASE_URLS[opts.env ?? "test"];
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  if (!doFetch) throw new Error("@lacspace/khalti: global fetch is unavailable; pass opts.fetch.");
+  const res = await doFetch(`${base}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Key ${opts.secretKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  let parsed = void 0;
+  const text = await res.text();
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!res.ok) {
+    const detail = parsed && typeof parsed === "object" && "detail" in parsed ? parsed.detail : parsed;
+    const message = typeof detail === "string" ? detail : `Khalti request failed with status ${res.status}`;
+    throw new KhaltiError(message, res.status, detail);
+  }
+  return parsed;
+}
+async function initiate(payload, opts) {
+  return post("/epayment/initiate/", payload, opts);
+}
+async function lookup(pidx, opts) {
+  return post("/epayment/lookup/", { pidx }, opts);
+}
+
+exports.KHALTI_BASE_URLS = KHALTI_BASE_URLS;
+exports.KhaltiError = KhaltiError;
+exports.initiate = initiate;
+exports.lookup = lookup;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AA0BO,IAAM,gBAAA,GAA8C;AAAA,EACzD,IAAA,EAAM,6BAAA;AAAA,EACN,IAAA,EAAM;AACR;AAqEO,IAAM,WAAA,GAAN,MAAM,YAAA,SAAoB,KAAA,CAAM;AAAA,EAMrC,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,MAAA,EAAiB;AAC5D,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAEd,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,YAAA,CAAY,SAAS,CAAA;AAAA,EACnD;AACF;AAMA,eAAe,IAAA,CAAQ,IAAA,EAAc,IAAA,EAAe,IAAA,EAAoC;AACtF,EAAA,MAAM,IAAA,GAAO,gBAAA,CAAiB,IAAA,CAAK,GAAA,IAAO,MAAM,CAAA;AAChD,EAAA,MAAM,OAAA,GAAU,IAAA,CAAK,KAAA,IAAS,UAAA,CAAW,KAAA;AACzC,EAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,MAAM,iEAAiE,CAAA;AAE/F,EAAA,MAAM,MAAM,MAAM,OAAA,CAAQ,GAAG,IAAI,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI;AAAA,IAC1C,MAAA,EAAQ,MAAA;AAAA,IACR,OAAA,EAAS;AAAA,MACP,aAAA,EAAe,CAAA,IAAA,EAAO,IAAA,CAAK,SAAS,CAAA,CAAA;AAAA,MACpC,cAAA,EAAgB;AAAA,KAClB;AAAA,IACA,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,IAAI;AAAA,GAC1B,CAAA;AAED,EAAA,IAAI,MAAA,GAAkB,MAAA;AACtB,EAAA,MAAM,IAAA,GAAO,MAAM,GAAA,CAAI,IAAA,EAAK;AAC5B,EAAA,IAAI,IAAA,EAAM;AACR,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,IAC1B,CAAA,CAAA,MAAQ;AACN,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAEA,EAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,IAAA,MAAM,MAAA,GACJ,UAAU,OAAO,MAAA,KAAW,YAAY,QAAA,IAAa,MAAA,GAChD,OAAmC,MAAA,GACpC,MAAA;AACN,IAAA,MAAM,UACJ,OAAO,MAAA,KAAW,WAAW,MAAA,GAAS,CAAA,kCAAA,EAAqC,IAAI,MAAM,CAAA,CAAA;AACvF,IAAA,MAAM,IAAI,WAAA,CAAY,OAAA,EAAS,GAAA,CAAI,QAAQ,MAAM,CAAA;AAAA,EACnD;AAEA,EAAA,OAAO,MAAA;AACT;AAsBA,eAAsB,QAAA,CACpB,SACA,IAAA,EAC2B;AAC3B,EAAA,OAAO,IAAA,CAAuB,qBAAA,EAAuB,OAAA,EAAS,IAAI,CAAA;AACpE;AAUA,eAAsB,MAAA,CAAO,MAAc,IAAA,EAAiD;AAC1F,EAAA,OAAO,IAAA,CAAqB,mBAAA,EAAqB,EAAE,IAAA,IAAQ,IAAI,CAAA;AACjE","file":"index.cjs","sourcesContent":["/**\n * @lacspace/khalti\n *\n * Khalti KPG-2 (ePayment API v2, Nepal) — a tiny, typed client for the two calls\n * every integration needs:\n *\n *   1. **initiate** — create a payment and get back a `payment_url` to redirect\n *      the customer to, plus a `pidx` to track it.\n *   2. **lookup**   — the source of truth: check a payment's real status by\n *      `pidx` after the customer returns (never trust the callback alone).\n *\n * Amounts are always in **paisa** (integer): NPR 10 → `1000`. Authentication is\n * a server-side `Authorization: Key <secretKey>` header. Non-2xx responses throw\n * a {@link KhaltiError} carrying Khalti's parsed `detail`.\n *\n * Isomorphic: Node 20+, edge runtimes and browsers via global `fetch`\n * (injectable). Zero dependencies.\n */\n\n/* ------------------------------------------------------------------ *\n * Endpoints & types\n * ------------------------------------------------------------------ */\n\nexport type KhaltiEnv = \"test\" | \"prod\";\n\n/** Khalti API base URLs. */\nexport const KHALTI_BASE_URLS: Record<KhaltiEnv, string> = {\n  test: \"https://a.khalti.com/api/v2\",\n  prod: \"https://khalti.com/api/v2\",\n};\n\n/** Possible values of a Khalti payment `status`. */\nexport type KhaltiStatus =\n  | \"Completed\"\n  | \"Pending\"\n  | \"Initiated\"\n  | \"Refunded\"\n  | \"Expired\"\n  | \"User canceled\"\n  | \"Partially Refunded\";\n\nexport interface KhaltiCustomerInfo {\n  name?: string;\n  email?: string;\n  phone?: string;\n}\n\nexport interface KhaltiAmountBreakdown {\n  label: string;\n  /** In paisa. */\n  amount: number;\n}\n\nexport interface InitiatePayload {\n  /** Where Khalti redirects the customer after payment. */\n  return_url: string;\n  /** Your site's base URL. */\n  website_url: string;\n  /** Total payable amount in **paisa** (integer). */\n  amount: number;\n  /** Your unique order id. */\n  purchase_order_id: string;\n  /** Human-readable order name. */\n  purchase_order_name: string;\n  customer_info?: KhaltiCustomerInfo;\n  amount_breakdown?: KhaltiAmountBreakdown[];\n  product_details?: unknown[];\n}\n\nexport interface InitiateResponse {\n  pidx: string;\n  payment_url: string;\n  expires_at: string;\n  expires_in: number;\n}\n\nexport interface LookupResponse {\n  pidx: string;\n  /** In paisa. */\n  total_amount: number;\n  status: KhaltiStatus | string;\n  transaction_id: string | null;\n  /** In paisa. */\n  fee: number;\n  refunded: boolean;\n}\n\nexport interface KhaltiClientOpts {\n  secretKey: string;\n  env?: KhaltiEnv;\n  fetch?: typeof fetch;\n}\n\n/* ------------------------------------------------------------------ *\n * Errors\n * ------------------------------------------------------------------ */\n\n/** Thrown on any non-2xx Khalti response, carrying the parsed error body. */\nexport class KhaltiError extends Error {\n  /** HTTP status code. */\n  readonly status: number;\n  /** Khalti's `detail` field (or the raw error payload). */\n  readonly detail: unknown;\n\n  constructor(message: string, status: number, detail: unknown) {\n    super(message);\n    this.name = \"KhaltiError\";\n    this.status = status;\n    this.detail = detail;\n    // Restore prototype chain for instanceof across transpile targets.\n    Object.setPrototypeOf(this, KhaltiError.prototype);\n  }\n}\n\n/* ------------------------------------------------------------------ *\n * Internal request helper\n * ------------------------------------------------------------------ */\n\nasync function post<T>(path: string, body: unknown, opts: KhaltiClientOpts): Promise<T> {\n  const base = KHALTI_BASE_URLS[opts.env ?? \"test\"];\n  const doFetch = opts.fetch ?? globalThis.fetch;\n  if (!doFetch) throw new Error(\"@lacspace/khalti: global fetch is unavailable; pass opts.fetch.\");\n\n  const res = await doFetch(`${base}${path}`, {\n    method: \"POST\",\n    headers: {\n      Authorization: `Key ${opts.secretKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify(body),\n  });\n\n  let parsed: unknown = undefined;\n  const text = await res.text();\n  if (text) {\n    try {\n      parsed = JSON.parse(text);\n    } catch {\n      parsed = text;\n    }\n  }\n\n  if (!res.ok) {\n    const detail =\n      parsed && typeof parsed === \"object\" && \"detail\" in (parsed as Record<string, unknown>)\n        ? (parsed as Record<string, unknown>).detail\n        : parsed;\n    const message =\n      typeof detail === \"string\" ? detail : `Khalti request failed with status ${res.status}`;\n    throw new KhaltiError(message, res.status, detail);\n  }\n\n  return parsed as T;\n}\n\n/* ------------------------------------------------------------------ *\n * Public API\n * ------------------------------------------------------------------ */\n\n/**\n * Initiate a Khalti payment. POSTs to `/epayment/initiate/` and returns the\n * `pidx` and `payment_url` to redirect the customer to.\n *\n * @example\n * const { payment_url, pidx } = await initiate(\n *   {\n *     return_url: \"https://myshop.np/khalti/return\",\n *     website_url: \"https://myshop.np\",\n *     amount: 1000, // NPR 10, in paisa\n *     purchase_order_id: \"order-42\",\n *     purchase_order_name: \"Test order\",\n *   },\n *   { secretKey: process.env.KHALTI_SECRET!, env: \"test\" },\n * );\n */\nexport async function initiate(\n  payload: InitiatePayload,\n  opts: KhaltiClientOpts,\n): Promise<InitiateResponse> {\n  return post<InitiateResponse>(\"/epayment/initiate/\", payload, opts);\n}\n\n/**\n * Look up a payment's real status by `pidx` — the authoritative check to run\n * after the customer returns. POSTs `{ pidx }` to `/epayment/lookup/`.\n *\n * @example\n * const r = await lookup(pidx, { secretKey, env: \"test\" });\n * if (r.status === \"Completed\") fulfilOrder();\n */\nexport async function lookup(pidx: string, opts: KhaltiClientOpts): Promise<LookupResponse> {\n  return post<LookupResponse>(\"/epayment/lookup/\", { pidx }, opts);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+/**
+ * @lacspace/khalti
+ *
+ * Khalti KPG-2 (ePayment API v2, Nepal) — a tiny, typed client for the two calls
+ * every integration needs:
+ *
+ *   1. **initiate** — create a payment and get back a `payment_url` to redirect
+ *      the customer to, plus a `pidx` to track it.
+ *   2. **lookup**   — the source of truth: check a payment's real status by
+ *      `pidx` after the customer returns (never trust the callback alone).
+ *
+ * Amounts are always in **paisa** (integer): NPR 10 → `1000`. Authentication is
+ * a server-side `Authorization: Key <secretKey>` header. Non-2xx responses throw
+ * a {@link KhaltiError} carrying Khalti's parsed `detail`.
+ *
+ * Isomorphic: Node 20+, edge runtimes and browsers via global `fetch`
+ * (injectable). Zero dependencies.
+ */
+type KhaltiEnv = "test" | "prod";
+/** Khalti API base URLs. */
+declare const KHALTI_BASE_URLS: Record<KhaltiEnv, string>;
+/** Possible values of a Khalti payment `status`. */
+type KhaltiStatus = "Completed" | "Pending" | "Initiated" | "Refunded" | "Expired" | "User canceled" | "Partially Refunded";
+interface KhaltiCustomerInfo {
+    name?: string;
+    email?: string;
+    phone?: string;
+}
+interface KhaltiAmountBreakdown {
+    label: string;
+    /** In paisa. */
+    amount: number;
+}
+interface InitiatePayload {
+    /** Where Khalti redirects the customer after payment. */
+    return_url: string;
+    /** Your site's base URL. */
+    website_url: string;
+    /** Total payable amount in **paisa** (integer). */
+    amount: number;
+    /** Your unique order id. */
+    purchase_order_id: string;
+    /** Human-readable order name. */
+    purchase_order_name: string;
+    customer_info?: KhaltiCustomerInfo;
+    amount_breakdown?: KhaltiAmountBreakdown[];
+    product_details?: unknown[];
+}
+interface InitiateResponse {
+    pidx: string;
+    payment_url: string;
+    expires_at: string;
+    expires_in: number;
+}
+interface LookupResponse {
+    pidx: string;
+    /** In paisa. */
+    total_amount: number;
+    status: KhaltiStatus | string;
+    transaction_id: string | null;
+    /** In paisa. */
+    fee: number;
+    refunded: boolean;
+}
+interface KhaltiClientOpts {
+    secretKey: string;
+    env?: KhaltiEnv;
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx Khalti response, carrying the parsed error body. */
+declare class KhaltiError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Khalti's `detail` field (or the raw error payload). */
+    readonly detail: unknown;
+    constructor(message: string, status: number, detail: unknown);
+}
+/**
+ * Initiate a Khalti payment. POSTs to `/epayment/initiate/` and returns the
+ * `pidx` and `payment_url` to redirect the customer to.
+ *
+ * @example
+ * const { payment_url, pidx } = await initiate(
+ *   {
+ *     return_url: "https://myshop.np/khalti/return",
+ *     website_url: "https://myshop.np",
+ *     amount: 1000, // NPR 10, in paisa
+ *     purchase_order_id: "order-42",
+ *     purchase_order_name: "Test order",
+ *   },
+ *   { secretKey: process.env.KHALTI_SECRET!, env: "test" },
+ * );
+ */
+declare function initiate(payload: InitiatePayload, opts: KhaltiClientOpts): Promise<InitiateResponse>;
+/**
+ * Look up a payment's real status by `pidx` — the authoritative check to run
+ * after the customer returns. POSTs `{ pidx }` to `/epayment/lookup/`.
+ *
+ * @example
+ * const r = await lookup(pidx, { secretKey, env: "test" });
+ * if (r.status === "Completed") fulfilOrder();
+ */
+declare function lookup(pidx: string, opts: KhaltiClientOpts): Promise<LookupResponse>;
+
+export { type InitiatePayload, type InitiateResponse, KHALTI_BASE_URLS, type KhaltiAmountBreakdown, type KhaltiClientOpts, type KhaltiCustomerInfo, type KhaltiEnv, KhaltiError, type KhaltiStatus, type LookupResponse, initiate, lookup };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @lacspace/khalti
+ *
+ * Khalti KPG-2 (ePayment API v2, Nepal) — a tiny, typed client for the two calls
+ * every integration needs:
+ *
+ *   1. **initiate** — create a payment and get back a `payment_url` to redirect
+ *      the customer to, plus a `pidx` to track it.
+ *   2. **lookup**   — the source of truth: check a payment's real status by
+ *      `pidx` after the customer returns (never trust the callback alone).
+ *
+ * Amounts are always in **paisa** (integer): NPR 10 → `1000`. Authentication is
+ * a server-side `Authorization: Key <secretKey>` header. Non-2xx responses throw
+ * a {@link KhaltiError} carrying Khalti's parsed `detail`.
+ *
+ * Isomorphic: Node 20+, edge runtimes and browsers via global `fetch`
+ * (injectable). Zero dependencies.
+ */
+type KhaltiEnv = "test" | "prod";
+/** Khalti API base URLs. */
+declare const KHALTI_BASE_URLS: Record<KhaltiEnv, string>;
+/** Possible values of a Khalti payment `status`. */
+type KhaltiStatus = "Completed" | "Pending" | "Initiated" | "Refunded" | "Expired" | "User canceled" | "Partially Refunded";
+interface KhaltiCustomerInfo {
+    name?: string;
+    email?: string;
+    phone?: string;
+}
+interface KhaltiAmountBreakdown {
+    label: string;
+    /** In paisa. */
+    amount: number;
+}
+interface InitiatePayload {
+    /** Where Khalti redirects the customer after payment. */
+    return_url: string;
+    /** Your site's base URL. */
+    website_url: string;
+    /** Total payable amount in **paisa** (integer). */
+    amount: number;
+    /** Your unique order id. */
+    purchase_order_id: string;
+    /** Human-readable order name. */
+    purchase_order_name: string;
+    customer_info?: KhaltiCustomerInfo;
+    amount_breakdown?: KhaltiAmountBreakdown[];
+    product_details?: unknown[];
+}
+interface InitiateResponse {
+    pidx: string;
+    payment_url: string;
+    expires_at: string;
+    expires_in: number;
+}
+interface LookupResponse {
+    pidx: string;
+    /** In paisa. */
+    total_amount: number;
+    status: KhaltiStatus | string;
+    transaction_id: string | null;
+    /** In paisa. */
+    fee: number;
+    refunded: boolean;
+}
+interface KhaltiClientOpts {
+    secretKey: string;
+    env?: KhaltiEnv;
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx Khalti response, carrying the parsed error body. */
+declare class KhaltiError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Khalti's `detail` field (or the raw error payload). */
+    readonly detail: unknown;
+    constructor(message: string, status: number, detail: unknown);
+}
+/**
+ * Initiate a Khalti payment. POSTs to `/epayment/initiate/` and returns the
+ * `pidx` and `payment_url` to redirect the customer to.
+ *
+ * @example
+ * const { payment_url, pidx } = await initiate(
+ *   {
+ *     return_url: "https://myshop.np/khalti/return",
+ *     website_url: "https://myshop.np",
+ *     amount: 1000, // NPR 10, in paisa
+ *     purchase_order_id: "order-42",
+ *     purchase_order_name: "Test order",
+ *   },
+ *   { secretKey: process.env.KHALTI_SECRET!, env: "test" },
+ * );
+ */
+declare function initiate(payload: InitiatePayload, opts: KhaltiClientOpts): Promise<InitiateResponse>;
+/**
+ * Look up a payment's real status by `pidx` — the authoritative check to run
+ * after the customer returns. POSTs `{ pidx }` to `/epayment/lookup/`.
+ *
+ * @example
+ * const r = await lookup(pidx, { secretKey, env: "test" });
+ * if (r.status === "Completed") fulfilOrder();
+ */
+declare function lookup(pidx: string, opts: KhaltiClientOpts): Promise<LookupResponse>;
+
+export { type InitiatePayload, type InitiateResponse, KHALTI_BASE_URLS, type KhaltiAmountBreakdown, type KhaltiClientOpts, type KhaltiCustomerInfo, type KhaltiEnv, KhaltiError, type KhaltiStatus, type LookupResponse, initiate, lookup };

package/dist/index.js

@@ -0,0 +1,52 @@
+// src/index.ts
+var KHALTI_BASE_URLS = {
+  test: "https://a.khalti.com/api/v2",
+  prod: "https://khalti.com/api/v2"
+};
+var KhaltiError = class _KhaltiError extends Error {
+  constructor(message, status, detail) {
+    super(message);
+    this.name = "KhaltiError";
+    this.status = status;
+    this.detail = detail;
+    Object.setPrototypeOf(this, _KhaltiError.prototype);
+  }
+};
+async function post(path, body, opts) {
+  const base = KHALTI_BASE_URLS[opts.env ?? "test"];
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  if (!doFetch) throw new Error("@lacspace/khalti: global fetch is unavailable; pass opts.fetch.");
+  const res = await doFetch(`${base}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Key ${opts.secretKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  let parsed = void 0;
+  const text = await res.text();
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!res.ok) {
+    const detail = parsed && typeof parsed === "object" && "detail" in parsed ? parsed.detail : parsed;
+    const message = typeof detail === "string" ? detail : `Khalti request failed with status ${res.status}`;
+    throw new KhaltiError(message, res.status, detail);
+  }
+  return parsed;
+}
+async function initiate(payload, opts) {
+  return post("/epayment/initiate/", payload, opts);
+}
+async function lookup(pidx, opts) {
+  return post("/epayment/lookup/", { pidx }, opts);
+}
+
+export { KHALTI_BASE_URLS, KhaltiError, initiate, lookup };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA0BO,IAAM,gBAAA,GAA8C;AAAA,EACzD,IAAA,EAAM,6BAAA;AAAA,EACN,IAAA,EAAM;AACR;AAqEO,IAAM,WAAA,GAAN,MAAM,YAAA,SAAoB,KAAA,CAAM;AAAA,EAMrC,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,MAAA,EAAiB;AAC5D,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAEd,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,YAAA,CAAY,SAAS,CAAA;AAAA,EACnD;AACF;AAMA,eAAe,IAAA,CAAQ,IAAA,EAAc,IAAA,EAAe,IAAA,EAAoC;AACtF,EAAA,MAAM,IAAA,GAAO,gBAAA,CAAiB,IAAA,CAAK,GAAA,IAAO,MAAM,CAAA;AAChD,EAAA,MAAM,OAAA,GAAU,IAAA,CAAK,KAAA,IAAS,UAAA,CAAW,KAAA;AACzC,EAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,MAAM,iEAAiE,CAAA;AAE/F,EAAA,MAAM,MAAM,MAAM,OAAA,CAAQ,GAAG,IAAI,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI;AAAA,IAC1C,MAAA,EAAQ,MAAA;AAAA,IACR,OAAA,EAAS;AAAA,MACP,aAAA,EAAe,CAAA,IAAA,EAAO,IAAA,CAAK,SAAS,CAAA,CAAA;AAAA,MACpC,cAAA,EAAgB;AAAA,KAClB;AAAA,IACA,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,IAAI;AAAA,GAC1B,CAAA;AAED,EAAA,IAAI,MAAA,GAAkB,MAAA;AACtB,EAAA,MAAM,IAAA,GAAO,MAAM,GAAA,CAAI,IAAA,EAAK;AAC5B,EAAA,IAAI,IAAA,EAAM;AACR,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,IAC1B,CAAA,CAAA,MAAQ;AACN,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAEA,EAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,IAAA,MAAM,MAAA,GACJ,UAAU,OAAO,MAAA,KAAW,YAAY,QAAA,IAAa,MAAA,GAChD,OAAmC,MAAA,GACpC,MAAA;AACN,IAAA,MAAM,UACJ,OAAO,MAAA,KAAW,WAAW,MAAA,GAAS,CAAA,kCAAA,EAAqC,IAAI,MAAM,CAAA,CAAA;AACvF,IAAA,MAAM,IAAI,WAAA,CAAY,OAAA,EAAS,GAAA,CAAI,QAAQ,MAAM,CAAA;AAAA,EACnD;AAEA,EAAA,OAAO,MAAA;AACT;AAsBA,eAAsB,QAAA,CACpB,SACA,IAAA,EAC2B;AAC3B,EAAA,OAAO,IAAA,CAAuB,qBAAA,EAAuB,OAAA,EAAS,IAAI,CAAA;AACpE;AAUA,eAAsB,MAAA,CAAO,MAAc,IAAA,EAAiD;AAC1F,EAAA,OAAO,IAAA,CAAqB,mBAAA,EAAqB,EAAE,IAAA,IAAQ,IAAI,CAAA;AACjE","file":"index.js","sourcesContent":["/**\n * @lacspace/khalti\n *\n * Khalti KPG-2 (ePayment API v2, Nepal) — a tiny, typed client for the two calls\n * every integration needs:\n *\n *   1. **initiate** — create a payment and get back a `payment_url` to redirect\n *      the customer to, plus a `pidx` to track it.\n *   2. **lookup**   — the source of truth: check a payment's real status by\n *      `pidx` after the customer returns (never trust the callback alone).\n *\n * Amounts are always in **paisa** (integer): NPR 10 → `1000`. Authentication is\n * a server-side `Authorization: Key <secretKey>` header. Non-2xx responses throw\n * a {@link KhaltiError} carrying Khalti's parsed `detail`.\n *\n * Isomorphic: Node 20+, edge runtimes and browsers via global `fetch`\n * (injectable). Zero dependencies.\n */\n\n/* ------------------------------------------------------------------ *\n * Endpoints & types\n * ------------------------------------------------------------------ */\n\nexport type KhaltiEnv = \"test\" | \"prod\";\n\n/** Khalti API base URLs. */\nexport const KHALTI_BASE_URLS: Record<KhaltiEnv, string> = {\n  test: \"https://a.khalti.com/api/v2\",\n  prod: \"https://khalti.com/api/v2\",\n};\n\n/** Possible values of a Khalti payment `status`. */\nexport type KhaltiStatus =\n  | \"Completed\"\n  | \"Pending\"\n  | \"Initiated\"\n  | \"Refunded\"\n  | \"Expired\"\n  | \"User canceled\"\n  | \"Partially Refunded\";\n\nexport interface KhaltiCustomerInfo {\n  name?: string;\n  email?: string;\n  phone?: string;\n}\n\nexport interface KhaltiAmountBreakdown {\n  label: string;\n  /** In paisa. */\n  amount: number;\n}\n\nexport interface InitiatePayload {\n  /** Where Khalti redirects the customer after payment. */\n  return_url: string;\n  /** Your site's base URL. */\n  website_url: string;\n  /** Total payable amount in **paisa** (integer). */\n  amount: number;\n  /** Your unique order id. */\n  purchase_order_id: string;\n  /** Human-readable order name. */\n  purchase_order_name: string;\n  customer_info?: KhaltiCustomerInfo;\n  amount_breakdown?: KhaltiAmountBreakdown[];\n  product_details?: unknown[];\n}\n\nexport interface InitiateResponse {\n  pidx: string;\n  payment_url: string;\n  expires_at: string;\n  expires_in: number;\n}\n\nexport interface LookupResponse {\n  pidx: string;\n  /** In paisa. */\n  total_amount: number;\n  status: KhaltiStatus | string;\n  transaction_id: string | null;\n  /** In paisa. */\n  fee: number;\n  refunded: boolean;\n}\n\nexport interface KhaltiClientOpts {\n  secretKey: string;\n  env?: KhaltiEnv;\n  fetch?: typeof fetch;\n}\n\n/* ------------------------------------------------------------------ *\n * Errors\n * ------------------------------------------------------------------ */\n\n/** Thrown on any non-2xx Khalti response, carrying the parsed error body. */\nexport class KhaltiError extends Error {\n  /** HTTP status code. */\n  readonly status: number;\n  /** Khalti's `detail` field (or the raw error payload). */\n  readonly detail: unknown;\n\n  constructor(message: string, status: number, detail: unknown) {\n    super(message);\n    this.name = \"KhaltiError\";\n    this.status = status;\n    this.detail = detail;\n    // Restore prototype chain for instanceof across transpile targets.\n    Object.setPrototypeOf(this, KhaltiError.prototype);\n  }\n}\n\n/* ------------------------------------------------------------------ *\n * Internal request helper\n * ------------------------------------------------------------------ */\n\nasync function post<T>(path: string, body: unknown, opts: KhaltiClientOpts): Promise<T> {\n  const base = KHALTI_BASE_URLS[opts.env ?? \"test\"];\n  const doFetch = opts.fetch ?? globalThis.fetch;\n  if (!doFetch) throw new Error(\"@lacspace/khalti: global fetch is unavailable; pass opts.fetch.\");\n\n  const res = await doFetch(`${base}${path}`, {\n    method: \"POST\",\n    headers: {\n      Authorization: `Key ${opts.secretKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify(body),\n  });\n\n  let parsed: unknown = undefined;\n  const text = await res.text();\n  if (text) {\n    try {\n      parsed = JSON.parse(text);\n    } catch {\n      parsed = text;\n    }\n  }\n\n  if (!res.ok) {\n    const detail =\n      parsed && typeof parsed === \"object\" && \"detail\" in (parsed as Record<string, unknown>)\n        ? (parsed as Record<string, unknown>).detail\n        : parsed;\n    const message =\n      typeof detail === \"string\" ? detail : `Khalti request failed with status ${res.status}`;\n    throw new KhaltiError(message, res.status, detail);\n  }\n\n  return parsed as T;\n}\n\n/* ------------------------------------------------------------------ *\n * Public API\n * ------------------------------------------------------------------ */\n\n/**\n * Initiate a Khalti payment. POSTs to `/epayment/initiate/` and returns the\n * `pidx` and `payment_url` to redirect the customer to.\n *\n * @example\n * const { payment_url, pidx } = await initiate(\n *   {\n *     return_url: \"https://myshop.np/khalti/return\",\n *     website_url: \"https://myshop.np\",\n *     amount: 1000, // NPR 10, in paisa\n *     purchase_order_id: \"order-42\",\n *     purchase_order_name: \"Test order\",\n *   },\n *   { secretKey: process.env.KHALTI_SECRET!, env: \"test\" },\n * );\n */\nexport async function initiate(\n  payload: InitiatePayload,\n  opts: KhaltiClientOpts,\n): Promise<InitiateResponse> {\n  return post<InitiateResponse>(\"/epayment/initiate/\", payload, opts);\n}\n\n/**\n * Look up a payment's real status by `pidx` — the authoritative check to run\n * after the customer returns. POSTs `{ pidx }` to `/epayment/lookup/`.\n *\n * @example\n * const r = await lookup(pidx, { secretKey, env: \"test\" });\n * if (r.status === \"Completed\") fulfilOrder();\n */\nexport async function lookup(pidx: string, opts: KhaltiClientOpts): Promise<LookupResponse> {\n  return post<LookupResponse>(\"/epayment/lookup/\", { pidx }, opts);\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/khalti",
+  "version": "1.0.0",
+  "description": "Khalti KPG-2 (ePayment API v2, Nepal) client — initiate payments, look up status, typed errors and Key auth over global fetch. 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",
+    "khalti",
+    "kpg-2",
+    "epayment",
+    "esewa",
+    "fetch",
+    "web-crypto",
+    "edge",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/khalti",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "khalti"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}