@adonis-agora/payments 0.2.0 → 0.4.0

package/dist/src/invoice/invoice_manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoice_manager.d.ts","sourceRoot":"","sources":["../../../src/invoice/invoice_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,yFAAyF;AACzF,qBAAa,cAAc;;gBAGb,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;IAInD,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe;CAqBzC;AAED,kDAAkD;AAClD,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAQvC"}
+{"version":3,"file":"invoice_manager.d.ts","sourceRoot":"","sources":["../../../src/invoice/invoice_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,yFAAyF;AACzF,qBAAa,cAAc;;IAGzB,YAAY,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EAElD;IAED,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAUvC;CAWF;AAED,kDAAkD;AAClD,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAQvC"}

package/dist/src/money.d.ts

@@ -1,11 +1,29 @@
 import type { Money } from './types.js';
+/**
+ * How many decimal places a currency has. Defaults to 2 — the case for every currency not
+ * listed above, including BRL, USD and EUR.
+ */
+export declare function currencyExponent(currency: string | undefined): number;
 /**
  * Money helpers shared by the fetch-based drivers.
  *
- * The billing layer and the `PaymentsDriver` contract work in the currency's smallest
- * unit (cents); the BR gateway APIs (Asaas, AbacatePay, Woovi) work in decimal reais.
- * These two conversions are the only place that mapping lives.
+ * The billing layer and the `PaymentsDriver` contract work in the currency's smallest unit;
+ * many gateway APIs (the Brazilian ones, Mollie, PayPal, Mercado Pago) want a decimal. This
+ * is the only place that mapping lives.
+ *
+ * `currency` is optional so the BRL-only drivers can keep calling these with one argument —
+ * but a **multi-currency** driver that omits it is asking for the ¥ bug above. Prefer
+ * {@link formatDecimal} when the gateway wants a string.
+ */
+export declare function toDecimal(amount: Money, currency?: string): number;
+export declare function fromDecimal(value: number, currency?: string): Money;
+/**
+ * The decimal string a gateway's JSON wants — `"19.90"`, `"1990"`, `"19.900"` — built from
+ * the integer without ever dividing.
+ *
+ * `toDecimal(x).toFixed(2)` goes through a binary float on the way to a decimal string,
+ * which is the classic way to ship `"19.89"`. Shifting the digits of an integer cannot
+ * round anywhere, so this is what drivers should use on the wire.
  */
-export declare function toDecimal(amount: Money): number;
-export declare function fromDecimal(value: number): Money;
+export declare function formatDecimal(amount: Money, currency?: string): string;
 //# sourceMappingURL=money.d.ts.map

package/dist/src/money.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/money.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAE/C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAEhD"}
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/money.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAqCxC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAGnE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAOtE"}

package/dist/src/money.js

@@ -1,14 +1,79 @@
+/**
+ * ISO 4217 minor units, for the currencies where it is not 2.
+ *
+ * Dividing by 100 is right for most of the world and wrong in a way that succeeds for the
+ * rest: a ¥1990 charge sent as `19.90` is accepted by the gateway and bills a hundredth of
+ * what it should. Lowercase keys, because currencies travel lowercase through this package.
+ */
+const MINOR_UNITS = {
+    // Zero-decimal — the amount IS the integer; there is nothing to shift.
+    bif: 0,
+    clp: 0,
+    djf: 0,
+    gnf: 0,
+    isk: 0,
+    jpy: 0,
+    kmf: 0,
+    krw: 0,
+    pyg: 0,
+    rwf: 0,
+    ugx: 0,
+    vnd: 0,
+    vuv: 0,
+    xaf: 0,
+    xof: 0,
+    xpf: 0,
+    // Three-decimal.
+    bhd: 3,
+    iqd: 3,
+    jod: 3,
+    kwd: 3,
+    lyd: 3,
+    omr: 3,
+    tnd: 3,
+};
+/**
+ * How many decimal places a currency has. Defaults to 2 — the case for every currency not
+ * listed above, including BRL, USD and EUR.
+ */
+export function currencyExponent(currency) {
+    if (currency === undefined)
+        return 2;
+    return MINOR_UNITS[currency.toLowerCase()] ?? 2;
+}
 /**
  * Money helpers shared by the fetch-based drivers.
  *
- * The billing layer and the `PaymentsDriver` contract work in the currency's smallest
- * unit (cents); the BR gateway APIs (Asaas, AbacatePay, Woovi) work in decimal reais.
- * These two conversions are the only place that mapping lives.
+ * The billing layer and the `PaymentsDriver` contract work in the currency's smallest unit;
+ * many gateway APIs (the Brazilian ones, Mollie, PayPal, Mercado Pago) want a decimal. This
+ * is the only place that mapping lives.
+ *
+ * `currency` is optional so the BRL-only drivers can keep calling these with one argument —
+ * but a **multi-currency** driver that omits it is asking for the ¥ bug above. Prefer
+ * {@link formatDecimal} when the gateway wants a string.
  */
-export function toDecimal(amount) {
-    return amount / 100;
+export function toDecimal(amount, currency) {
+    const exponent = currencyExponent(currency);
+    return exponent === 0 ? amount : amount / 10 ** exponent;
+}
+export function fromDecimal(value, currency) {
+    const exponent = currencyExponent(currency);
+    return exponent === 0 ? Math.round(value) : Math.round(value * 10 ** exponent);
 }
-export function fromDecimal(value) {
-    return Math.round(value * 100);
+/**
+ * The decimal string a gateway's JSON wants — `"19.90"`, `"1990"`, `"19.900"` — built from
+ * the integer without ever dividing.
+ *
+ * `toDecimal(x).toFixed(2)` goes through a binary float on the way to a decimal string,
+ * which is the classic way to ship `"19.89"`. Shifting the digits of an integer cannot
+ * round anywhere, so this is what drivers should use on the wire.
+ */
+export function formatDecimal(amount, currency) {
+    const exponent = currencyExponent(currency);
+    const negative = amount < 0;
+    const digits = String(Math.abs(Math.trunc(amount))).padStart(exponent + 1, '0');
+    const whole = digits.slice(0, digits.length - exponent);
+    const fraction = exponent === 0 ? '' : `.${digits.slice(digits.length - exponent)}`;
+    return `${negative ? '-' : ''}${whole}${fraction}`;
 }
 //# sourceMappingURL=money.js.map

package/dist/src/money.js.map

@@ -1 +1 @@
-{"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/money.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAa;IACrC,OAAO,MAAM,GAAG,GAAG,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/money.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,GAA2B;IAC1C,uEAAuE;IACvE,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,iBAAiB;IACjB,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;CACP,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA4B;IAC3D,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACrC,OAAO,WAAW,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,MAAa,EAAE,QAAiB;IACxD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,IAAI,QAAQ,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,QAAiB;IAC1D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,IAAI,QAAQ,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAa,EAAE,QAAiB;IAC5D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC;IACpF,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,QAAQ,EAAE,CAAC;AACrD,CAAC"}

package/dist/src/payments_manager.d.ts

@@ -13,6 +13,13 @@ export interface PaymentsManagerOptions {
 export declare class PaymentsManager {
     #private;
     constructor(options: PaymentsManagerOptions);
+    /**
+     * Every configured driver, by the name it was configured under.
+     *
+     * Read-only, and there for the checks that have to look at all of them at once — the
+     * boot-time webhook-verification refusal is the one that needed it.
+     */
+    get drivers(): ReadonlyMap<string, PaymentsDriver>;
     /**
      * Resolve a driver by payment method (e.g. `'pix'`), by provider name, or by the
      * configured default when nothing is given.
@@ -33,7 +40,7 @@ export declare class PaymentsManager {
      * Check a driver capability before delegating, so callers discover the limitation
      * early (e.g. Woovi/OpenPix has no refunds) instead of at the gateway.
      */
-    assertCapability(driver: PaymentsDriver, capability: 'refunds' | 'invoices' | 'subscriptions'): void;
+    assertCapability(driver: PaymentsDriver, capability: 'refunds' | 'invoices' | 'subscriptions' | 'disputes'): void;
 }
 /** Build the driver map from config, resolving every configured factory. */
 export declare function resolveDrivers(config: PaymentsConfig, invoices?: InvoiceManager): Promise<Map<string, PaymentsDriver>>;

package/dist/src/payments_manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payments_manager.d.ts","sourceRoot":"","sources":["../../src/payments_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,eAAe;;gBAMd,OAAO,EAAE,sBAAsB;IAW3C;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,cAAc;IAqBjE;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM;IASrB;;;OAGG;IACH,gBAAgB,CACd,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,eAAe,GACnD,IAAI;CA6BR;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAatC"}
+{"version":3,"file":"payments_manager.d.ts","sourceRoot":"","sources":["../../src/payments_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,eAAe;;IAa1B,YAAY,OAAO,EAAE,sBAAsB,EAS1C;IAED;;;;;OAKG;IACH,IAAI,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAEjD;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,cAAc,CAoChE;IAuGD;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,gDAOpB;IAED;;;OAGG;IACH,gBAAgB,CACd,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,SAAS,GAAG,UAAU,GAAG,eAAe,GAAG,UAAU,GAChE,IAAI,CAgBN;CAsDF;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAatC"}

package/dist/src/payments_manager.js

@@ -1,8 +1,16 @@
+import { PAYMENT_METHOD_NAMES } from './types.js';
 export class PaymentsManager {
     #drivers;
     #invoices;
     #methods;
     #defaultName;
+    /**
+     * Method-bound driver proxies, so repeated `driver('pix')` calls return the same object.
+     * Keyed by `name:method`, not method alone: the proxy closes over the name the routing
+     * check compares against, so caching by method would hand a second provider the first
+     * one's identity.
+     */
+    #boundDrivers = new Map();
     constructor(options) {
         this.#drivers = options.drivers;
         this.#invoices = options.invoices;
@@ -13,6 +21,15 @@ export class PaymentsManager {
         }
         this.#defaultName = options.defaultName ?? names[0];
     }
+    /**
+     * Every configured driver, by the name it was configured under.
+     *
+     * Read-only, and there for the checks that have to look at all of them at once — the
+     * boot-time webhook-verification refusal is the one that needed it.
+     */
+    get drivers() {
+        return this.#drivers;
+    }
     /**
      * Resolve a driver by payment method (e.g. `'pix'`), by provider name, or by the
      * configured default when nothing is given.
@@ -24,7 +41,7 @@ export class PaymentsManager {
      * ```
      */
     driver(methodOrName) {
-        const { name: resolved, method } = this.#resolveName(methodOrName);
+        const { name: resolved, method, unrouted } = this.#resolveName(methodOrName);
         const driver = this.#drivers.get(resolved);
         if (!driver) {
             throw new Error(`[payments] Driver "${resolved}" is not configured. ` +
@@ -37,8 +54,118 @@ export class PaymentsManager {
                 `Supported methods: ${[...driver.supportedMethods].join(', ')}. ` +
                 `Route "${method}" to a different provider in config.methods.`);
         }
+        // Routing picked the provider; it must also reach the charge. Without this the method
+        // is only ever set when the CALLER repeats it — `driver('pix').charge({ method: 'pix' })`
+        // — and every driver that varies by method (Stripe's `payment_method_types`, Asaas' and
+        // AbacatePay's `billingType`) silently fell back to the gateway's dashboard default. A
+        // charge routed as Pix could come back a card.
+        // `resolved` is the CONFIG KEY, not `driver.provider` — `config.methods` is written in
+        // terms of the keys under `config.providers`, and the two differ whenever an app names a
+        // provider something of its own (`providers: { primary: payments.stripe(…) }`). Passing
+        // the driver's own name here made the routing check compare "stripe" against "primary"
+        // and refuse a charge that was routed exactly right.
+        if (method !== undefined)
+            return this.#bound(driver, method, resolved);
+        // `driver()` with no argument used to skip `config.methods` entirely, which is the same
+        // trap one level up: an app that configured pix/credit_card/boleto routing and then
+        // calls `driver()` got a driver bound to NOTHING, and every charge fell back to the
+        // gateway's dashboard default unless the caller happened to repeat `method:`.
+        if (unrouted !== undefined)
+            return this.#unrouted(driver, resolved, unrouted);
+        // (`method === undefined` and no routing map entry: nothing to bind, nothing to check.)
         return driver;
     }
+    /**
+     * The default driver when `config.methods` is configured but this call named no method.
+     *
+     * Three cases, and only the first can be answered silently:
+     *
+     * - **Exactly one method routes here.** The routing is unambiguous, so it is applied — the
+     *   same binding `driver('pix')` would have produced.
+     * - **Several methods route here.** There is no honest answer: `methods` says this provider
+     *   takes pix AND boleto AND card, and picking one would be inventing the charge's payment
+     *   method. The charge is refused with the two ways to say what you meant. It refuses at
+     *   `charge`/`createSubscription` rather than at `driver()`, so the app that already passes
+     *   `method:` on every call — which is what makes this correct today — keeps working
+     *   unchanged.
+     * - **A method is passed that `methods` routes ELSEWHERE.** The routing map and the call
+     *   disagree about where the money goes; that is a config error either way, and running it
+     *   would send a card charge to the provider configured for Pix.
+     */
+    #unrouted(driver, name, candidates) {
+        if (candidates.length === 1) {
+            return this.#bound(driver, candidates[0], name);
+        }
+        return new Proxy(driver, {
+            get: (target, property, _receiver) => {
+                const value = Reflect.get(target, property, target);
+                if (typeof value !== 'function')
+                    return value;
+                if (property !== 'charge' && property !== 'createSubscription') {
+                    return value.bind(target);
+                }
+                // `async`, so the refusal below is a rejected promise rather than a synchronous
+                // throw: every caller of `charge` awaits it, and a sync throw out of an awaited call
+                // skips a `.catch()` the caller reasonably attached.
+                return async (input, ...rest) => {
+                    const method = input?.method;
+                    if (method === undefined) {
+                        throw new Error([
+                            `[payments] driver() resolved "${name}", and config.methods routes`,
+                            `${candidates.join(', ')} to it — so this ${String(property)} has no payment`,
+                            'method and would fall back to whatever the gateway dashboard defaults to.',
+                            `Name it: driver('${candidates[0]}') or`,
+                            `${String(property)}({ method: '${candidates[0]}' }).`,
+                        ].join(' '));
+                    }
+                    this.#assertRoutedHere(method, name, String(property));
+                    return value.call(target, input, ...rest);
+                };
+            },
+        });
+    }
+    /**
+     * The driver, with the routed method filled in on the inputs that carry one.
+     *
+     * A Proxy rather than a hand-written wrapper for one reason: the driver contract has
+     * optional members (`findDispute`, `submitDisputeEvidence`, `capabilities`), and callers
+     * test for them with `typeof driver.x === 'function'`. A wrapper that defines every method
+     * turns "this gateway cannot do that" into "it can, until you call it" — which is the class
+     * of bug this package keeps finding. A Proxy passes absence through as absence.
+     *
+     * Cached per method so `driver('pix') === driver('pix')` still holds. Note that a driver
+     * resolved by NAME is returned untouched: `driver('stripe')` routed nothing, so there is no
+     * method to thread and no reason to wrap.
+     */
+    #bound(driver, method, name) {
+        const cacheKey = `${name ?? driver.provider}:${method}`;
+        const cached = this.#boundDrivers.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const bound = new Proxy(driver, {
+            // An arrow, so `this` is still the manager: the routing check below is its business.
+            get: (target, property, _receiver) => {
+                // Bound to `target`, never to the proxy: driver methods read `#private` fields, and
+                // a proxy is not the instance those belong to.
+                const value = Reflect.get(target, property, target);
+                if (typeof value !== 'function')
+                    return value;
+                if (property !== 'charge' && property !== 'createSubscription') {
+                    return value.bind(target);
+                }
+                return async (input, ...rest) => {
+                    // An explicit method on the input wins. Routing is a default, not an override:
+                    // `driver('pix')` picks the provider, and a caller who then names a method meant it
+                    // — as long as the routing map does not send that method somewhere else.
+                    const chosen = input?.method ?? method;
+                    this.#assertRoutedHere(chosen, name ?? driver.provider, String(property));
+                    return value.call(target, { ...input, method: chosen }, ...rest);
+                };
+            },
+        });
+        this.#boundDrivers.set(cacheKey, bound);
+        return bound;
+    }
     /**
      * Resolve an invoice provider by name (falls back to the configured default). Throws
      * when no invoice provider is configured — a charge with `invoice: true` needs one.
@@ -56,14 +183,26 @@ export class PaymentsManager {
     assertCapability(driver, capability) {
         if (driver.capabilities?.[capability] === false ||
             driver.capabilities?.[capability] === undefined) {
+            // Only the capabilities actually set to `true`. Listing every KEY meant a driver that
+            // spells out `{ invoices: false }` — as the newer ones do — had the capability it was
+            // just refused named back to it as supported.
+            const supported = Object.entries(driver.capabilities ?? {})
+                .filter(([, enabled]) => enabled === true)
+                .map(([name]) => name);
             throw new Error(`[payments] Driver "${driver.provider}" does not support ${capability}. ` +
-                `Supported capabilities: ${Object.keys(driver.capabilities ?? {}).join(', ') || '(none)'}.`);
+                `Supported capabilities: ${supported.join(', ') || '(none)'}.`);
         }
     }
     #resolveName(methodOrName) {
-        if (methodOrName === undefined)
-            return { name: this.#defaultName };
-        // If it names a configured provider, use it directly.
+        if (methodOrName === undefined) {
+            const candidates = this.#methodsRoutedTo(this.#defaultName);
+            return candidates.length > 0
+                ? { name: this.#defaultName, unrouted: candidates }
+                : { name: this.#defaultName };
+        }
+        // If it names a configured provider, use it directly. Naming the provider is an
+        // explicit choice, so `config.methods` is deliberately not consulted — it says which
+        // provider a METHOD goes to, and this call already answered that question.
         if (this.#drivers.has(methodOrName))
             return { name: methodOrName };
         // Otherwise treat it as a payment method and route via config.methods.
@@ -73,7 +212,30 @@ export class PaymentsManager {
             return { name: routed, method };
         // Unknown method/name: throw a helpful error pointing at the routing config.
         const providers = [...this.#drivers.keys()].join(', ') || '(none)';
-        throw new Error(`[payments] "${methodOrName}" is neither a configured provider nor a method routed in config.methods. Configured providers: ${providers}. Known methods: pix, credit_card, debit_card, boleto, undefined.`);
+        throw new Error(`[payments] "${methodOrName}" is neither a configured provider nor a method routed in config.methods. Configured providers: ${providers}. Known methods: ${PAYMENT_METHOD_NAMES.join(', ')}.`);
+    }
+    /**
+     * Refuse a call whose payment method `config.methods` routes to a DIFFERENT provider.
+     *
+     * The routing map and the call disagree about where the money goes. Running it anyway sends
+     * a card charge to the provider configured for Pix — the same class of silence as an
+     * unbound driver, one level up.
+     */
+    #assertRoutedHere(method, name, operation) {
+        const routed = this.#methods[method];
+        if (routed === undefined || routed === name)
+            return;
+        throw new Error([
+            `[payments] config.methods routes "${method}" to "${routed}", but this ${operation} is`,
+            `going to "${name}". Call driver('${method}') to use the routed provider, or name the`,
+            `provider explicitly (driver('${name}')) if the override is deliberate.`,
+        ].join(' '));
+    }
+    /** Which payment methods `config.methods` routes to a given provider. */
+    #methodsRoutedTo(name) {
+        return Object.entries(this.#methods)
+            .filter(([, provider]) => provider === name)
+            .map(([method]) => method);
     }
 }
 /** Build the driver map from config, resolving every configured factory. */

package/dist/src/payments_manager.js.map

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

package/dist/src/services/main.d.ts

@@ -1,6 +1,44 @@
+import type { BillingStore } from '../billing/billing_store.js';
+import type { WebhookDispatcher } from '../billing/webhook_dispatcher.js';
+import type { PaymentsDriver } from '../driver.js';
 import { PaymentsManager } from '../payments_manager.js';
+import type { PaymentMethodName } from '../types.js';
 export declare function getPayments(): PaymentsManager;
+/** The manager if there is one, without the throw — for callers that can handle absence. */
+export declare function findPayments(): PaymentsManager | undefined;
 /** Set by the provider once the manager is built. */
 export declare function setPayments(manager: PaymentsManager): void;
+export declare function getBillingStore(): BillingStore;
+/** The store if there is one, without the throw. */
+export declare function findBillingStore(): BillingStore | undefined;
+/** Set by the provider once the store is resolved. */
+export declare function setBillingStore(store: BillingStore): void;
+export declare function getWebhookDispatcher(): WebhookDispatcher;
+/** The dispatcher if there is one, without throwing — for callers that can do nothing. */
+export declare function findWebhookDispatcher(): WebhookDispatcher | undefined;
+/** Set by the provider once the billing layer is built. */
+export declare function setWebhookDispatcher(dispatcher: WebhookDispatcher | undefined): void;
+/** A {@link PaymentsManager} that resolves on first use. Safe in a field initializer. */
+export declare function lazyPayments(): PaymentsManager;
+/** The billing store, resolved on first use. Safe in a field initializer. */
+export declare function lazyBillingStore(): BillingStore;
+/**
+ * One driver — by method or by provider name — resolved on first use.
+ *
+ * The shape the ecosystem app actually wanted: `private driver = lazyPaymentsDriver('pix')`.
+ * Note the routing is resolved lazily too, so a driver named in `config.methods` does not
+ * have to exist yet when the field is initialized.
+ */
+export declare function lazyPaymentsDriver(methodOrName?: PaymentMethodName | string): PaymentsDriver;
+/**
+ * Forget the resolved singletons.
+ *
+ * Exists for tests: `@adonis-agora/payments/testing`'s `swapPayments()` restores what was
+ * there before, and "before" is legitimately *nothing at all* — the app under test may never
+ * have booted a provider. Without this, a restore had to call `setPayments` with a value it
+ * did not have.
+ */
+export declare function resetPayments(): void;
+export declare function resetBillingStore(): void;
 export default getPayments;
 //# sourceMappingURL=main.d.ts.map

package/dist/src/services/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAQzD,wBAAgB,WAAW,IAAI,eAAe,CAO7C;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAE1D;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAQrD,wBAAgB,WAAW,IAAI,eAAe,CAO7C;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,IAAI,eAAe,GAAG,SAAS,CAE1D;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAE1D;AAWD,wBAAgB,eAAe,IAAI,YAAY,CAO9C;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,IAAI,YAAY,GAAG,SAAS,CAE3D;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEzD;AAWD,wBAAgB,oBAAoB,IAAI,iBAAiB,CAQxD;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,IAAI,iBAAiB,GAAG,SAAS,CAErE;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAEpF;AAmDD,yFAAyF;AACzF,wBAAgB,YAAY,IAAI,eAAe,CAE9C;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,IAAI,YAAY,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,cAAc,CAE5F;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;eAEc,WAAW"}

package/dist/src/services/main.js

@@ -1,3 +1,4 @@
+import { PaymentsManager } from '../payments_manager.js';
 /**
  * Lazy singleton accessor for the payments manager. Set by the provider when it builds
  * the manager; importing this module never triggers the app boot (media/authkit pattern).
@@ -9,9 +10,138 @@ export function getPayments() {
     }
     return payments;
 }
+/** The manager if there is one, without the throw — for callers that can handle absence. */
+export function findPayments() {
+    return payments;
+}
 /** Set by the provider once the manager is built. */
 export function setPayments(manager) {
     payments = manager;
 }
+/**
+ * The billing store the provider resolved from `config.billing.store` — the Lucid
+ * store over the published tables unless the app configured another one.
+ *
+ * `@inject()`-ing `LucidBillingStore` covers the default case; this accessor is what
+ * reaches a **custom** store, which has no class to use as a DI token.
+ */
+let billingStore;
+export function getBillingStore() {
+    if (!billingStore) {
+        throw new Error('[payments] The billing store is not ready yet. Make sure the PaymentsProvider is registered, the app has booted, and `billing.enabled` is not false.');
+    }
+    return billingStore;
+}
+/** The store if there is one, without the throw. */
+export function findBillingStore() {
+    return billingStore;
+}
+/** Set by the provider once the store is resolved. */
+export function setBillingStore(store) {
+    billingStore = store;
+}
+/**
+ * The webhook dispatcher the provider built for this app, when the billing layer is on.
+ *
+ * Published for the same reason as the store: it is built inside the provider from config
+ * nothing else can reconstruct, and tests need to reach it — `flushWebhooks()` in
+ * `@adonis-agora/payments/testing` is the whole reason it is here.
+ */
+let webhookDispatcher;
+export function getWebhookDispatcher() {
+    if (!webhookDispatcher) {
+        throw new Error('[payments] The webhook dispatcher is not ready yet. Make sure the PaymentsProvider is ' +
+            'registered, the app has booted, and `billing.enabled` is not false.');
+    }
+    return webhookDispatcher;
+}
+/** The dispatcher if there is one, without throwing — for callers that can do nothing. */
+export function findWebhookDispatcher() {
+    return webhookDispatcher;
+}
+/** Set by the provider once the billing layer is built. */
+export function setWebhookDispatcher(dispatcher) {
+    webhookDispatcher = dispatcher;
+}
+/**
+ * A stand-in that resolves the real singleton on FIRST PROPERTY ACCESS, not when it is
+ * built.
+ *
+ * `getPayments()` throws until the provider's `booted()` hook runs, and providers that
+ * registered earlier boot first — `@adonis-agora/durable` boots workflows whose services are
+ * constructed before payments has set anything. So `private payments = getPayments()` in a
+ * constructor throws, and every app hits it: the ecosystem app that found this had the SAME
+ * four-line comment copy-pasted into four files explaining why it could not resolve in a
+ * constructor.
+ *
+ * These accessors make the field initializer safe. Nothing is resolved until the service
+ * actually CALLS something, which by definition happens after boot.
+ *
+ * ```ts
+ * export default class GrantAccess {
+ *   #payments = lazyPayments()          // safe in a field initializer
+ *   #store = lazyBillingStore()
+ *   #pix = lazyPaymentsDriver('pix')
+ * }
+ * ```
+ *
+ * `getPayments()`/`getBillingStore()` are unchanged for callers that WANT the eager throw —
+ * a `start/` file asserting the wiring is right is a legitimate use of it.
+ */
+function lazyProxy(resolve, prototype) {
+    // `Object.create(prototype)` rather than `{}`: `instanceof PaymentsManager` and
+    // `Object.getPrototypeOf` then answer what a caller expects, and a Proxy may not lie about
+    // an invariant its target does not have.
+    return new Proxy(Object.create(prototype), {
+        get(_target, property) {
+            const instance = resolve();
+            const value = Reflect.get(instance, property, instance);
+            // Bound to the instance, never to the proxy: these classes read `#private` fields, and
+            // a proxy is not the object those belong to.
+            return typeof value === 'function' ? value.bind(instance) : value;
+        },
+        set(_target, property, value) {
+            return Reflect.set(resolve(), property, value);
+        },
+        has(_target, property) {
+            return Reflect.has(resolve(), property);
+        },
+        getPrototypeOf() {
+            return prototype;
+        },
+    });
+}
+/** A {@link PaymentsManager} that resolves on first use. Safe in a field initializer. */
+export function lazyPayments() {
+    return lazyProxy(getPayments, PaymentsManager.prototype);
+}
+/** The billing store, resolved on first use. Safe in a field initializer. */
+export function lazyBillingStore() {
+    return lazyProxy(getBillingStore, Object.prototype);
+}
+/**
+ * One driver — by method or by provider name — resolved on first use.
+ *
+ * The shape the ecosystem app actually wanted: `private driver = lazyPaymentsDriver('pix')`.
+ * Note the routing is resolved lazily too, so a driver named in `config.methods` does not
+ * have to exist yet when the field is initialized.
+ */
+export function lazyPaymentsDriver(methodOrName) {
+    return lazyProxy(() => getPayments().driver(methodOrName), Object.prototype);
+}
+/**
+ * Forget the resolved singletons.
+ *
+ * Exists for tests: `@adonis-agora/payments/testing`'s `swapPayments()` restores what was
+ * there before, and "before" is legitimately *nothing at all* — the app under test may never
+ * have booted a provider. Without this, a restore had to call `setPayments` with a value it
+ * did not have.
+ */
+export function resetPayments() {
+    payments = undefined;
+}
+export function resetBillingStore() {
+    billingStore = undefined;
+}
 export default getPayments;
 //# sourceMappingURL=main.js.map

package/dist/src/services/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,IAAI,QAAqC,CAAC;AAE1C,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,mHAAmH,CACpH,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,WAAW,CAAC,OAAwB;IAClD,QAAQ,GAAG,OAAO,CAAC;AACrB,CAAC;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/services/main.ts"],"names":[],"mappings":"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"}

package/dist/src/telescope/index.d.ts

@@ -1,3 +1,5 @@
 export { PaymentsWatcher } from './payments_watcher.js';
+export type { RegisteredWatcher, TelescopeRecorder } from './register.js';
+export { registerPaymentsWatcher } from './register.js';
 export type { WatcherContext } from './telescope-sdk.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/telescope/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telescope/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telescope/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}