@abhi1693/medusa-payment-razorpay 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhimanyu Saharan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation 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 following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# Medusa Razorpay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/abhi1693/medusa-payment-razorpay/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/abhi1693/medusa-payment-razorpay/actions/workflows/ci.yaml)
+
+[![Medusa 2.22.2 / 2.22.4](https://img.shields.io/badge/Medusa-2.22.2%20%7C%202.22.4-7c3aed)](https://docs.medusajs.com/)
+[![MIT license](https://img.shields.io/github/license/abhi1693/medusa-payment-razorpay)](LICENSE)
+[![Sponsor](https://img.shields.io/badge/Sponsor-abhi1693-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/abhi1693)
+
+A Razorpay payment provider for Medusa v2, with verified checkout results, automatic-capture payments, full and partial refunds, and reusable server-side reconciliation helpers. Uses native Medusa payment sessions, payments, captures and refunds without additional models or a financial ledger.
+
+**Supports INR with explicitly configured Razorpay test or live credentials.** Unsupported currencies and mode/key mismatches are rejected. Automatic capture must already be configured in the selected Razorpay account. Live-mode support is a configuration capability, not a claim that real-money processing or a deployment has been validated.
+
+[Setup](#installation-and-configuration) · [Checkout](#storefront-checkout) · [Webhooks](#webhooks) · [Server integration](docs/server-integration.md) · [Operations](docs/operations.md)
+
+## Supported payment lifecycle
+
+| Capability            | Behavior                                                                                                                                                                                                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Payment sessions      | Creates a Razorpay order from the server-provided Medusa amount, with precise rupee-to-paise conversion and a native session association.                                                                                                                                                              |
+| Checkout verification | Verifies the signature, fetched payment and order, amount, INR currency and session association before accepting payment.                                                                                                                                                                              |
+| Automatic capture     | Requires captured gateway funds before authorization completes. Native capture verifies gateway state and never sends another capture request.                                                                                                                                                         |
+| Failed attempts       | Allows another attempt on the same order after the previous bound attempt has failed. Successful or in-progress associations cannot silently be replaced.                                                                                                                                              |
+| Cancellation          | Cancels/deletes an unpaid session locally; rejects cancellation when gateway payment is authorized or captured. It does not cancel a Razorpay order or issue an implicit refund.                                                                                                                       |
+| Refunds               | Full and partial normal-speed refunds, minimum INR 1.00, with a stable native operation key sent through Razorpay's idempotent refund API.                                                                                                                                                             |
+| Payment webhooks      | Signed `payment.authorized` and `payment.captured` events re-fetch gateway state; native processing proceeds only after capture.                                                                                                                                                                       |
+| Refund observation    | Signed refund events trigger authenticated current-state checks through optional application wiring. The optional importer records verified processed Dashboard and deferred native refunds in native accounting without sending funds again. Pending/failed refunds do not create accounting entries. |
+
+The declared framework peer versions are **2.22.2 and 2.22.4**. Native application validation targets Medusa 2.22.2; package development uses 2.22.4. This repository provides a payment module provider and server helpers. Checkout UI, customer authorization, terms acceptance, order-completion policy and infrastructure belong to the consuming application.
+
+## Installation and configuration
+
+For source installation, use a reviewed full commit SHA and commit your application's lockfile:
+
+```sh
+npm install 'git+https://github.com/abhi1693/medusa-payment-razorpay.git#<reviewed-full-commit-sha>'
+```
+
+Git installation runs the package's TypeScript build through its `prepare` script. Your build environment needs Git, Node.js and the declared peer dependency. The repository's Docker toolchain uses Node.js 24.
+
+Add the provider to your existing Payment Module configuration in `medusa-config.ts`:
+
+```ts
+{
+  resolve: "@medusajs/medusa/payment",
+  options: {
+    providers: [
+      // Keep your other payment providers here.
+      {
+        resolve: "@abhi1693/medusa-payment-razorpay",
+        id: "razorpay",
+        options: {
+          mode: process.env.RAZORPAY_MODE,
+          key_id: process.env.RAZORPAY_KEY_ID,
+          key_secret: process.env.RAZORPAY_KEY_SECRET,
+          webhook_secret: process.env.RAZORPAY_WEBHOOK_SECRET,
+        },
+      },
+    ],
+  },
+}
+```
+
+Configure the backend's private environment:
+
+```dotenv
+RAZORPAY_MODE=test
+RAZORPAY_KEY_ID=rzp_test_REPLACE_ME
+RAZORPAY_KEY_SECRET=REPLACE_ME
+RAZORPAY_WEBHOOK_SECRET=REPLACE_ME
+```
+
+These are placeholders. Never commit actual credentials or expose the secret or webhook secret to a frontend. The key ID is public checkout configuration. Set `mode` explicitly to `test` or `live`: the key ID must begin with the matching `rzp_test_` or `rzp_live_` prefix and a nonempty API secret is required. Missing/unknown modes, malformed IDs and mismatches fail before network access; the plugin never infers live mode from a key. This validates configuration shape, not whether the key/secret pair is valid at Razorpay.
+
+For live configuration, use `RAZORPAY_MODE=live`, a matching live key ID and that environment's API and webhook secrets. **Live provider initialization requires a nonempty webhook secret.** Test mode may omit it for initial Admin setup, but webhook delivery always fails closed without a valid secret. Use separate deployments/data, credentials and webhook endpoints/secrets for test and live; do not switch an existing test database into live processing. See [account modes](docs/operations.md#account-modes).
+
+Start the backend through your application's normal workflow. In **Admin → Settings → Regions → your region**, select the Razorpay payment provider. This registration produces provider ID **`pp_razorpay_razorpay`**. Registration alone does not associate it with a region. There is no enabled/disabled environment toggle and no custom Admin menu or plugin migration.
+
+## Storefront checkout
+
+1. Create/select a native Medusa payment session using `pp_razorpay_razorpay`.
+2. Initialize Razorpay Checkout using the session's public `key_id`, `order_id`, `amount` (paise) and `currency` (`INR`).
+3. Submit `razorpay_order_id`, `razorpay_payment_id` and `razorpay_signature` through Medusa's Store payment-session client-data endpoint (`data.client`). Keep the stored server session fields authoritative.
+4. Complete the cart through your backend's normal ownership, cart-total and acceptance checks. While automatic capture is pending, wait/reconcile rather than treating authorization as a completed payment.
+
+The provider includes no checkout widget and makes no blanket promise about individual Razorpay payment methods. Available methods depend on the merchant account and Checkout configuration. Enforce application rules on the server: native payment webhooks may complete carts without the browser returning.
+
+## Webhooks
+
+For the example registration above, use your **backend's public HTTPS origin** with:
+
+```text
+/hooks/payment/razorpay_razorpay
+```
+
+Subscribe to `payment.authorized` and `payment.captured` in the matching Razorpay account and mode. Preserve the exact raw request bytes and `x-razorpay-signature` header. The provider verifies HMAC signatures and fetches current gateway state, making repeated and out-of-order notifications safe to re-evaluate. `payment.failed` and other unsupported payment events are ignored; they do not invalidate a later checkout attempt.
+
+For refund observation, also subscribe to `refund.created`, `refund.processed`, `refund.failed` and `refund.speed_changed`, and wire the exported server helpers into an application subscriber. These events require an application subscriber calling the importer; provider registration alone does not import accounting. A speed change updates informational observations only; it never means settlement or initiates a refund.
+
+See [server integration](docs/server-integration.md) for the helper contract, shared locking hook and subscriber requirements. Use durable Medusa event infrastructure and monitor failed jobs; HTTP acknowledgement is not proof of successful reconciliation.
+
+## Refunds and reconciliation
+
+Initiate refunds through Medusa's native refund workflow and preserve the operation identity. A synchronously processed response completes normally. A pending gateway response returns an explanatory conflict and remains outside successful native refund accounting. Wire the signed refund subscriber below: a later processed event imports one successful native refund, while a later failed event creates no successful refund accounting. The original native failed attempt remains as audit evidence; it does not mean the gateway request failed. Do not issue a new operation merely to retry a pending request. `last_refund_initial_status` is an immutable processed-response snapshot, not proof of bank receipt.
+
+The exported reconciliation helpers compare authenticated gateway payment/order/refund information with native records. The read-only report helpers never change records. The optional importer uses native financial APIs only for individually verified processed Dashboard and deferred native refunds and rejects ambiguous associations. Review discrepancies before retrying an uncertain request. Applications can supply a `refund_guard` and a common distributed lock covering the session and its associated order to coordinate refund execution, observation and order completion.
+
+Read [operations and validation](docs/operations.md) for pending/failed refund handling, uncertain outcomes, monitoring and test limits. The exported `assessRazorpayRefundRecovery` and `recoverRazorpayRefund` helpers provide a controlled operator path for supported processed-refund imports, with reviewed snapshots, application-enforced maintenance controls and post-recovery accounting checks. Original pending reservations remain quarantined. Known incomplete canonical accounting requires the operator path; automatic takeover scheduling is disabled.
+
+## Logging
+
+Set provider option `log_level` to `debug`, `info` (default), `warning`, `error`, `critical`, or `none`. Thresholds include the selected level and higher severities. `none` emits no plugin log records. JSON records contain `level`, a clear `message`, and `context`. The simple shared logger uses Medusa's injected logger, with a console fallback. Warning uses the `warn` sink; critical uses `error` while retaining its JSON severity.
+
+All API calls use one typed HTTP client with `get`, `post`, `put`, `patch` and `delete`. Authentication, timeout, parsing, and request/response logging live in its single executor. Callers do not add HTTP logging code or classifications. Request context includes the complete supplied API path (including pagination), method, a local correlation UUID and timing. Paths contain opaque gateway resource IDs; these are included as requested.
+
+Debug records receive the complete request body and provider response, including unknown response keys. There is no provider-field extraction or event-schema framework. Authentication headers are never supplied to the logger. Redaction is intentionally not implemented for the current debugging stage. Raw debug bodies can contain personal or sensitive data. Restrict access and retention, and use test data. Keep live deployments at `info` or higher (or `none`); raw `debug` payloads are not suitable for routine live logging. Authentication headers and configured credentials are not intentionally added to log context; an upstream response or caller-supplied body can still contain sensitive values. Other levels omit request/response bodies.
+
+## Common API client
+
+`RazorpayGateway` takes a named `GatewayOptions` object with explicit `mode`, matching credentials, optional Medusa logger, log level, timeout and injectable `fetch` for isolated testing. The base host is fixed, redirects are rejected, authentication cannot be overridden by custom headers, and timeout is bounded at 15 seconds. Reconciliation uses its GET-only adapter with a 30-second aggregate deadline. The compatibility `request` method delegates to the same executor; plugin internals use explicit verbs.
+
+`GatewayRequestError` has typed method, failure kind and optional HTTP status. Transport failures are generic; response errors remain distinct from HTTP errors. No HTTP method retries automatically. `reconciliation_required` is a precaution on failed writes, not proof of a mismatch or a completed reconciliation. GET failures set it false. A successful HTTP response does not establish refund settlement.
+
+## Development
+
+Run project commands through Docker Compose:
+
+```sh
+docker compose build tools
+docker compose run --rm tools npm run format:check
+docker compose run --rm tools npm run lint
+docker compose run --rm tools npm run typecheck
+docker compose run --rm tools npm test
+docker compose run --rm tools npm run build
+docker compose run --rm tools npm run package:check
+```
+
+Prettier checks the repository, including documentation and configuration; `.editorconfig` and `.prettierrc.json` define the shared editor style. Generated files, private environment files and local scratch files are ignored. To apply formatting to the checkout, use the tools container with the repository mounted at `/plugin` and its image dependencies available, or the Compose bootstrap service after installing development dependencies.
+
+Typecheck validates both the published source and unit tests. The test project matches Vitest's ESM resolution; malformed runtime fixture values remain explicit test boundaries. The scripts under `tests/native` are consuming-Medusa integration fixtures and resolve/run inside that application's isolated test environment, not the standalone unit-test project.
+
+The GitHub workflow runs formatting, lint, typecheck and build as separately visible checks, reusing the Node CI and security workflows from `abhi1693/actions@v1`. Each unit suite runs independently in its own matrix job and uploads JUnit XML. Reproduce a selected suite locally with `docker compose run --rm tools npm test -- tests/http-client.test.ts`. These self-contained suites use mocked gateway/service fixtures and do not perform gateway transactions. Hosted results and consuming-application integration evidence remain separate from local unit checks.
+
+## Rejected refund requests
+
+A refund POST rejected with HTTP 400 raises `RazorpayRefundRejectedError`
+(`invalid_data`, code `razorpay_refund_rejected`). Medusa Admin can show its
+actionable message instead of a generic server error. The message asks operators
+to verify the refund status and available balance before retrying. HTTP 400 alone does not establish insufficient balance.
+Transport failures and other uncertain responses retain reconciliation handling;
+the provider never retries a refund automatically.
+
+## License
+
+[MIT](LICENSE) © Abhimanyu Saharan.

package/dist/amounts.d.ts

@@ -0,0 +1,6 @@
+/** Exact INR accounting conversion; positivity is a caller-specific constraint. */
+export declare function inrMinorUnits(value: unknown, { allowNegative }?: {
+    allowNegative?: boolean;
+}): number;
+/** Use a decimal string at Medusa BigNumberValue boundaries, never float division. */
+export declare function inrMajorUnits(value: number): string;

package/dist/amounts.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inrMinorUnits = inrMinorUnits;
+exports.inrMajorUnits = inrMajorUnits;
+const utils_1 = require("@medusajs/framework/utils");
+/** Exact INR accounting conversion; positivity is a caller-specific constraint. */
+function inrMinorUnits(value, { allowNegative = false } = {}) {
+    if (value === undefined || value === null)
+        throw new Error("Invalid INR amount");
+    const decimal = new utils_1.BigNumber(value).bigNumber;
+    if (!decimal || !decimal.isFinite())
+        throw new Error("Invalid INR amount");
+    const minor = decimal.multipliedBy(100);
+    if (!minor.isInteger() || (!allowNegative && minor.lt(0)))
+        throw new Error("Invalid INR amount");
+    if (minor.abs().gt(Number.MAX_SAFE_INTEGER))
+        throw new Error("INR amount exceeds supported range");
+    return minor.toNumber();
+}
+/** Use a decimal string at Medusa BigNumberValue boundaries, never float division. */
+function inrMajorUnits(value) {
+    if (!Number.isSafeInteger(value))
+        throw new Error("Invalid INR minor amount");
+    const negative = value < 0;
+    const amount = BigInt(Math.abs(value));
+    return ((negative ? "-" : "") +
+        amount / 100n +
+        "." +
+        String(amount % 100n).padStart(2, "0"));
+}

package/dist/configuration.d.ts

@@ -0,0 +1,12 @@
+export type RazorpayMode = "test" | "live";
+export type RazorpayCredentials = {
+    mode: RazorpayMode;
+    key_id: string;
+    key_secret: string;
+};
+/** Require an explicit account mode; never infer live access from a key. */
+export declare function validateRazorpayCredentials<T extends {
+    mode?: unknown;
+    key_id?: unknown;
+    key_secret?: unknown;
+}>(options: T): asserts options is T & RazorpayCredentials;

package/dist/configuration.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRazorpayCredentials = validateRazorpayCredentials;
+const utils_1 = require("@medusajs/framework/utils");
+/** Require an explicit account mode; never infer live access from a key. */
+function validateRazorpayCredentials(options) {
+    if (options.mode !== "test" && options.mode !== "live")
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Razorpay mode must be explicitly set to test or live");
+    if (typeof options.key_id !== "string" ||
+        options.key_id !== options.key_id.trim() ||
+        !new RegExp(`^rzp_${options.mode}_[A-Za-z0-9]+$`).test(options.key_id))
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Razorpay key ID must match the configured mode");
+    if (typeof options.key_secret !== "string" || !options.key_secret.trim())
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Razorpay API secret must be configured privately");
+}

package/dist/financial-coordination.d.ts

@@ -0,0 +1,11 @@
+export type FinancialCoordinator = <T>(sessions: string[], work: () => Promise<T>) => Promise<T>;
+export type SessionOrderAssociation = {
+    session_id: string;
+    order_id: string | null;
+};
+export type FinancialCoordinationDependencies = {
+    resolve: (sessions: string[]) => Promise<SessionOrderAssociation[]>;
+    execute: <T>(keys: string[], work: () => Promise<T>) => Promise<T>;
+};
+/** Trusted server resolver and shared distributed locking are supplied by the app. */
+export declare function createRazorpayCoordinator(dependencies: FinancialCoordinationDependencies): FinancialCoordinator;

package/dist/financial-coordination.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRazorpayCoordinator = createRazorpayCoordinator;
+/** Trusted server resolver and shared distributed locking are supplied by the app. */
+function createRazorpayCoordinator(dependencies) {
+    const associations = async (sessions) => {
+        const rows = await dependencies.resolve([...sessions]);
+        if (rows.length !== sessions.length ||
+            new Set(rows.map((row) => row.session_id)).size !== rows.length ||
+            rows.some((row) => !sessions.includes(row.session_id) ||
+                (row.order_id !== null && !/^order_[A-Za-z0-9]+$/.test(row.order_id))))
+            throw new Error("Incomplete or invalid financial order association");
+        return rows
+            .map(({ session_id, order_id }) => ({ session_id, order_id }))
+            .sort((a, b) => a.session_id.localeCompare(b.session_id));
+    };
+    return async (input, work) => {
+        const sessions = [...new Set(input)].sort();
+        if (!sessions.length ||
+            sessions.some((id) => !/^payses_[A-Za-z0-9]+$/.test(id)))
+            throw new Error("Invalid financial coordination identity");
+        const before = await associations(sessions);
+        const keys = [
+            ...new Set(before.flatMap(({ session_id, order_id }) => [
+                "razorpay:session:" + session_id,
+                ...(order_id ? ["razorpay:order:" + order_id] : []),
+            ])),
+        ].sort();
+        return dependencies.execute(keys, async () => {
+            if (JSON.stringify(before) !== JSON.stringify(await associations(sessions)))
+                throw new Error("Financial order association changed; retry coordination");
+            return work();
+        });
+    };
+}

package/dist/gateway-refund-pending-error.d.ts

@@ -0,0 +1,5 @@
+import { MedusaError } from "@medusajs/framework/utils";
+export declare class GatewayRefundPendingError extends MedusaError {
+    readonly gateway_refund_id: string;
+    constructor(gateway_refund_id: string);
+}

package/dist/gateway-refund-pending-error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayRefundPendingError = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+// A gateway request exists, but native financial accounting must await processing.
+class GatewayRefundPendingError extends utils_1.MedusaError {
+    gateway_refund_id;
+    constructor(gateway_refund_id) {
+        super(utils_1.MedusaError.Types.CONFLICT, "Razorpay refund " +
+            gateway_refund_id +
+            " is pending. Do not issue another refund; signed reconciliation will record it after processing.");
+        this.gateway_refund_id = gateway_refund_id;
+        this.name = "GatewayRefundPendingError";
+    }
+}
+exports.GatewayRefundPendingError = GatewayRefundPendingError;

package/dist/gateway-refund-reconciliation-error.d.ts

@@ -0,0 +1,5 @@
+import { MedusaError } from "@medusajs/framework/utils";
+export declare class GatewayRefundReconciliationError extends MedusaError {
+    readonly gateway_refund_id: string;
+    constructor(gateway_refund_id: string);
+}

package/dist/gateway-refund-reconciliation-error.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayRefundReconciliationError = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+// Existing gateway funds must be adopted by the coordinated native importer,
+// never by restoring a second native attempt after canonical import.
+class GatewayRefundReconciliationError extends utils_1.MedusaError {
+    gateway_refund_id;
+    constructor(gateway_refund_id) {
+        super(utils_1.MedusaError.Types.CONFLICT, "Razorpay refund " +
+            gateway_refund_id +
+            " is already processed. Await signed reconciliation; do not issue another refund.");
+        this.gateway_refund_id = gateway_refund_id;
+        this.name = "GatewayRefundReconciliationError";
+    }
+}
+exports.GatewayRefundReconciliationError = GatewayRefundReconciliationError;

package/dist/gateway.d.ts

@@ -0,0 +1,46 @@
+import { type RazorpayCredentials } from "./configuration";
+import { type LoggerSink, type LogLevel } from "./logger";
+export interface Entity {
+    id: string;
+    amount: number;
+    currency: string;
+    status: string;
+    order_id?: string;
+    payment_id?: string;
+    amount_refunded?: number;
+    notes?: Record<string, string>;
+    receipt?: string;
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type GatewayFailureKind = "http" | "transport" | "response";
+export interface Gateway {
+    get<T>(path: string, timeoutMs?: number): Promise<T>;
+    post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+}
+export interface GatewayOptions extends RazorpayCredentials {
+    logger?: LoggerSink;
+    log_level?: LogLevel;
+    fetch?: typeof fetch;
+    timeout_ms?: number;
+}
+export declare class GatewayRequestError extends Error {
+    readonly method: HttpMethod;
+    readonly kind: GatewayFailureKind;
+    readonly status?: number | undefined;
+    constructor(message: string, method: HttpMethod, kind: GatewayFailureKind, status?: number | undefined);
+}
+export declare class RazorpayGateway implements Gateway {
+    private readonly authorization;
+    private readonly logger;
+    private readonly transport;
+    private readonly timeoutMs;
+    constructor(options: GatewayOptions);
+    get<T>(path: string, timeoutMs?: number): Promise<T>;
+    post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    /** Compatibility adapter; plugin internals use explicit HTTP verbs. */
+    request<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    private execute;
+}

package/dist/gateway.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RazorpayGateway = exports.GatewayRequestError = void 0;
+const configuration_1 = require("./configuration");
+const node_crypto_1 = require("node:crypto");
+const logger_1 = require("./logger");
+class GatewayRequestError extends Error {
+    method;
+    kind;
+    status;
+    constructor(message, method, kind, status) {
+        super(message);
+        this.method = method;
+        this.kind = kind;
+        this.status = status;
+        this.name = "GatewayRequestError";
+    }
+}
+exports.GatewayRequestError = GatewayRequestError;
+class RazorpayGateway {
+    authorization;
+    logger;
+    transport;
+    timeoutMs;
+    constructor(options) {
+        (0, configuration_1.validateRazorpayCredentials)(options);
+        this.timeoutMs = options.timeout_ms ?? 15000;
+        if (!Number.isSafeInteger(this.timeoutMs) ||
+            this.timeoutMs < 1 ||
+            this.timeoutMs > 15000)
+            throw new Error("Invalid Razorpay request timeout");
+        this.authorization =
+            "Basic " +
+                Buffer.from(options.key_id + ":" + options.key_secret).toString("base64");
+        this.logger = (0, logger_1.createLogger)({
+            sink: options.logger,
+            level: options.log_level,
+        });
+        this.transport = options.fetch || ((...args) => globalThis.fetch(...args));
+    }
+    get(path, timeoutMs = this.timeoutMs) {
+        return this.execute("GET", path, undefined, {}, timeoutMs);
+    }
+    post(path, body, headers = {}) {
+        return this.execute("POST", path, body, headers);
+    }
+    put(path, body, headers = {}) {
+        return this.execute("PUT", path, body, headers);
+    }
+    patch(path, body, headers = {}) {
+        return this.execute("PATCH", path, body, headers);
+    }
+    delete(path, headers = {}) {
+        return this.execute("DELETE", path, undefined, headers);
+    }
+    /** Compatibility adapter; plugin internals use explicit HTTP verbs. */
+    request(path, body, headers = {}) {
+        return body === undefined
+            ? this.get(path)
+            : this.post(path, body, headers);
+    }
+    async execute(method, path, body, headers = {}, timeoutMs = this.timeoutMs) {
+        if (!path ||
+            path.startsWith("/") ||
+            path.includes("://") ||
+            path.split("?")[0].split("/").includes(".."))
+            throw new Error("Invalid relative Razorpay API path");
+        const started = Date.now(), context = { method, path, correlation: (0, node_crypto_1.randomUUID)() };
+        let status, payload, rawResponse;
+        const log = (level, message, data = {}) => this.logger[level](message, {
+            ...context,
+            ...data,
+            duration_ms: Math.max(0, Date.now() - started),
+        });
+        const requestFailure = (kind, existing) => {
+            const failure = existing ??
+                new GatewayRequestError(kind === "http"
+                    ? "Razorpay request failed; reconcile gateway state before retrying"
+                    : kind === "response"
+                        ? "Razorpay response invalid; reconcile gateway state before retrying"
+                        : "Razorpay request unavailable; reconcile gateway state before retrying", method, kind, status);
+            const severity = status === 401 || status === 403
+                ? "critical"
+                : status !== undefined && status < 500 && kind === "http"
+                    ? "warning"
+                    : "error";
+            const message = {
+                http: "Razorpay returned an unsuccessful HTTP response",
+                response: "Razorpay returned invalid JSON",
+                transport: "Razorpay transport failed",
+            };
+            log(severity, message[kind], {
+                http_status: status,
+                reconciliation_required: method !== "GET",
+            });
+            return failure;
+        };
+        let response;
+        log("debug", "Sending Razorpay API request", { request: body });
+        try {
+            const requestHeaders = new Headers(headers);
+            requestHeaders.set("Authorization", this.authorization);
+            requestHeaders.set("Content-Type", "application/json");
+            response = await this.transport("https://api.razorpay.com/v1/" + path, {
+                method,
+                headers: requestHeaders,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(Math.ceil(Math.min(this.timeoutMs, Math.max(1, timeoutMs)))),
+                redirect: "error",
+            });
+            status = response.status;
+            rawResponse = await response.text();
+            payload = status === 204 ? undefined : JSON.parse(rawResponse);
+        }
+        catch (error) {
+            const kind = status !== undefined && status >= 400
+                ? "http"
+                : error instanceof SyntaxError
+                    ? "response"
+                    : "transport";
+            throw requestFailure(kind, error instanceof GatewayRequestError ? error : undefined);
+        }
+        finally {
+            if (status !== undefined)
+                log("debug", "Received Razorpay API response", {
+                    http_status: status,
+                    response: payload === undefined ? rawResponse : payload,
+                });
+        }
+        if (!response.ok)
+            throw requestFailure("http");
+        log(method === "GET" ? "debug" : "info", "Razorpay API request completed", {
+            http_status: status,
+        });
+        return payload;
+    }
+}
+exports.RazorpayGateway = RazorpayGateway;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import RazorpayProvider from "./service";
+export { RazorpayProvider };
+export type { Options } from "./service";
+declare const _default: import("@medusajs/types").ModuleProviderExports;
+export default _default;
+export { reconcileRazorpayPayment, gatewayReader } from "./reconciliation";
+export type { ReconciliationOptions, RazorpayReconciliationReport, } from "./reconciliation";
+export { signedRefundEvent, observeRazorpayRefund } from "./refund-observation";
+export type { RefundObservationDependencies } from "./refund-observation";
+export { verify as verifyRazorpayWebhook, verifyRazorpayCheckout, } from "./security";
+export { importRazorpayRefund } from "./refund-import";
+export type { RefundImportOptions } from "./refund-import";
+export { reconcileRazorpayRefund, RAZORPAY_REFUND_RECOVERY_EVENT, REFUND_RECOVERY_DELAY_MS, } from "./refund-recovery";
+export type { RefundRecoveryEvent } from "./refund-recovery";
+export { PendingRefundRecoveryError } from "./refund-recovery-error";
+export { GatewayRefundPendingError } from "./gateway-refund-pending-error";
+export { GatewayRefundReconciliationError } from "./gateway-refund-reconciliation-error";
+export { LOG_LEVELS, validateLogLevel } from "./logger";
+export type { LogLevel } from "./logger";
+export { RazorpayGateway, GatewayRequestError } from "./gateway";
+export { createLogger } from "./logger";
+export type { LoggerSink, PluginLogger, LoggerOptions, LogContext, } from "./logger";
+export type { GatewayOptions, HttpMethod, GatewayFailureKind } from "./gateway";
+export type { GatewayReader } from "./reconciliation";
+export { RazorpayRefundRejectedError } from "./razorpay-refund-rejected-error";
+export { validateRazorpayCredentials } from "./configuration";
+export type { RazorpayMode, RazorpayCredentials } from "./configuration";
+export { createRazorpayCoordinator } from "./financial-coordination";
+export type { FinancialCoordinator, FinancialCoordinationDependencies, SessionOrderAssociation, } from "./financial-coordination";
+export { assessRazorpayRefundRecovery, recoverRazorpayRefund, } from "./operator-recovery";
+export type { RefundRecoveryTarget, RefundRecoveryAssessment, RefundRecoveryControl, } from "./operator-recovery";
+export { OperatorRefundRecoveryRequiredError } from "./operator-recovery-required-error";
+export { createRazorpayRecoveryOptions } from "./operator-configuration";
+export type { RefundRecoveryConfiguration, RefundRecoveryConfigurationFactory, } from "./operator-configuration";

package/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRazorpayRecoveryOptions = exports.OperatorRefundRecoveryRequiredError = exports.recoverRazorpayRefund = exports.assessRazorpayRefundRecovery = exports.createRazorpayCoordinator = exports.validateRazorpayCredentials = exports.RazorpayRefundRejectedError = exports.createLogger = exports.GatewayRequestError = exports.RazorpayGateway = exports.validateLogLevel = exports.LOG_LEVELS = exports.GatewayRefundReconciliationError = exports.GatewayRefundPendingError = exports.PendingRefundRecoveryError = exports.REFUND_RECOVERY_DELAY_MS = exports.RAZORPAY_REFUND_RECOVERY_EVENT = exports.reconcileRazorpayRefund = exports.importRazorpayRefund = exports.verifyRazorpayCheckout = exports.verifyRazorpayWebhook = exports.observeRazorpayRefund = exports.signedRefundEvent = exports.gatewayReader = exports.reconcileRazorpayPayment = exports.RazorpayProvider = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const service_1 = __importDefault(require("./service"));
+exports.RazorpayProvider = service_1.default;
+exports.default = (0, utils_1.ModuleProvider)(utils_1.Modules.PAYMENT, { services: [service_1.default] });
+var reconciliation_1 = require("./reconciliation");
+Object.defineProperty(exports, "reconcileRazorpayPayment", { enumerable: true, get: function () { return reconciliation_1.reconcileRazorpayPayment; } });
+Object.defineProperty(exports, "gatewayReader", { enumerable: true, get: function () { return reconciliation_1.gatewayReader; } });
+var refund_observation_1 = require("./refund-observation");
+Object.defineProperty(exports, "signedRefundEvent", { enumerable: true, get: function () { return refund_observation_1.signedRefundEvent; } });
+Object.defineProperty(exports, "observeRazorpayRefund", { enumerable: true, get: function () { return refund_observation_1.observeRazorpayRefund; } });
+var security_1 = require("./security");
+Object.defineProperty(exports, "verifyRazorpayWebhook", { enumerable: true, get: function () { return security_1.verify; } });
+Object.defineProperty(exports, "verifyRazorpayCheckout", { enumerable: true, get: function () { return security_1.verifyRazorpayCheckout; } });
+var refund_import_1 = require("./refund-import");
+Object.defineProperty(exports, "importRazorpayRefund", { enumerable: true, get: function () { return refund_import_1.importRazorpayRefund; } });
+var refund_recovery_1 = require("./refund-recovery");
+Object.defineProperty(exports, "reconcileRazorpayRefund", { enumerable: true, get: function () { return refund_recovery_1.reconcileRazorpayRefund; } });
+Object.defineProperty(exports, "RAZORPAY_REFUND_RECOVERY_EVENT", { enumerable: true, get: function () { return refund_recovery_1.RAZORPAY_REFUND_RECOVERY_EVENT; } });
+Object.defineProperty(exports, "REFUND_RECOVERY_DELAY_MS", { enumerable: true, get: function () { return refund_recovery_1.REFUND_RECOVERY_DELAY_MS; } });
+var refund_recovery_error_1 = require("./refund-recovery-error");
+Object.defineProperty(exports, "PendingRefundRecoveryError", { enumerable: true, get: function () { return refund_recovery_error_1.PendingRefundRecoveryError; } });
+var gateway_refund_pending_error_1 = require("./gateway-refund-pending-error");
+Object.defineProperty(exports, "GatewayRefundPendingError", { enumerable: true, get: function () { return gateway_refund_pending_error_1.GatewayRefundPendingError; } });
+var gateway_refund_reconciliation_error_1 = require("./gateway-refund-reconciliation-error");
+Object.defineProperty(exports, "GatewayRefundReconciliationError", { enumerable: true, get: function () { return gateway_refund_reconciliation_error_1.GatewayRefundReconciliationError; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "LOG_LEVELS", { enumerable: true, get: function () { return logger_1.LOG_LEVELS; } });
+Object.defineProperty(exports, "validateLogLevel", { enumerable: true, get: function () { return logger_1.validateLogLevel; } });
+var gateway_1 = require("./gateway");
+Object.defineProperty(exports, "RazorpayGateway", { enumerable: true, get: function () { return gateway_1.RazorpayGateway; } });
+Object.defineProperty(exports, "GatewayRequestError", { enumerable: true, get: function () { return gateway_1.GatewayRequestError; } });
+var logger_2 = require("./logger");
+Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_2.createLogger; } });
+var razorpay_refund_rejected_error_1 = require("./razorpay-refund-rejected-error");
+Object.defineProperty(exports, "RazorpayRefundRejectedError", { enumerable: true, get: function () { return razorpay_refund_rejected_error_1.RazorpayRefundRejectedError; } });
+var configuration_1 = require("./configuration");
+Object.defineProperty(exports, "validateRazorpayCredentials", { enumerable: true, get: function () { return configuration_1.validateRazorpayCredentials; } });
+var financial_coordination_1 = require("./financial-coordination");
+Object.defineProperty(exports, "createRazorpayCoordinator", { enumerable: true, get: function () { return financial_coordination_1.createRazorpayCoordinator; } });
+var operator_recovery_1 = require("./operator-recovery");
+Object.defineProperty(exports, "assessRazorpayRefundRecovery", { enumerable: true, get: function () { return operator_recovery_1.assessRazorpayRefundRecovery; } });
+Object.defineProperty(exports, "recoverRazorpayRefund", { enumerable: true, get: function () { return operator_recovery_1.recoverRazorpayRefund; } });
+var operator_recovery_required_error_1 = require("./operator-recovery-required-error");
+Object.defineProperty(exports, "OperatorRefundRecoveryRequiredError", { enumerable: true, get: function () { return operator_recovery_required_error_1.OperatorRefundRecoveryRequiredError; } });
+var operator_configuration_1 = require("./operator-configuration");
+Object.defineProperty(exports, "createRazorpayRecoveryOptions", { enumerable: true, get: function () { return operator_configuration_1.createRazorpayRecoveryOptions; } });