@prakashacharya/vendure-plugin-nepal-payments 0.1.0

package/dist/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_ATTEMPT_STATUSES = exports.NEPAL_PAYMENT_PROVIDERS = void 0;
+exports.NEPAL_PAYMENT_PROVIDERS = ['khalti', 'esewa', 'fonepay'];
+exports.PAYMENT_ATTEMPT_STATUSES = [
+    'initiated',
+    'pending',
+    'settled',
+    'failed',
+    'cancelled',
+    'expired',
+    'partially-refunded',
+    'refunded',
+    'unknown',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAEa,QAAA,uBAAuB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAIlE,QAAA,wBAAwB,GAAG;IACtC,WAAW;IACX,SAAS;IACT,SAAS;IACT,QAAQ;IACR,WAAW;IACX,SAAS;IACT,oBAAoB;IACpB,UAAU;IACV,SAAS;CACD,CAAC"}

package/docs/ADDING_A_PROVIDER.md

@@ -0,0 +1,74 @@
+# Adding a provider
+
+Provider contributions are welcome when based on official, shareable documentation.
+
+## 1. Extend the provider type
+
+Add the provider code to `NEPAL_PAYMENT_PROVIDERS` in `src/types.ts`. Treat this as a public API change and update `CHANGELOG.md`.
+
+## 2. Implement `NepalPaymentProvider`
+
+Create `src/providers/<provider>.provider.ts` implementing:
+
+```ts
+interface NepalPaymentProvider {
+  readonly code: NepalPaymentProviderCode;
+  initiate(input: InitiatePaymentInput): Promise<PaymentInitiation>;
+  verify(input: VerifyPaymentInput): Promise<VerifiedPayment>;
+  refund?(input: RefundPaymentInput): Promise<RefundResult>;
+}
+```
+
+The adapter must:
+
+- use fixed sandbox and production base URLs;
+- keep credentials server-side;
+- set bounded network timeouts;
+- reject unexpected redirects;
+- validate provider reference, merchant reference, exact amount, and currency where available;
+- map only documented terminal success states to `settled`;
+- preserve unknown states as `unknown` or `pending`;
+- return sanitized response data suitable for restricted operational logs/storage.
+
+Do not use floating-point money calculations.
+
+## 3. Add configuration
+
+Add a provider options interface in `src/config.ts`, validate required values at bootstrap, and document every option in `docs/CONFIGURATION.md` and `.env.example`.
+
+## 4. Register the provider
+
+Update `createProvider()` and add a dedicated Vendure `PaymentMethodHandler`. The handler must validate the settlement proof and perform its own provider lookup.
+
+Refund support is optional. If no verified API exists, omit `createRefund` and document the manual process.
+
+## 5. Add GraphQL and callback support
+
+Update the GraphQL enum and ensure the provider can use the shared callback route. If a provider requires a webhook with different authentication, add a narrowly scoped controller and document it.
+
+## 6. Test the contract
+
+Unit tests must cover:
+
+- initiation payload and authorization headers without revealing real credentials;
+- successful verification;
+- pending, failed, cancelled, expired, refunded, and unknown mappings;
+- mismatched amount and references;
+- malformed responses;
+- network errors and timeouts;
+- full and partial refunds, if supported.
+
+An end-to-end sandbox test plan is required before marking the provider production-ready.
+
+## 7. Document and release
+
+Update:
+
+- root `README.md` support matrix;
+- `docs/PROVIDERS.md` with official links;
+- `docs/INSTALLATION.md` payment method and environment setup;
+- `docs/STOREFRONT.md` for any unique UI behavior;
+- `CHANGELOG.md`;
+- package keywords when appropriate.
+
+Never commit private provider manuals unless their license expressly permits redistribution.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# Architecture
+
+The package contains one Vendure plugin with separate payment handlers and a shared provider contract.
+
+```text
+Storefront
+  │ initiateNepalPayment(provider)
+  ▼
+PaymentOrchestratorService ── persists ── NepalPaymentAttempt
+  │                                      │
+  │ initiate                             │ idempotency/status
+  ▼                                      │
+Provider adapter                         │
+  │ redirect or signed form              │
+  ▼                                      │
+Hosted provider checkout                 │
+  │ callback                             │
+  ▼                                      │
+PaymentCallbackController ───────────────┘
+  │ server lookup + exact validation
+  ▼
+Authenticated settlement proof
+  │
+  ▼
+Vendure PaymentMethodHandler
+  │ second provider lookup
+  ▼
+Settled Vendure Payment → order state transition
+```
+
+## Why separate payment handlers
+
+Vendure payment methods are independently enabled, assigned to channels, checked for eligibility, displayed to customers, refunded, and reported. Keeping `nepal-khalti` and `nepal-esewa` separate preserves those native behaviors while sharing internal infrastructure.
+
+## Why payment attempts are separate from Vendure payments
+
+A redirect or QR initiation is not authorization or settlement. Creating an `Authorized` Vendure payment before the customer pays would misrepresent the financial state. `NepalPaymentAttempt` tracks the asynchronous provider lifecycle; the actual Vendure payment is created only after verification succeeds.
+
+## Settlement proof
+
+Vendure's standard `addPaymentToOrder` mutation accepts arbitrary metadata from the storefront. The handlers therefore do not trust an attempt ID or provider reference by itself. The callback orchestrator creates an HMAC proof binding:
+
+```text
+provider | attemptId | orderId | amount | providerReference
+```
+
+The handler checks this proof using `internalSigningSecret` and then independently calls the provider lookup endpoint. This prevents a customer from attaching a known transaction for another order, channel, or amount.
+
+## Idempotency
+
+- Merchant references are UUIDs.
+- Provider/merchant and provider/provider-reference pairs are unique.
+- Callback processing atomically changes an eligible attempt to `verifying`.
+- Already-settled callbacks return the existing attempt.
+- Stale `verifying` attempts return to `pending` during reconciliation.
+- Vendure creates a payment only after a successful provider lookup.
+
+## Status normalization
+
+Provider-specific statuses map to a conservative shared vocabulary:
+
+```text
+initiated, pending, settled, failed, cancelled, expired,
+partially-refunded, refunded, unknown
+```
+
+Only `settled` creates a Vendure payment. Unknown and ambiguous provider states never settle.
+
+## Amounts
+
+Vendure stores money as integer minor units. Khalti consumes paisa directly. eSewa consumes a canonical rupee decimal string. Conversion uses string/integer arithmetic and rejects unsafe or over-precise values.
+
+## Reconciliation
+
+The scheduled task checks old `initiated`, `pending`, and `unknown` attempts. It does not infer success; it calls the same provider verification and settlement path as a callback. This handles lost redirects, browser closure, and transient network errors.

package/docs/CONFIGURATION.md

@@ -0,0 +1,49 @@
+# Configuration reference
+
+`NepalPaymentsPlugin.init(options)` validates configuration during Vendure bootstrap and fails early for unsafe or incomplete settings.
+
+## Top-level options
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `publicServerUrl` | `string` | Yes | Public Vendure server origin used to build provider callbacks. HTTPS is required except on loopback hosts. |
+| `storefrontResultUrl` | `string` | Yes | Storefront page receiving the final redirect. HTTPS is required except on loopback hosts. |
+| `internalSigningSecret` | `string` | Yes | At least 32 characters. Authenticates internal settlement metadata. Do not reuse a provider secret. |
+| `reconciliationSchedule` | cron string or `false` | No | Defaults to every five minutes (`*/5 * * * *`). `false` disables the scheduled task. |
+| `khalti` | `KhaltiPluginOptions` | Conditional | Enables Khalti. |
+| `esewa` | `EsewaPluginOptions` | Conditional | Enables eSewa. |
+| `fonepay` | `FonepayPluginOptions` | No | Reserved API shape only; Fonepay initiation is not implemented yet. |
+
+At least one of `khalti` or `esewa` is required.
+
+## Khalti options
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `secretKey` | `string` | Yes | Merchant secret key. It is used only server-side. |
+| `websiteUrl` | `string` | Yes | Public storefront website URL registered with Khalti. |
+| `environment` | `sandbox` or `production` | No | Defaults to `sandbox`. |
+| `paymentMethodCode` | `string` | No | Vendure payment method code. Defaults to `khalti`. |
+
+## eSewa options
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `productCode` | `string` | Yes | Merchant product code supplied by eSewa. |
+| `secretKey` | `string` | Yes | HMAC secret supplied by eSewa. It is used only server-side. |
+| `environment` | `sandbox` or `production` | No | Defaults to `sandbox`. |
+| `paymentMethodCode` | `string` | No | Vendure payment method code. Defaults to `esewa`. |
+
+## Environment separation
+
+Create separate deployments or secret sets for sandbox and production. Never select production merely because `NODE_ENV=production`; the provider environment must be explicit so staging cannot accidentally charge real accounts.
+
+## Multi-channel limitation
+
+Version 0.1 uses one credential set per provider for the entire Vendure instance. Payment attempts record `channelId` and `channelToken`, but per-channel credential resolution is not implemented yet. Do not use this release when multiple channels require different merchant accounts for the same provider.
+
+## Secret rotation
+
+Rotating `internalSigningSecret` while callbacks are pending can prevent those attempts from settling. During rotation, stop new initiations, reconcile pending attempts, deploy the new value, and then resume checkout.
+
+Provider-secret rotation follows the provider's merchant procedure. Existing attempts may require the old key for lookup, so coordinate rotation during a low-traffic window and reconcile first.

package/docs/DATA_HANDLING.md

@@ -0,0 +1,46 @@
+# Data handling and privacy
+
+The plugin processes payment and order identifiers and therefore should be included in the merchant's privacy, retention, access-control, and incident-response reviews.
+
+## Stored payment-attempt fields
+
+`NepalPaymentAttempt` stores:
+
+- Vendure order ID and code;
+- channel ID and token;
+- provider and Vendure payment method code;
+- generated merchant reference and provider reference;
+- integer amount and currency code;
+- normalized status and timestamps;
+- provider transaction ID and resulting Vendure payment ID;
+- a sanitized subset of provider response data for operations.
+
+The plugin does not intentionally store wallet passwords, OTPs, PINs, card data, provider secret keys, or the internal signing secret in the database.
+
+## Provider-response redaction
+
+Before a provider response is stored, recursive redaction removes fields whose names indicate credentials, API keys, PINs, OTPs, customer details, phone/mobile numbers, email addresses, signatures, tokens, or signed payment/redirect URLs. Depth, array size, and string length are bounded.
+
+This is defense in depth, not a substitute for reviewing every provider adapter. New adapters must return the smallest useful `raw` object and must add tests for provider-specific sensitive fields.
+
+## Logs
+
+The plugin does not intentionally log provider payloads or credentials. Host applications, reverse proxies, GraphQL instrumentation, error tracking, and HTTP debugging can still capture request data. Configure those systems to redact:
+
+- `Authorization` headers and API keys;
+- callback query/body payloads;
+- phone numbers and email addresses;
+- provider and merchant transaction references where not operationally required;
+- GraphQL variables containing payment form fields.
+
+## Retention
+
+Version 0.1 does not automatically delete payment attempts. Merchants must define a retention policy balancing accounting, dispute, fraud, provider-contract, privacy, and Nepalese legal requirements. Do not add a generic cleanup job without confirming which financial records must be retained.
+
+## Access
+
+The entity is not exposed through a public Shop API query. Database and operational access should be limited to staff who need payment reconciliation capability. Future Admin API/Dashboard views must use Vendure order/payment permissions and avoid exposing raw provider responses by default.
+
+## Telemetry
+
+This plugin sends no analytics or project telemetry. It communicates only with the provider endpoints required for payment initiation, verification, and refunds.

package/docs/INSTALLATION.md

@@ -0,0 +1,132 @@
+# Installing in Vendure
+
+This guide installs the plugin into an existing Vendure 3.7 application. The plugin is a server plugin; it is not installed in the storefront package.
+
+## Requirements
+
+- Vendure `>=3.7.0 <4.0.0`
+- Node.js 22 or newer
+- A Vendure SQL database
+- A separately running Vendure worker for scheduled reconciliation in production
+- Merchant sandbox credentials from at least one supported provider
+- A publicly reachable HTTPS server URL for provider callbacks
+
+## 1. Install the package
+
+From the Vendure server project:
+
+```bash
+npm install @prakashacharya/vendure-plugin-nepal-payments
+```
+
+When developing from a local clone before the first npm release:
+
+```bash
+# In the plugin repository
+npm ci
+npm run build
+npm pack
+
+# In the Vendure application; use the generated filename
+npm install ../vendure-plugin-nepal-payments/pa-vendure-plugin-nepal-payments-0.1.0.tgz
+```
+
+## 2. Add environment variables
+
+Copy the relevant names from [`.env.example`](../.env.example) into the Vendure application's environment configuration. Never commit real values.
+
+Generate the internal signing secret separately from provider keys:
+
+```bash
+openssl rand -base64 48
+```
+
+The generated value is used only inside this plugin to bind a verified gateway transaction to a specific Vendure order.
+
+## 3. Register the plugin
+
+Add `NepalPaymentsPlugin.init()` to `vendure-config.ts`:
+
+```ts
+import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+import { NepalPaymentsPlugin } from '@prakashacharya/vendure-plugin-nepal-payments';
+
+export const config: VendureConfig = {
+  // Existing database, API, auth, order and other configuration...
+  plugins: [
+    DefaultSchedulerPlugin.init(),
+    NepalPaymentsPlugin.init({
+      publicServerUrl: process.env.PUBLIC_SERVER_URL!,
+      storefrontResultUrl: process.env.STOREFRONT_PAYMENT_RESULT_URL!,
+      internalSigningSecret: process.env.NEPAL_PAYMENTS_INTERNAL_SECRET!,
+      khalti: {
+        environment: process.env.KHALTI_ENVIRONMENT === 'production' ? 'production' : 'sandbox',
+        secretKey: process.env.KHALTI_SECRET_KEY!,
+        websiteUrl: process.env.KHALTI_WEBSITE_URL!,
+        paymentMethodCode: 'khalti',
+      },
+      esewa: {
+        environment: process.env.ESEWA_ENVIRONMENT === 'production' ? 'production' : 'sandbox',
+        productCode: process.env.ESEWA_PRODUCT_CODE!,
+        secretKey: process.env.ESEWA_SECRET_KEY!,
+        paymentMethodCode: 'esewa',
+      },
+    }),
+  ],
+};
+```
+
+Omit a provider block if that provider should not be enabled. At least one implemented provider must be configured.
+
+`DefaultSchedulerPlugin` is required for automatic pending-payment reconciliation. Set `reconciliationSchedule: false` only when another process calls equivalent reconciliation logic.
+
+## 4. Generate the database migration
+
+The plugin adds a `NepalPaymentAttempt` entity. From the Vendure application, run:
+
+```bash
+npx vendure migrate
+```
+
+Choose **Generate a new migration**, inspect the generated SQL, then run the migration command again and choose **Run pending migrations**.
+
+Commit the generated migration to the Vendure application repository. Do not enable TypeORM schema synchronization in production.
+
+## 5. Create Vendure payment methods
+
+Start the server and open the Vendure Dashboard:
+
+1. Go to **Settings → Payment methods**.
+2. Create a method with code `khalti`.
+3. Select the **Khalti by IME** handler (`nepal-khalti`).
+4. Enable it and assign it only to channels that use NPR.
+5. Create a method with code `esewa`.
+6. Select the **eSewa** handler (`nepal-esewa`).
+7. Enable it and assign it only to channels that use NPR.
+
+The payment method code must equal the matching `paymentMethodCode` in plugin configuration. The handler code and payment method code are different concepts.
+
+| Provider | Payment method code | Handler code |
+| --- | --- | --- |
+| Khalti by IME | `khalti` | `nepal-khalti` |
+| eSewa | `esewa` | `nepal-esewa` |
+
+## 6. Integrate the storefront
+
+Follow [STOREFRONT.md](./STOREFRONT.md). The storefront must transition the order to `ArrangingPayment`, call `initiateNepalPayment`, then redirect to Khalti or submit the signed eSewa form.
+
+Do not call Vendure's standard `addPaymentToOrder` mutation directly from the storefront for these providers. The callback orchestrator does that only after server verification.
+
+## 7. Verify the installation
+
+Before using real money:
+
+```bash
+npx vendure doctor --check dependencies config schema database
+```
+
+Then complete the sandbox matrix in [PRODUCTION.md](./PRODUCTION.md), including duplicate callbacks, cancellations, altered amounts, timeouts, and delayed status changes.
+
+## Upgrading
+
+Read [`CHANGELOG.md`](../CHANGELOG.md) before every upgrade. Run `npx vendure migrate` when a release changes plugin entities. Public API breaking changes occur only in semver-major releases after 1.0; while the project is `0.x`, minor versions may contain breaking changes and will call them out prominently.

package/docs/LICENSING.md

@@ -0,0 +1,29 @@
+# Licensing and trademarks
+
+## Project license
+
+The plugin's original source code is licensed under the [MIT License](../LICENSE). You may use, copy, modify, publish, and distribute it subject to that license's notice requirements and warranty disclaimer.
+
+## Vendure compatibility
+
+Vendure Core is GPLv3. Vendure's official [Publishing a Plugin](https://docs.vendure.io/current/core/how-to/publish-plugin) guide states that Vendure provides a special plugin exception allowing independently distributed plugins to use another license. This project relies on that published exception and uses MIT.
+
+This explanation is informational and is not legal advice. Organizations with redistribution or embedded-product concerns should have counsel review their complete dependency and deployment model.
+
+## Dependencies
+
+Dependencies and peer dependencies retain their own licenses. npm consumers should run their normal software-composition analysis and preserve notices required by those projects. This repository does not relicense Vendure, NestJS, TypeORM, GraphQL, or provider services.
+
+## Provider material
+
+The repository does not include provider SDK source code, logos, private manuals, merchant credentials, or test accounts. API names and endpoints are implemented for interoperability. Provider APIs remain subject to their own merchant agreements and terms.
+
+Contributors must not upload documents or assets they are not authorized to redistribute.
+
+## Trademarks
+
+Vendure, Khalti, IME Pay, eSewa, Fonepay, and other product names are trademarks of their respective owners. Their use does not imply endorsement. See [`NOTICE.md`](../NOTICE.md).
+
+## Contributions
+
+Contributions are accepted under the project's MIT License. There is no CLA at present. See [`CONTRIBUTING.md`](../CONTRIBUTING.md).

package/docs/PRODUCTION.md

@@ -0,0 +1,50 @@
+# Security and production checklist
+
+## Before sandbox testing
+
+- [ ] Plugin and Vendure versions satisfy the compatibility range.
+- [ ] The database migration is generated and reviewed.
+- [ ] Provider payment methods are assigned only to NPR channels.
+- [ ] Provider environment is explicitly `sandbox`.
+- [ ] Secrets are loaded from a secret manager or local ignored `.env` file.
+- [ ] The Vendure worker and scheduler are running.
+
+## Sandbox test matrix
+
+- [ ] Successful Khalti payment
+- [ ] Successful eSewa payment
+- [ ] Customer cancellation
+- [ ] Expired checkout
+- [ ] Provider pending/ambiguous status
+- [ ] Browser closed before redirect
+- [ ] Callback delivered twice
+- [ ] Callback delivered concurrently
+- [ ] Altered callback amount
+- [ ] Altered provider reference
+- [ ] Provider timeout during initiation
+- [ ] Provider timeout during verification
+- [ ] Reconciliation after a lost callback
+- [ ] Full Khalti refund
+- [ ] Partial Khalti refund
+- [ ] Manual eSewa refund process
+
+Verify in every case that fulfillment occurs only after the Vendure payment is `Settled`.
+
+## Before production
+
+- [ ] Merchant onboarding and KYC are complete for each provider.
+- [ ] Production domains and callback URLs are approved by providers.
+- [ ] Production keys are separate from sandbox keys.
+- [ ] `publicServerUrl` and `storefrontResultUrl` use HTTPS.
+- [ ] `internalSigningSecret` is unique, random, and at least 32 characters.
+- [ ] Logs redact authorization headers, secrets, customer identifiers, and raw callbacks.
+- [ ] Callback routes are protected by infrastructure rate limiting and request-size limits.
+- [ ] Database backups and migration rollback procedures are tested.
+- [ ] Alerts exist for old `pending`, `unknown`, and repeated verification failures.
+- [ ] Operations staff can reconcile provider and Vendure transaction references.
+- [ ] Refund roles and approval processes are defined.
+- [ ] `npx vendure doctor --profile production --strict` passes in the host project.
+
+## Operational rule
+
+Never manually change a payment attempt or Vendure payment to settled based only on a screenshot, customer claim, redirect query parameter, or callback body. Confirm the transaction in the provider merchant system or through its server status API.

package/docs/PROVIDERS.md

@@ -0,0 +1,57 @@
+# Provider support
+
+Provider behavior and access can change. Confirm the current official documentation and merchant agreement before each production launch.
+
+## Support matrix
+
+| Provider | Initiation | Verification | Refund | Status |
+| --- | --- | --- | --- | --- |
+| Khalti by IME | KPG-2 server request and hosted redirect | `/epayment/lookup/` using `pidx` | Wallet full/partial; bank-funded refunds may need payer mobile/manual handling | Implemented with refund caveat |
+| eSewa | ePay v2 signed HTML form | Signed callback plus transaction status API | No public refund call implemented | Implemented |
+| Fonepay | Dynamic QR expected | Merchant documentation required | Unknown until onboarding | Reserved, disabled |
+| IME Pay | — | — | — | No separate integration; migrated into Khalti by IME |
+| connectIPS / NEPALPAY | Not implemented | Not implemented | Not implemented | Candidate future provider |
+
+## Khalti by IME
+
+Official documentation:
+
+- [KPG-2 Web Checkout](https://docs.khalti.com/khalti-epayment/)
+- [Refund API](https://docs.khalti.com/api/refund/)
+- [Merchant support](https://docs.khalti.com/contact-us/)
+
+The plugin sends Vendure's integer NPR minor-unit amount directly as Khalti paisa. Only the `Completed` lookup status settles a payment. Unknown or pending statuses remain unsettled.
+
+The public Khalti refund API documents additional mobile data for some bank-funded refunds. Vendure's standard refund input does not collect that provider-specific value, so those cases may fail through the handler and should be completed in the Khalti merchant dashboard. Wallet refunds can use the implemented API path.
+
+Khalti can expose multiple underlying payment sources. That does not change the plugin's provider code; Vendure records the payment under the Khalti payment method.
+
+## eSewa
+
+Official documentation:
+
+- [eSewa ePay](https://developer.esewa.com.np/pages/Epay)
+
+The plugin converts Vendure minor units into a two-decimal rupee string, signs the documented fields using HMAC-SHA256, verifies signed callback data when supplied, and performs an independent status lookup. Only `COMPLETE` or `SUCCESS` settles a payment.
+
+Programmatic refunds are intentionally not advertised because the public ePay documentation does not provide a complete merchant refund request contract. Vendure administrators must follow their merchant agreement and settle refund records manually unless a future verified API is added.
+
+## Fonepay
+
+Fonepay advertises dynamic QR integration, but the implementation contract is merchant-specific and is not publicly complete. The project will not reproduce private documentation or implement unofficial signature recipes.
+
+A contribution may enable Fonepay after maintainers can verify legally shareable details for:
+
+- sandbox and production endpoints;
+- merchant authentication and signature canonicalization;
+- dynamic QR request/response fields;
+- enquiry and terminal status mapping;
+- callback authentication;
+- expiry behavior;
+- full and partial refunds.
+
+Until then, `FONEPAY` exists in the GraphQL enum for forward compatibility but initiation fails explicitly.
+
+## Provider terms and fees
+
+This open-source package does not create merchant accounts, negotiate fees, certify an integration, or grant access to provider APIs. Each merchant is responsible for onboarding, KYC, commercial terms, limits, settlement, disputes, refunds, and compliance directly with the relevant provider.

package/docs/README.md

@@ -0,0 +1,15 @@
+# Documentation
+
+- [Installation in an existing Vendure project](./INSTALLATION.md)
+- [Configuration reference](./CONFIGURATION.md)
+- [Storefront integration](./STOREFRONT.md)
+- [Provider support and onboarding](./PROVIDERS.md)
+- [Architecture and payment lifecycle](./ARCHITECTURE.md)
+- [Adding another provider](./ADDING_A_PROVIDER.md)
+- [Security and production checklist](./PRODUCTION.md)
+- [Data handling and privacy](./DATA_HANDLING.md)
+- [Troubleshooting](./TROUBLESHOOTING.md)
+- [Licensing and trademarks](./LICENSING.md)
+- [Maintainer release process](./RELEASING.md)
+
+The root [`README.md`](../README.md) remains the primary npm and Vendure Hub landing page.

package/docs/RELEASING.md

@@ -0,0 +1,74 @@
+# Maintainer release process
+
+## One-time repository setup
+
+Before the first public release:
+
+1. Create the public GitHub repository.
+2. Add `repository`, `homepage`, and `bugs` URLs to `package.json`.
+3. Replace the repository link placeholders in `CHANGELOG.md`.
+4. Confirm that the `@prakashacharya` npm scope belongs to the publishing user or organization and that maintainers have publish access. Otherwise choose a scope you control before the first release.
+5. Enable GitHub private vulnerability reporting.
+6. Create a short-lived npm granular access token for the initial publication:
+   - grant read and write access to the `@prakashacharya` scope;
+   - enable bypass 2FA because GitHub Actions cannot answer an interactive OTP prompt;
+   - use the shortest practical expiration;
+   - add it to the GitHub `npm` environment as an environment secret named `NPM_TOKEN`.
+7. Enable branch protection requiring the CI workflow.
+8. Add an npm README/profile link to the public repository.
+
+`npm publish` intentionally runs `npm run check:release-metadata` and refuses to publish until these real public URLs are configured.
+
+The npm token must only be stored as a GitHub Actions secret. Never commit it to this repository, place it directly in the workflow, or include it in an issue or log. The release workflow exposes it only to the credential check and `npm publish` steps as `NODE_AUTH_TOKEN`.
+
+### Configure the first GitHub Actions publication
+
+1. Sign in to npm with an account that can publish packages under `@prakashacharya`.
+2. In npm account settings, create a granular access token with read and write access to the `@prakashacharya` scope and bypass 2FA enabled.
+3. In GitHub, open **Settings > Environments > npm**. Create the environment if it does not exist.
+4. Under **Environment secrets**, add a secret named `NPM_TOKEN` and paste the npm token as its value.
+5. Optionally configure required reviewers on the `npm` environment so a maintainer must approve every publication.
+6. Follow the release checklist below and publish the GitHub Release. The workflow publishes the package; maintainers do not run `npm publish` locally.
+
+After the first package version exists on npm, replace token authentication with npm Trusted Publishing. Configure the package's trusted publisher for GitHub owner `pracharya2601`, repository `NPP`, workflow `release.yml`, and environment `npm`; then remove `NPM_TOKEN` from GitHub and remove the credential-check and `NODE_AUTH_TOKEN` configuration from the workflow. Trusted Publishing uses GitHub OIDC and does not require a stored publishing token.
+
+Vendure recommends scoped plugin package names, a current changelog included in the npm package, full installation and storefront documentation, compatibility metadata, and tests before submission to Vendure Hub.
+
+## Release checklist
+
+1. Ensure CI passes on the default branch.
+2. Update `CHANGELOG.md`, moving relevant Unreleased entries into a dated version.
+3. Update the version without creating an automatic Git tag:
+
+   ```bash
+   npm version <patch|minor|major> --no-git-tag-version
+   ```
+
+4. Run:
+
+   ```bash
+   npm ci
+   npm run check
+   npm pack --dry-run
+   npm audit --omit=dev
+   ```
+
+5. Inspect the tarball file list. It must include `dist`, README, docs, changelog, license, and notices, and must exclude tests, credentials, local environment files, and private documentation.
+6. Commit the version and changelog.
+7. Create a signed tag `v<version>`.
+8. Push the commit and tag.
+9. Create a GitHub Release from the tag. The release workflow verifies that tag and package versions match, then publishes to npm with provenance using the protected `NPM_TOKEN` secret.
+10. Verify installation in a clean Vendure project.
+11. For a stable, documented release, submit the npm and GitHub URLs to Vendure Hub.
+
+## Versioning
+
+The package uses Semantic Versioning.
+
+- Patch: backwards-compatible fixes and documentation.
+- Minor: backwards-compatible provider/features after 1.0.
+- Major: public API, configuration, GraphQL, database, or behavioral breaking changes.
+
+Before 1.0, a minor version may be breaking. Such changes must be clearly labeled in the changelog and migration notes.
+
+Provider-side API changes can require urgent plugin releases even when this project's TypeScript API is unchanged.