@adonis-agora/payments 0.2.0 → 0.3.0

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;AAED,eAAe,WAAW,CAAC"}

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 { WatcherContext } from './telescope-sdk.js';
+export { registerPaymentsWatcher } from './register.js';
+export type { RegisteredWatcher, TelescopeRecorder } from './register.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,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/telescope/index.js

@@ -1,2 +1,3 @@
 export { PaymentsWatcher } from './payments_watcher.js';
+export { registerPaymentsWatcher } from './register.js';
 //# sourceMappingURL=index.js.map

package/dist/src/telescope/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telescope/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telescope/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

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

@@ -1,10 +1,16 @@
 import type { WatcherContext } from './telescope-sdk.js';
 /**
  * A payments-specific Telescope watcher: records a typed `payments` entry for every
- * milestone `agora:payments:*` event the library emits (charges, refunds,
- * subscriptions, invoice emission, webhook lifecycle), flattening the event's payload
- * into structured content rather than storing the raw envelope like the generic
- * diagnostics bridge does.
+ * `agora:payments:*` event the library emits — the milestones (charges, refunds,
+ * subscriptions, invoice emission, webhook lifecycle) and the debug events
+ * (`gateway.request*`, `webhook.verification`) — flattening the event's payload into
+ * structured content rather than storing the raw envelope like the generic diagnostics
+ * bridge does.
+ *
+ * Entries are SHAPED, not spread blindly: the fields you scan a timeline by lead
+ * ({@link LEAD_KEYS} — who, which object, what happened, how long), then whatever else
+ * the payload carried, then `ts`. Same family as the other Agora watchers, which is why
+ * the `event` + flattened-payload envelope handling is identical to media's.
  *
  * Zero coupling: payments publishes via the structural `@adonis-agora/diagnostics`
  * emit slot; this subscribes to the same `node:diagnostics_channel` channels — neither

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

@@ -1 +1 @@
-{"version":3,"file":"payments_watcher.d.ts","sourceRoot":"","sources":["../../../src/telescope/payments_watcher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAkBzD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAuBnC,mFAAmF;IACnF,OAAO,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"payments_watcher.d.ts","sourceRoot":"","sources":["../../../src/telescope/payments_watcher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAsEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAenC,mFAAmF;IACnF,OAAO,IAAI,IAAI;CAGhB"}

package/dist/src/telescope/payments_watcher.js

@@ -6,12 +6,72 @@ const RECORDED_EVENTS = [...PAYMENTS_DIAGNOSTIC_EVENTS];
 function paymentsChannelName(event) {
     return `agora:payments:${event}`;
 }
+/**
+ * The fields that lead an entry, in this order — the ones a developer scans a timeline
+ * by. Everything else in the payload follows, unreordered.
+ *
+ * `traceId` is handled separately (it can come from either the envelope or the payload)
+ * and always sits right after `event`.
+ */
+const LEAD_KEYS = [
+    'provider',
+    'gatewayId',
+    'id',
+    'type',
+    'method',
+    'host',
+    'path',
+    'query',
+    'status',
+    'outcome',
+    'scheme',
+    'amount',
+    'currency',
+    'durationMs',
+    'error',
+    'reason',
+];
+/**
+ * Build the entry content: `event`, the correlation id, the {@link LEAD_KEYS} that are
+ * present, then the rest of the payload, then `ts`.
+ *
+ * The trace id can arrive two ways. `@adonis-agora/diagnostics` fills the ENVELOPE's
+ * `traceId` from the host's request-context accessor; payments cannot set that field
+ * (the structural emit slot is `(lib, event, payload)`) so it puts its own webhook-chain
+ * id on the PAYLOAD. The envelope's wins when both are there — it is the host's real
+ * request trace, and correlating to it reaches other libraries too.
+ */
+function shapeContent(envelope) {
+    const payload = envelope.payload ?? {};
+    const traceId = envelope.traceId ?? payload.traceId;
+    const content = { event: envelope.event };
+    if (traceId !== undefined)
+        content.traceId = traceId;
+    for (const key of LEAD_KEYS) {
+        if (payload[key] !== undefined)
+            content[key] = payload[key];
+    }
+    for (const [key, value] of Object.entries(payload)) {
+        if (key === 'traceId' || key in content)
+            continue;
+        content[key] = value;
+    }
+    if (envelope.ts !== undefined)
+        content.ts = envelope.ts;
+    return content;
+}
 /**
  * A payments-specific Telescope watcher: records a typed `payments` entry for every
- * milestone `agora:payments:*` event the library emits (charges, refunds,
- * subscriptions, invoice emission, webhook lifecycle), flattening the event's payload
- * into structured content rather than storing the raw envelope like the generic
- * diagnostics bridge does.
+ * `agora:payments:*` event the library emits — the milestones (charges, refunds,
+ * subscriptions, invoice emission, webhook lifecycle) and the debug events
+ * (`gateway.request*`, `webhook.verification`) — flattening the event's payload into
+ * structured content rather than storing the raw envelope like the generic diagnostics
+ * bridge does.
+ *
+ * Entries are SHAPED, not spread blindly: the fields you scan a timeline by lead
+ * ({@link LEAD_KEYS} — who, which object, what happened, how long), then whatever else
+ * the payload carried, then `ts`. Same family as the other Agora watchers, which is why
+ * the `event` + flattened-payload envelope handling is identical to media's.
  *
  * Zero coupling: payments publishes via the structural `@adonis-agora/diagnostics`
  * emit slot; this subscribes to the same `node:diagnostics_channel` channels — neither
@@ -35,15 +95,7 @@ export class PaymentsWatcher {
                 const envelope = message;
                 if (envelope === null || typeof envelope !== 'object')
                     return;
-                ctx.record({
-                    type: this.type,
-                    content: {
-                        event: envelope.event,
-                        ...(envelope.ts !== undefined ? { ts: envelope.ts } : {}),
-                        ...(envelope.traceId !== undefined ? { traceId: envelope.traceId } : {}),
-                        ...(envelope.payload ?? {}),
-                    },
-                });
+                ctx.record({ type: this.type, content: shapeContent(envelope) });
             };
             subscribe(channel, onMessage);
             this.disposers.push(() => unsubscribe(channel, onMessage));

package/dist/src/telescope/payments_watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"payments_watcher.js","sourceRoot":"","sources":["../../../src/telescope/payments_watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACL,0BAA0B,EAE1B,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,4EAA4E;AAC5E,MAAM,eAAe,GAA8B,CAAC,GAAG,0BAA0B,CAAC,CAAC;AAEnF,iLAAiL;AACjL,SAAS,mBAAmB,CAAC,KAAa;IACxC,OAAO,kBAAkB,KAAK,EAAE,CAAC;AACnC,CAAC;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,UAAU,CAAC;IACV,SAAS,GAAsB,EAAE,CAAC;IAEnD,0FAA0F;IAC1F,QAAQ,CAAC,GAAmB;QAC1B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,wBAAwB,CAAC,eAAe,CAAC,CAAC,CAAC;QAE/D,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAC3C,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAE,EAAE;gBACrC,MAAM,QAAQ,GAAG,OAAqC,CAAC;gBACvD,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ;oBAAE,OAAO;gBAC9D,GAAG,CAAC,MAAM,CAAC;oBACT,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,OAAO,EAAE;wBACP,KAAK,EAAE,QAAQ,CAAC,KAAK;wBACrB,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACzD,GAAG,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACxE,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC;qBAC5B;iBACF,CAAC,CAAC;YACL,CAAC,CAAC;YACF,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,mFAAmF;IACnF,OAAO;QACL,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;IACzD,CAAC;CACF"}
+{"version":3,"file":"payments_watcher.js","sourceRoot":"","sources":["../../../src/telescope/payments_watcher.ts"],"names":[],"mappings":"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"}