@adonis-agora/payments 0.2.0 → 0.3.0

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

@@ -0,0 +1,135 @@
+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';
+export interface DodoDriverConfig {
+    /** Dodo Payments API key. Defaults to `env.get('DODO_PAYMENTS_API_KEY')`. */
+    apiKey?: string;
+    /**
+     * Currency charges are billed in (lowercase ISO 4217), sent as Dodo's
+     * `billing_currency`. **Required** — Dodo settles in 140+ currencies and bills in
+     * whatever you hand it, so a default would be a guess at the app's country.
+     */
+    currency: string;
+    /**
+     * Use Dodo's test mode (`https://test.dodopayments.com`). Defaults to
+     * `NODE_ENV !== 'production'`. Test and live keys are not interchangeable.
+     */
+    sandbox?: boolean;
+    /**
+     * Default billing-address country (ISO 3166-1 alpha-2) for charges that do not carry
+     * one. Dodo requires a country on every payment; per-charge
+     * `metadata.billingCountry`/`metadata.billing` wins over this. Defaults to
+     * `env.get('DODO_PAYMENTS_BILLING_COUNTRY')`.
+     */
+    billingCountry?: string;
+    /**
+     * Webhook signing key from the dashboard (`whsec_...`). Defaults to
+     * `env.get('DODO_PAYMENTS_WEBHOOK_KEY')`. Required to parse Dodo webhooks.
+     */
+    webhookKey?: string;
+}
+/**
+ * Dodo Payments driver — merchant-of-record billing for SaaS (dodopayments.com), written
+ * against the REST API with `fetch`; the `dodopayments` peer dependency is deliberately
+ * not used.
+ *
+ * Dodo is the legal seller of your digital products: it registers for, calculates and
+ * remits sales tax/VAT worldwide, and pays you net. That is a business arrangement the
+ * library does not model — it only changes which driver you configure.
+ *
+ * The consequence for the driver is that **every charge names a product you created in
+ * Dodo**. There is no amount-only endpoint anywhere in the API, so `charge()` and
+ * `createCheckout()` require a product id, and an arbitrary `amount` is only honored on a
+ * product with Pay What You Want enabled.
+ */
+export declare class DodoDriver implements PaymentsDriver {
+    #private;
+    readonly provider = "dodo";
+    /**
+     * `allowed_payment_method_types` is the field that restricts the hosted checkout, and
+     * Dodo's supported-methods table reaches well past cards: wallets (Apple/Google/Amazon
+     * Pay, Cash App, Revolut Pay, WeChat Pay), bank redirects (iDEAL, Bancontact, EPS,
+     * Multibanco, BLIK, Satispay), direct debit (SEPA, ACH), BNPL (Klarna,
+     * Afterpay/Clearpay, Billie), UPI and Pix. Every one of those now has a **category**
+     * name in the contract, so they stop being unroutable.
+     *
+     * Boleto appears in the raw processor-level enum but not in Dodo's table, so it is not
+     * advertised; `voucher` has no Dodo equivalent at all. Note Dodo's own wording: naming a
+     * method never *guarantees* it — eligibility still depends on the customer's country and
+     * your merchant settings, which is why {@link DodoDriver.#allowedMethods} keeps the card
+     * fallbacks Dodo tells you to keep.
+     */
+    readonly supportedMethods: readonly ["credit_card", "debit_card", "pix", "upi", "wallet", "bank_transfer", "bank_debit", "bnpl", "undefined"];
+    /**
+     * `disputes: false` even though Dodo forwards the whole chargeback lifecycle over
+     * webhooks. The capability gates the *API* half — `findDispute` and
+     * `submitDisputeEvidence` — and Dodo's own dispute reference says evidence "must occur
+     * within this window **through the Dodo dashboard**". There is no representment endpoint
+     * to call, so a driver that claimed one would be lying about the only part that matters.
+     */
+    readonly capabilities: {
+        refunds: boolean;
+        invoices: boolean;
+        subscriptions: boolean;
+        disputes: boolean;
+    };
+    constructor(ctx: EmitInvoiceContext, config: DodoDriverConfig);
+    createCustomer(input: CreateCustomerInput): Promise<Customer>;
+    findCustomer(customerId: string): Promise<Customer | null>;
+    updateCustomer(customerId: string, input: UpdateCustomerInput): Promise<Customer>;
+    /**
+     * `POST /payments` — Dodo marks this endpoint deprecated in favour of checkout sessions,
+     * but it is the only call that hands back a payment id up front, which is what this
+     * contract returns. {@link DodoDriver.createCheckout} uses the newer `/checkouts` route.
+     *
+     * The payment is created **pending**: the response carries a `payment_link` the customer
+     * still has to pay on. Settlement arrives as a `payment.succeeded` webhook.
+     */
+    charge(input: ChargeInput): Promise<Payment>;
+    findPayment(gatewayId: string): Promise<Payment | null>;
+    /**
+     * `POST /refunds` has no top-level amount: a partial refund is expressed per line item
+     * (`items[].item_id` = the product or addon id, plus its own amount), which this
+     * contract's single `amount` cannot address. So a full refund works and a partial one is
+     * refused, rather than quietly refunding everything.
+     *
+     * `options.idempotencyKey` is REFUSED, not ignored: Dodo documents no deduplication
+     * mechanism, so accepting the key would turn a retry guarantee into a second refund.
+     */
+    refund(paymentGatewayId: string, amount?: Money, options?: {
+        idempotencyKey?: string;
+    }): Promise<Refund>;
+    createCheckout(input: CheckoutInput): Promise<CheckoutSession>;
+    createSubscription(input: CreateSubscriptionInput): Promise<Subscription>;
+    /**
+     * Cancelling is a `PATCH`, and Dodo separates the two meanings: `status: 'cancelled'`
+     * ends it now, `cancel_at_next_billing_date: true` lets the paid period run out. There
+     * is no `DELETE /subscriptions/{id}`.
+     */
+    cancelSubscription(subscriptionGatewayId: string, options?: {
+        atPeriodEnd?: boolean;
+    }): Promise<Subscription>;
+    /**
+     * What a customer pays is decided by the product, so the only real change is a plan
+     * switch — `POST /subscriptions/{id}/change-plan`, expressed here as
+     * `metadata.productId`. Everything else in `UpdateSubscriptionInput` that Dodo has no
+     * field for is refused instead of dropped.
+     */
+    updateSubscription(subscriptionGatewayId: string, input: UpdateSubscriptionInput): Promise<Subscription>;
+    findSubscription(gatewayId: string): Promise<Subscription | null>;
+    /**
+     * Dodo issues an invoice per payment (it is the merchant of record, so the invoice is
+     * its own). `invoice_url` on the payment is the PDF, which saves a call to
+     * `GET /invoices/payments/{id}`.
+     */
+    listInvoices(customerId: string): Promise<Invoice[]>;
+    /**
+     * Whether a delivery to `POST /payments/webhook/:provider` can be authenticated.
+     *
+     * `parseWebhook` already refuses without the key — declaring it moves the refusal to boot,
+     * where it is a config error rather than a lost webhook.
+     */
+    get webhookVerification(): WebhookVerificationState;
+    parseWebhook(rawBody: string, headers: Record<string, string | string[] | undefined>): WebhookEvent;
+}
+//# sourceMappingURL=dodo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dodo.d.ts","sourceRoot":"","sources":["../../../src/drivers/dodo.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,OAAO,EACP,KAAK,EACL,OAAO,EACP,MAAM,EACN,YAAY,EACZ,YAAY,EACb,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA0JD;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,YAAW,cAAc;;IAC/C,QAAQ,CAAC,QAAQ,UAAU;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,gBAAgB,qHAUd;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY;;;;;MAA2E;gBASpF,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,gBAAgB;IAiBvD,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkB7D,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAY1D,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsBvF;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA8B5C,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAU7D;;;;;;;;OAQG;IACG,MAAM,CACV,gBAAgB,EAAE,MAAM,EACxB,MAAM,CAAC,EAAE,KAAK,EACd,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GACpC,OAAO,CAAC,MAAM,CAAC;IAoCZ,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAsC9D,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC;IAyC/E;;;;OAIG;IACG,kBAAkB,CACtB,qBAAqB,EAAE,MAAM,EAC7B,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAClC,OAAO,CAAC,YAAY,CAAC;IAgBxB;;;;;OAKG;IACG,kBAAkB,CACtB,qBAAqB,EAAE,MAAM,EAC7B,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,YAAY,CAAC;IA4ClB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAcvE;;;;OAIG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA0B1D;;;;;OAKG;IACH,IAAI,mBAAmB,IAAI,wBAAwB,CAElD;IAED,YAAY,CACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,YAAY;CAuhBhB"}