@prakashacharya/vendure-plugin-nepal-payments 0.1.0

package/docs/STOREFRONT.md

@@ -0,0 +1,111 @@
+# Storefront integration
+
+The plugin adds one Shop API mutation. It does not add UI components, so any Vendure-compatible storefront can use it.
+
+## Checkout sequence
+
+1. Build the cart, addresses, shipping method, and customer details normally.
+2. Transition the active order to `ArrangingPayment`.
+3. Query eligible payment methods and show only methods returned by Vendure.
+4. Call `initiateNepalPayment` with the selected provider.
+5. Redirect to Khalti or submit the returned eSewa form.
+6. The provider returns to the plugin callback controller.
+7. The plugin verifies server-to-server and creates a settled Vendure payment.
+8. The plugin redirects to the configured storefront result page.
+9. The result page queries Vendure for the authoritative order state.
+
+## GraphQL mutation
+
+```graphql
+mutation InitiateNepalPayment($provider: NepalPaymentProviderCode!) {
+  initiateNepalPayment(provider: $provider) {
+    attemptId
+    provider
+    status
+    redirectUrl
+    qrPayload
+    expiresAt
+    form {
+      action
+      fields {
+        name
+        value
+      }
+    }
+  }
+}
+```
+
+Variables:
+
+```json
+{ "provider": "KHALTI" }
+```
+
+or:
+
+```json
+{ "provider": "ESEWA" }
+```
+
+The request must carry the same Vendure session token/cookie used for the active order.
+
+## Khalti response
+
+Khalti returns `redirectUrl`. Navigate the top-level browser to that URL:
+
+```ts
+const payment = result.data.initiateNepalPayment;
+if (!payment.redirectUrl) throw new Error('Khalti redirect URL was not returned');
+window.location.assign(payment.redirectUrl);
+```
+
+Do not open checkout in an iframe unless Khalti's current merchant documentation explicitly supports it.
+
+## eSewa response
+
+eSewa requires an HTML POST. Submit the exact returned field names and values:
+
+```ts
+function submitPaymentForm(form: {
+  action: string;
+  fields: Array<{ name: string; value: string }>;
+}) {
+  const element = document.createElement('form');
+  element.method = 'POST';
+  element.action = form.action;
+
+  for (const field of form.fields) {
+    const input = document.createElement('input');
+    input.type = 'hidden';
+    input.name = field.name;
+    input.value = field.value;
+    element.appendChild(input);
+  }
+
+  document.body.appendChild(element);
+  element.submit();
+}
+```
+
+Do not recalculate, reformat, translate, or round any signed eSewa field.
+
+## Result page
+
+The callback controller redirects to `storefrontResultUrl` with:
+
+```text
+?attemptId=<uuid>&provider=<provider>&status=<status>
+```
+
+Possible status values include `settled`, `pending`, `failed`, `cancelled`, `expired`, and `unknown`.
+
+These query parameters are presentation hints, not authorization or fulfillment proof. The storefront must query Vendure and use the order/payment state as authoritative. For `pending`, show a waiting state and poll with backoff; the reconciliation worker may settle the payment later.
+
+## Preventing duplicate initiation
+
+Disable the payment button while the mutation is running. The server also rejects another active attempt for the same order and provider. Do not automatically retry an initiation after a network timeout; first allow the callback/reconciliation flow to determine whether the provider created the transaction.
+
+## Do not expose secrets
+
+The storefront needs no secret keys, signatures, provider lookup APIs, or settlement proofs. If any provider secret appears in browser code, browser network responses, analytics, or source maps, the integration is incorrect.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,71 @@
+# Troubleshooting
+
+## Plugin fails during bootstrap
+
+Common causes:
+
+- `NepalPaymentsPlugin` was added without calling `.init()`;
+- the internal signing secret is shorter than 32 characters;
+- a public URL uses HTTP outside localhost;
+- neither Khalti nor eSewa is configured;
+- a required provider credential is empty;
+- Vendure is outside the plugin compatibility range.
+
+Run:
+
+```bash
+npx vendure doctor --check dependencies config
+```
+
+## Payment method is not eligible
+
+Confirm that:
+
+- the payment method code exactly matches `paymentMethodCode`;
+- the method is enabled;
+- it is assigned to the active channel;
+- the channel currency is NPR;
+- any custom eligibility checker accepts the order;
+- the order is in `ArrangingPayment`.
+
+## Database table is missing
+
+Generate and run the host Vendure application's migration after registering the plugin:
+
+```bash
+npx vendure migrate
+```
+
+Do not fix production by enabling schema synchronization.
+
+## Callback returns `pending`
+
+This can be normal for provider processing or a temporary lookup failure. Confirm that the Vendure worker and scheduler are running. Review the payment attempt and provider merchant dashboard using the merchant/provider references. Do not fulfill the order until Vendure records a settled payment.
+
+## eSewa signature failure
+
+Check that:
+
+- the correct sandbox or production secret is configured;
+- form fields were submitted without reformatting;
+- the storefront did not parse and reconstruct decimal amounts;
+- `productCode` matches the merchant environment;
+- proxies preserve the callback query/body.
+
+The reconciliation task can still perform a trusted server status lookup, but a malformed callback itself is never accepted.
+
+## Khalti lookup reference mismatch
+
+The `pidx` returned by lookup must equal the stored provider reference. Confirm that the callback URL and attempt ID were not reused or modified. Treat a mismatch as a security event rather than editing the database.
+
+## Duplicate payment attempt
+
+The plugin permits only one non-expired active attempt per provider and order. Let the existing attempt complete, expire, or be reconciled. Do not generate repeated payment requests automatically after browser/network errors.
+
+## Refund fails
+
+Confirm that the provider transaction is refundable, the merchant account has permission, and the correct production/sandbox key is active. Khalti bank-funded refunds may require payer mobile information depending on the merchant contract; the current Vendure handler does not collect that value, so such refunds may need the merchant dashboard.
+
+## Getting help
+
+Use GitHub Discussions for integration questions and GitHub Issues for reproducible bugs. Redact all sensitive data as described in [`SECURITY.md`](../SECURITY.md).

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@prakashacharya/vendure-plugin-nepal-payments",
+  "version": "0.1.0",
+  "description": "Open-source Vendure payment integrations for Khalti by IME, eSewa, and other Nepalese providers",
+  "license": "MIT",
+  "author": "NPP Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pracharya2601/NPP.git"
+  },
+  "homepage": "https://github.com/pracharya2601/NPP#readme",
+  "bugs": {
+    "url": "https://github.com/pracharya2601/NPP/issues"
+  },
+  "keywords": [
+    "vendure",
+    "vendure-plugin",
+    "payments",
+    "nepal",
+    "khalti",
+    "esewa",
+    "fonepay",
+    "ecommerce"
+  ],
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "check": "npm run typecheck && npm test && npm run build",
+    "check:release-metadata": "node scripts/check-release-metadata.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run clean && npm run check",
+    "prepublishOnly": "npm run check:release-metadata && npm run check"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "graphql-tag": "^2.12.6"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/graphql": "^13.1.0",
+    "@vendure/core": "^3.7.0",
+    "typeorm": "^0.3.21"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@nestjs/common": "^11.0.12",
+    "@nestjs/graphql": "^13.1.0",
+    "@vendure/core": "3.7.0",
+    "typeorm": "^0.3.21",
+    "typescript": "5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}