@adonis-agora/payments 0.2.0 → 0.4.0

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

@@ -0,0 +1,125 @@
+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 LemonSqueezyDriver} (`payments.lemonsqueezy({ … })`).
+ *
+ * Declared here rather than in `define_config.ts` so the driver module is self-contained;
+ * `define_config.ts` re-exports it alongside the factory.
+ */
+export interface LemonSqueezyDriverConfig {
+    /** Lemon Squeezy API key. Defaults to `env.get('LEMONSQUEEZY_API_KEY')`. */
+    apiKey?: string;
+    /**
+     * The store checkouts and customers are created in. **Required** — every write endpoint
+     * takes a store relationship and Lemon Squeezy accounts can hold several stores, each
+     * with its own currency, so there is nothing sane to pick by default.
+     */
+    storeId: string | number;
+    /**
+     * Signing secret configured on the webhook in the Lemon Squeezy dashboard, used to
+     * verify `X-Signature`. Defaults to `env.get('LEMONSQUEEZY_WEBHOOK_SECRET')`. Required
+     * to parse webhooks — Lemon Squeezy always signs, so there is no unsigned mode.
+     */
+    webhookSecret?: string;
+}
+/**
+ * Lemon Squeezy driver — the v1 REST API on `api.lemonsqueezy.com`.
+ *
+ * Lemon Squeezy is a merchant of record: it is the seller of record on the buyer's
+ * statement, calculates and remits sales tax/VAT worldwide, and pays you out. You sell to
+ * Lemon Squeezy; Lemon Squeezy sells to your customer.
+ *
+ * Two consequences shape this driver. First, there is no server-side charge endpoint at
+ * all — a purchase begins with a hosted checkout, so `charge()` throws and
+ * `createCheckout()` is the entry point. Second, subscriptions are created by a customer
+ * completing a checkout for a subscription variant, never by an API call, so
+ * `createSubscription()` throws too.
+ *
+ * The API is JSON:API (`application/vnd.api+json`), which is unusual enough that the
+ * request helper and every mapper below are written around `data.attributes`.
+ */
+export declare class LemonSqueezyDriver implements PaymentsDriver {
+    #private;
+    readonly provider = "lemonsqueezy";
+    /**
+     * The hosted checkout decides which methods to offer from the buyer's country and the
+     * store's settings, and the API takes no payment-method argument — so `'undefined'`
+     * ("the customer chooses at checkout") is the only honest canonical name. Routing
+     * `credit_card` here is refused by the manager, which is correct: this driver cannot
+     * promise the payment will be a card rather than PayPal.
+     */
+    readonly supportedMethods: readonly ['undefined'];
+    /**
+     * `disputes: false`. Lemon Squeezy has no dispute API and no dispute webhook — see
+     * `#mapWebhookType`. As merchant of record it "typically manages these disputes on
+     * behalf of the seller", so there is nothing here to read and nothing to submit.
+     */
+    readonly capabilities: {
+        refunds: boolean;
+        invoices: boolean;
+        subscriptions: boolean;
+        disputes: boolean;
+    };
+    constructor(_ctx: EmitInvoiceContext, config: LemonSqueezyDriverConfig);
+    createCustomer(input: CreateCustomerInput): Promise<Customer>;
+    findCustomer(customerId: string): Promise<Customer | null>;
+    updateCustomer(customerId: string, input: UpdateCustomerInput): Promise<Customer>;
+    /**
+     * Lemon Squeezy has no endpoint that takes money. As merchant of record it owns the
+     * payment page: the only way to start a purchase is a hosted checkout, so returning a
+     * `Payment` here would report a charge that was never attempted.
+     */
+    charge(_input: ChargeInput): Promise<Payment>;
+    findPayment(gatewayId: string): Promise<Payment | null>;
+    /**
+     * Refunds an **order** (`paymentGatewayId` is an order id, the same id `findPayment`
+     * takes). `amount` is in cents, like everywhere else here; omit it for a full refund.
+     * Renewal charges are subscription invoices with their own ids and their own refund
+     * endpoint — this method does not reach them.
+     *
+     * `options.idempotencyKey` is REFUSED, not ignored: Lemon Squeezy has no deduplication
+     * mechanism, so accepting a key would turn a retry guarantee into a second refund.
+     */
+    refund(paymentGatewayId: string, amount?: Money, options?: {
+        idempotencyKey?: string;
+    }): Promise<Refund>;
+    /**
+     * Creates a hosted checkout for a **variant** — `planId` is a Lemon Squeezy variant id
+     * and is required, because a checkout always sells something from the catalog. Pass
+     * `amount` to override the variant's price (`custom_price`, in cents).
+     */
+    createCheckout(input: CheckoutInput): Promise<CheckoutSession>;
+    /**
+     * Lemon Squeezy's API has no create-subscription endpoint: a subscription exists only
+     * once a customer has completed a checkout for a subscription variant. Anything
+     * returned here would be a subscription Lemon Squeezy has never heard of.
+     */
+    createSubscription(_input: CreateSubscriptionInput): Promise<Subscription>;
+    cancelSubscription(subscriptionGatewayId: string, options?: {
+        atPeriodEnd?: boolean;
+    }): Promise<Subscription>;
+    /**
+     * The only change Lemon Squeezy accepts on a subscription that this contract can carry
+     * is a plan swap, and it is expressed as a variant id — so it is read from
+     * `metadata.variantId`. There is no writable amount (the price belongs to the variant),
+     * no description, and no custom-data field; each is refused rather than dropped.
+     */
+    updateSubscription(subscriptionGatewayId: string, input: UpdateSubscriptionInput): Promise<Subscription>;
+    findSubscription(gatewayId: string): Promise<Subscription | null>;
+    /**
+     * Lists the customer's **orders** — the receipts Lemon Squeezy issues for a purchase.
+     * `GET /v1/orders` and `GET /v1/subscription-invoices` have no customer filter, so this
+     * walks the customer's own `orders` relationship instead. Renewal charges live under
+     * `/v1/subscription-invoices?filter[subscription_id]=…` and are not listed here.
+     */
+    listInvoices(customerId: string): Promise<Invoice[]>;
+    /**
+     * Whether a delivery to `POST /payments/webhook/:provider` can be authenticated.
+     *
+     * `parseWebhook` already refuses without the secret — declaring it moves the refusal to boot.
+     */
+    get webhookVerification(): WebhookVerificationState;
+    parseWebhook(rawBody: string, headers: Record<string, string | string[] | undefined>): WebhookEvent;
+}
+//# sourceMappingURL=lemonsqueezy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lemonsqueezy.d.ts","sourceRoot":"","sources":["../../../src/drivers/lemonsqueezy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,cAAc,CAAC;AAEtB,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;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyGD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IACvD,QAAQ,CAAC,QAAQ,kBAAkB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,YAAI,WAAW,EAAW;IACnD;;;;OAIG;IACH,QAAQ,CAAC,YAAY;QAAK,OAAO;QAAQ,QAAQ;QAAQ,aAAa;QAAQ,QAAQ;MAAU;IAOhG,YAAY,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,wBAAwB,EAarE;IAIK,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8BlE;IAEK,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAU/D;IAEK,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmBtF;IAID;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAMlD;IAEK,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAU5D;IAED;;;;;;;;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,CA4BjB;IAID;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAkEnE;IAID;;;;OAIG;IACG,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CAO/E;IAEK,kBAAkB,CACtB,qBAAqB,EAAE,MAAM,EAC7B,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAClC,OAAO,CAAC,YAAY,CAAC,CAkBvB;IAED;;;;;OAKG;IACG,kBAAkB,CACtB,qBAAqB,EAAE,MAAM,EAC7B,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAyCvB;IAEK,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAUtE;IAID;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAyBzD;IAID;;;;OAIG;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,CAiCd;CAoRF"}