@adonis-agora/payments 0.2.0 → 0.4.0

package/dist/src/drivers/razorpay.d.ts

@@ -0,0 +1,103 @@
+import type { ChargeInput, CheckoutInput, CreateCustomerInput, CreateSubscriptionInput, PaymentsDriver, UpdateCustomerInput, UpdateSubscriptionInput, WebhookVerificationState } from '../driver.js';
+import type { EmitInvoiceContext } from '../invoice/emit_invoice.js';
+import type { CheckoutSession, Customer, Invoice, Money, Payment, Refund, Subscription, WebhookEvent } from '../types.js';
+/**
+ * Config for {@link RazorpayDriver}.
+ *
+ * Declared here rather than in `define_config.ts` so the driver module type-checks on its
+ * own; `define_config.ts` re-exports it with an `import type`, which is erased at compile
+ * time and therefore keeps the driver lazily loaded.
+ */
+export interface RazorpayDriverConfig {
+    /** Razorpay key id (`rzp_live_…` / `rzp_test_…`). Defaults to `env.get('RAZORPAY_KEY_ID')`. */
+    keyId?: string;
+    /** Razorpay key secret. Defaults to `env.get('RAZORPAY_KEY_SECRET')`. */
+    keySecret?: string;
+    /**
+     * Currency for charges that don't name one (lowercase ISO 4217). **Required** — Razorpay
+     * accepts international currencies alongside INR, so a default here would be a guess at
+     * which country the app bills in, and a wrong guess succeeds silently.
+     */
+    currency: string;
+    /**
+     * Secret of the webhook you configured in the Razorpay dashboard, used to verify
+     * `X-Razorpay-Signature`. Defaults to `env.get('RAZORPAY_WEBHOOK_SECRET')`. When set,
+     * webhooks without a valid signature are rejected.
+     */
+    webhookSecret?: string;
+}
+/**
+ * Razorpay driver — the dominant Indian gateway (UPI, cards, netbanking, wallets) with
+ * native subscription billing. Plain REST over `fetch`, no SDK.
+ *
+ * Two shapes of this API are worth knowing before reading the mappings:
+ *
+ * **Orders, not charges.** Razorpay has no "charge this customer" endpoint for a normal
+ * integration: you create an *order* (an amount you expect to collect) and the payer
+ * settles it in Razorpay Checkout, which produces a *payment* against that order. So
+ * `charge()` creates an order and returns a `pending` payment whose `gatewayId` is the
+ * `order_…` id — the id you hand to Checkout. `findPayment` accepts either id and branches
+ * on the prefix.
+ *
+ * **Authorize then capture.** A Razorpay payment is `authorized` (funds held on the
+ * instrument) before it is `captured` (money moving to you). This package's
+ * `BillingStatus` has no name for that middle state, so `authorized` maps to `pending` —
+ * see {@link RazorpayDriver.capturePayment}.
+ *
+ * Test mode is chosen by the key pair (`rzp_test_…`), not by a different host, so there is
+ * no `sandbox` option: point the driver at test keys and it talks to the test account.
+ */
+export declare class RazorpayDriver implements PaymentsDriver {
+    #private;
+    readonly provider = "razorpay";
+    /**
+     * A Razorpay order carries no payment method — the payer picks card, UPI, netbanking or
+     * a wallet inside Checkout — so `undefined` ("let the customer choose") is the only
+     * honest entry. Routing `methods: { credit_card: 'razorpay' }` therefore fails at the
+     * manager, and it should: nothing in the Orders API can promise a card was used. Read
+     * the method the payer actually chose off `payment.method` on the webhook.
+     */
+    readonly supportedMethods: readonly ['undefined'];
+    readonly capabilities: {
+        refunds: boolean;
+        invoices: boolean;
+        subscriptions: boolean;
+    };
+    constructor(ctx: EmitInvoiceContext, config: RazorpayDriverConfig);
+    createCustomer(input: CreateCustomerInput): Promise<Customer>;
+    findCustomer(customerId: string): Promise<Customer | null>;
+    updateCustomer(customerId: string, input: UpdateCustomerInput): Promise<Customer>;
+    charge(input: ChargeInput): Promise<Payment>;
+    findPayment(gatewayId: string): Promise<Payment | null>;
+    refund(paymentGatewayId: string, amount?: Money, options?: {
+        idempotencyKey?: string;
+    }): Promise<Refund>;
+    /**
+     * Capture an authorized payment — the second half of Razorpay's authorize/capture split.
+     *
+     * Not part of {@link PaymentsDriver}: no other gateway here separates the two, and the
+     * canonical `BillingStatus` has no `authorized` member to hang it off. It is public
+     * because the alternative is worse — an account with auto-capture switched off would have
+     * `pending` payments that this package could never settle, and Razorpay voids an
+     * uncaptured authorization on its own after a few days.
+     *
+     * `amount` must equal the authorized amount; Razorpay rejects a partial capture.
+     */
+    capturePayment(paymentGatewayId: string, amount: Money, currency?: string): Promise<Payment>;
+    createCheckout(input: CheckoutInput): Promise<CheckoutSession>;
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    cancelSubscription(subscriptionGatewayId: string, options?: {
+        atPeriodEnd?: boolean;
+    }): Promise<Subscription>;
+    updateSubscription(subscriptionGatewayId: string, input: UpdateSubscriptionInput): Promise<Subscription>;
+    findSubscription(gatewayId: string): Promise<Subscription | null>;
+    listInvoices(customerId: string): Promise<Invoice[]>;
+    /**
+     * Whether a delivery to `POST /payments/webhook/:provider` can be authenticated.
+     *
+     * Without the secret the `X-Razorpay-Signature` header is never checked.
+     */
+    get webhookVerification(): WebhookVerificationState;
+    parseWebhook(rawBody: string, headers: Record<string, string | string[] | undefined>): WebhookEvent;
+}
+//# sourceMappingURL=razorpay.d.ts.map

package/dist/src/drivers/razorpay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"razorpay.d.ts","sourceRoot":"","sources":["../../../src/drivers/razorpay.ts"],"names":[],"mappings":"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"}