@adonis-agora/payments 0.2.0 → 0.3.0

package/dist/src/billing/schema.js

@@ -0,0 +1,350 @@
+/**
+ * The billing schema, as standalone idempotent functions.
+ *
+ * This is the ecosystem convention — a lib owns its own schema — and it is why
+ * `@adonis-agora/durable` exports `createDurableTables` and `@adonis-agora/authz` exports
+ * `createAuthzTables`. This package did not follow it, and the cost showed up quickly: every
+ * column added after the first release became another migration file with hand-written
+ * `hasColumn` / `hasTable` guards, and an app adopting the library had three files to publish
+ * and run before it could take a single payment.
+ *
+ * Two paths, one DDL. {@link LucidBillingStore} calls {@link createBillingTables} once on
+ * first use (`autoCreateSchema`, on by default), and the published migration stub calls the
+ * SAME function — so the two can never drift, which is the whole reason the DDL lives here
+ * rather than in a stub the store knows nothing about.
+ *
+ * The DDL is portable `rawQuery` (`CREATE TABLE IF NOT EXISTS`) rather than Knex's schema
+ * builder, matching the posture authz takes: it keeps the `@adonisjs/lucid` coupling to the
+ * `rawQuery` surface, and it is idempotent by construction — which is what lets an install
+ * that already ran the old Knex migration call this and have it do nothing.
+ */
+/**
+ * Every table the billing layer owns.
+ *
+ * Deliberately NOT configurable, unlike authz's table names. The models are the source of
+ * truth here (`BillingModels` lets an app swap any of them), and DDL that could name a table
+ * the models do not read is a way to create an empty table beside a missing one. An app that
+ * renames a table swaps the model and writes its own migration.
+ */
+export const BILLING_TABLES = [
+    'billing_customers',
+    'billing_subscriptions',
+    'billing_payments',
+    'billing_webhook_events',
+    'billing_disputes',
+    'billing_usage_events',
+    'billing_audit_events',
+];
+/** Best-effort dialect name; `undefined` when it cannot be read. */
+export function detectDialect(db) {
+    try {
+        const direct = db.dialect?.name;
+        if (typeof direct === 'string' && direct.length > 0)
+            return direct;
+        return db.connection?.()?.dialect?.name;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPostgres(dialect) {
+    return !!dialect && /postgres|pg|redshift/i.test(dialect);
+}
+function isMysql(dialect) {
+    return !!dialect && /mysql|mariadb/i.test(dialect);
+}
+function typesFor(dialect) {
+    if (isPostgres(dialect))
+        return { timestamp: 'TIMESTAMPTZ', json: 'JSONB' };
+    if (isMysql(dialect))
+        return { timestamp: 'DATETIME', json: 'JSON' };
+    // SQLite: no native JSON or timestamp types. It stores both as TEXT and Lucid serializes
+    // on the way in, which is why the models declare `prepare`/`consume` rather than trusting
+    // the column type.
+    return { timestamp: 'DATETIME', json: 'TEXT' };
+}
+/**
+ * Create a secondary index, idempotently.
+ *
+ * Postgres and SQLite take `CREATE INDEX IF NOT EXISTS`. **MySQL does not** — it fails with
+ * a syntax error — so there the statement is attempted and a duplicate-name error is
+ * swallowed. That is narrower than it looks: the only way this statement fails on a second
+ * run is that the index is already there, which is the outcome asked for. Any other failure
+ * still throws.
+ */
+async function createIndex(db, dialect, name, table, columns) {
+    if (!isMysql(dialect)) {
+        await db.rawQuery(`CREATE INDEX IF NOT EXISTS ${name} ON ${table} (${columns})`);
+        return;
+    }
+    try {
+        await db.rawQuery(`CREATE INDEX ${name} ON ${table} (${columns})`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/duplicate key name|already exists/i.test(message))
+            throw error;
+    }
+}
+/**
+ * Add a column that was introduced AFTER its table shipped, idempotently.
+ *
+ * `CREATE TABLE IF NOT EXISTS` is a no-op on a table that already exists, so it cannot carry
+ * a new column to an install that ran an earlier version. Without this, upgrading the package
+ * would silently leave the old schema in place and the first query naming the new column
+ * would fail — which is the failure mode a library owning its own schema exists to prevent.
+ *
+ * Postgres has `ADD COLUMN IF NOT EXISTS`. SQLite and MySQL do not, so there the statement is
+ * attempted and a duplicate-column error is swallowed: the only way this fails twice is that
+ * the column is already there, which is the outcome asked for. Anything else still throws.
+ */
+async function addColumn(db, dialect, table, column, type) {
+    if (isPostgres(dialect)) {
+        await db.rawQuery(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${column} ${type}`);
+        return;
+    }
+    try {
+        await db.rawQuery(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/duplicate column|already exists/i.test(message))
+            throw error;
+    }
+}
+/**
+ * Create every billing table, idempotently.
+ *
+ * Safe to call from a Lucid migration's `up()`, and safe to call repeatedly at boot — which
+ * is exactly what {@link LucidBillingStore} does when `autoCreateSchema` is on. An install
+ * that already ran the older Knex migrations gets no-ops: every statement is
+ * `IF NOT EXISTS`.
+ *
+ * It also carries columns added AFTER a table shipped — see the block at the end. That is
+ * what makes this a real upgrade path rather than a first-install convenience: an app that
+ * ran the 0.2.0 migration and then upgrades gets the columns the new code reads, without
+ * having to be told to publish and run a second migration.
+ */
+export async function createBillingTables(db) {
+    const dialect = detectDialect(db);
+    const t = typesFor(dialect);
+    const run = (sql) => db.rawQuery(sql);
+    await run(`CREATE TABLE IF NOT EXISTS billing_customers (
+      id VARCHAR(36) PRIMARY KEY,
+      owner_type VARCHAR(255),
+      owner_id VARCHAR(255),
+      gateway_id VARCHAR(255) UNIQUE,
+      provider VARCHAR(255),
+      email VARCHAR(255),
+      name VARCHAR(255),
+      tax_id VARCHAR(255),
+      metadata ${t.json},
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    await run(`CREATE TABLE IF NOT EXISTS billing_subscriptions (
+      id VARCHAR(36) PRIMARY KEY,
+      gateway_id VARCHAR(255) UNIQUE,
+      provider VARCHAR(255),
+      status VARCHAR(255),
+      plan_id VARCHAR(255),
+      customer_id VARCHAR(255),
+      trial_ends_at ${t.timestamp},
+      ends_at ${t.timestamp},
+      payload ${t.json},
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    await run(`CREATE TABLE IF NOT EXISTS billing_payments (
+      id VARCHAR(36) PRIMARY KEY,
+      gateway_id VARCHAR(255) UNIQUE,
+      provider VARCHAR(255),
+      status VARCHAR(255),
+      amount BIGINT,
+      currency VARCHAR(3),
+      customer_id VARCHAR(255),
+      subscription_id VARCHAR(255),
+      external_reference VARCHAR(255),
+      refunded_amount BIGINT,
+      payload ${t.json},
+      paid_at ${t.timestamp},
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    // The key an app actually looks a payment up by — its own order id, not the gateway's. An
+    // unindexed lookup here is a sequential scan on a table that grows with every charge.
+    await run(`CREATE TABLE IF NOT EXISTS billing_webhook_events (
+      id VARCHAR(36) PRIMARY KEY,
+      gateway_event_id VARCHAR(255) UNIQUE,
+      provider VARCHAR(255),
+      type VARCHAR(255),
+      status VARCHAR(255),
+      payload ${t.json},
+      normalized ${t.json},
+      error TEXT,
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    await run(`CREATE TABLE IF NOT EXISTS billing_disputes (
+      id VARCHAR(36) PRIMARY KEY,
+      gateway_id VARCHAR(255) UNIQUE,
+      payment_gateway_id VARCHAR(255),
+      provider VARCHAR(255),
+      status VARCHAR(255),
+      reason VARCHAR(255),
+      amount BIGINT,
+      currency VARCHAR(3),
+      evidence_due_by ${t.timestamp},
+      outcome VARCHAR(255),
+      opened_at ${t.timestamp},
+      closed_at ${t.timestamp},
+      payload ${t.json},
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    // The deadline read — open disputes ordered by the window closing soonest — scans exactly
+    // these two columns, in this order.
+    // Added in 0.4.0. A NEW table, not a new column, which is why it needs nothing from the ALTER
+    // block below: `CREATE TABLE IF NOT EXISTS` carries a table to an existing install exactly as
+    // well as to a fresh one. Only columns added to a table that already shipped have the upgrade
+    // problem, and only they belong down there.
+    await run(`CREATE TABLE IF NOT EXISTS billing_audit_events (
+      id VARCHAR(36) PRIMARY KEY,
+      action VARCHAR(255),
+      actor VARCHAR(255),
+      provider VARCHAR(255),
+      subject_type VARCHAR(255),
+      subject_id VARCHAR(255),
+      amount BIGINT,
+      currency VARCHAR(3),
+      message TEXT,
+      metadata ${t.json},
+      created_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    await run(`CREATE TABLE IF NOT EXISTS billing_usage_events (
+      id VARCHAR(36) PRIMARY KEY,
+      subscription_id VARCHAR(255),
+      customer_id VARCHAR(255),
+      meter VARCHAR(255),
+      quantity INTEGER DEFAULT 1,
+      metadata ${t.json},
+      recorded_at ${t.timestamp} NOT NULL,
+      updated_at ${t.timestamp} NOT NULL
+    )`);
+    // ── Columns added after their table shipped ────────────────────────────────────────────
+    //
+    // Placed here, BEFORE the indexes, and the order is load-bearing: an install on an older
+    // version has `billing_payments` without `external_reference`, so `CREATE TABLE IF NOT
+    // EXISTS` skips the table and indexing a column that does not exist yet fails the whole
+    // call. The integration suite caught exactly that, against a real Postgres, on the first
+    // run after this function was written.
+    //
+    // These columns are already declared in the CREATE statements above, so on a FRESH database
+    // every statement here is a no-op. They are repeated as ALTERs for the install that already
+    // has the table — which is what makes this an upgrade path rather than a first-install
+    // convenience.
+    //
+    // Anything added to a CREATE statement from now on belongs here too, on the same day. A
+    // column that exists only above works on every machine that has not shipped yet.
+    // 0.3.0 — the app's own reference on a payment, and the normalized event on the ledger row.
+    await addColumn(db, dialect, 'billing_payments', 'external_reference', 'VARCHAR(255)');
+    await addColumn(db, dialect, 'billing_webhook_events', 'normalized', t.json);
+    // 0.4.0 — how much of a payment has been refunded, in the same integer minor units as
+    // `amount`. A PARTIAL refund had nowhere to be recorded before this, so the only two
+    // options were to overwrite the status with `refunded` (writing off the whole charge) or to
+    // drop the event — and the library dropped it, leaving revenue overstated forever.
+    // `BIGINT`, matching `amount`, so net revenue is one subtraction and never a division.
+    await addColumn(db, dialect, 'billing_payments', 'refunded_amount', 'BIGINT');
+    // ── Indexes ───────────────────────────────────────────────────────────────────────────
+    //
+    // Last, and that is load-bearing twice over. Every table above has to exist, and so does
+    // every column added by the block above — `billing_payments_external_reference_idx` names
+    // a column an older install does not have until that ALTER runs. Getting this wrong fails
+    // the whole call and leaves the schema half-built on every boot; the integration suite
+    // caught both orderings against a real Postgres.
+    await createIndex(db, dialect, 'billing_customers_owner_idx', 'billing_customers', 'owner_type, owner_id');
+    await createIndex(db, dialect, 'billing_subscriptions_customer_idx', 'billing_subscriptions', 'customer_id');
+    await createIndex(db, dialect, 'billing_payments_customer_idx', 'billing_payments', 'customer_id');
+    await createIndex(db, dialect, 'billing_payments_subscription_idx', 'billing_payments', 'subscription_id');
+    await createIndex(db, dialect, 'billing_payments_external_reference_idx', 'billing_payments', 'external_reference');
+    await createIndex(db, dialect, 'billing_disputes_payment_idx', 'billing_disputes', 'payment_gateway_id');
+    await createIndex(db, dialect, 'billing_disputes_deadline_idx', 'billing_disputes', 'status, evidence_due_by');
+    // The two ways the audit trail is read: "what did the endpoint reject in the last day"
+    // (the health check) and "what has anyone done to THIS payment" (the timeline).
+    await createIndex(db, dialect, 'billing_audit_events_action_idx', 'billing_audit_events', 'action, created_at');
+    await createIndex(db, dialect, 'billing_audit_events_subject_idx', 'billing_audit_events', 'subject_type, subject_id');
+    await createIndex(db, dialect, 'billing_usage_subscription_meter_idx', 'billing_usage_events', 'subscription_id, meter');
+    await createIndex(db, dialect, 'billing_usage_customer_meter_idx', 'billing_usage_events', 'customer_id, meter');
+}
+/**
+ * Callbacks that forget a store's memoized "the schema exists" answer.
+ *
+ * A `LucidBillingStore` creates the tables once and caches the promise, so after
+ * {@link dropBillingTables} the store still believes the tables are there and every
+ * subsequent query fails with `relation ... does not exist`. The store registers here so the
+ * drop can tell it otherwise — a Set of callbacks rather than an import, because the store
+ * already imports this module and the reverse would be a cycle.
+ */
+const schemaCacheResets = new Set();
+/**
+ * Register a "forget the cached schema" callback. Returns the unregister function.
+ * Internal — {@link LucidBillingStore} is the only caller.
+ */
+export function registerBillingSchemaCache(reset) {
+    schemaCacheResets.add(reset);
+    return () => {
+        schemaCacheResets.delete(reset);
+    };
+}
+/**
+ * Drop every billing table, newest-dependency-first.
+ *
+ * Only for a migration's `down()` and for tests. There is no auto-drop and there will not be
+ * one: a library that can delete a payments table on a config typo is a library that will.
+ *
+ * Every live store is told to forget its cached schema afterwards, so a store built before
+ * the drop re-creates the tables on its next query instead of querying tables that are gone.
+ */
+export async function dropBillingTables(db) {
+    for (const table of [...BILLING_TABLES].reverse()) {
+        await db.rawQuery(`DROP TABLE IF EXISTS ${table}`);
+    }
+    for (const reset of schemaCacheResets)
+        reset();
+}
+/**
+ * Empty every billing table, keeping the schema.
+ *
+ * What a test suite actually needs between groups, and the reason it is here rather than in
+ * every app: dropping the tables invalidates the store (see above), while leaving the ROWS
+ * in place means one test's webhook ledger deduplicates the next test's event — the
+ * library's own idempotency working perfectly, against the suite. The app that found this
+ * hand-wrote it with a `to_regclass` guard; this is that, dialect-agnostically.
+ *
+ * Order is the reverse of creation, so a foreign key never blocks a delete. `DELETE FROM`
+ * rather than `TRUNCATE`: it is the one statement every dialect here spells the same way,
+ * and these tables are test-sized.
+ */
+export async function truncateBillingTables(db) {
+    for (const table of [...BILLING_TABLES].reverse()) {
+        // A table that was never created is not an error to a suite that only wants it empty —
+        // and asking `information_schema` per table per group costs more than the delete does.
+        try {
+            await db.rawQuery(`DELETE FROM ${table}`);
+        }
+        catch (error) {
+            if (!isMissingTableError(error))
+                throw error;
+        }
+    }
+}
+/** Whether a driver error is "that table does not exist" rather than a real failure. */
+function isMissingTableError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (/does not exist|no such table|doesn't exist|Unknown table|Invalid object name/i.test(message) ||
+        // Postgres `undefined_table`, MySQL `ER_NO_SUCH_TABLE`.
+        error?.code === '42P01' ||
+        error?.errno === 1146);
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/billing/schema.js.map

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

package/dist/src/billing/webhook_dispatcher.d.ts

@@ -5,20 +5,19 @@ import type { WebhookProcessor } from './webhook_processor.js';
  *
  * - `durable` — the event is dispatched as a fire-and-forget durable workflow run
  *   (`@adonis-agora/durable`), so processing survives crashes and retries deterministically.
- * - `queue` — the event is dispatched as an `@adonisjs/queue` job (`queueDispatch`).
  * - `in-process` — the event runs inline (awaited); on failure it is retried with
  *   exponential backoff in the background.
  * - `auto` — uses `durable` when its provider is registered, else `queue` when the queue
  *   provider is, else `in-process`.
  */
-export type WebhookDispatchMode = 'durable' | 'queue' | 'in-process' | 'auto';
+export type WebhookDispatchMode = 'durable' | 'in-process' | 'auto';
 export interface WebhookDispatcherOptions {
     processor: WebhookProcessor;
     /**
      * How webhooks are processed. `'auto'` (default) lazily resolves
      * `@adonis-agora/durable` and uses it when installed AND available (the app has the
      * durable provider registered), else `@adonisjs/queue` when available, else
-     * `in-process`. `'durable'`/`'queue'` require their backend (throw when missing).
+     * `in-process`. `'durable'` requires its backend (throws when missing).
      * `'in-process'` never touches either.
      */
     mode?: WebhookDispatchMode;
@@ -41,21 +40,54 @@ export interface WebhookDispatcherOptions {
      */
     durableAvailable?: () => Promise<boolean>;
     /**
-     * Dispatch a webhook event as an `@adonisjs/queue` job. The provider wires this (it owns
-     * the job class, its container binding and the queue-manager registration). Absent =
-     * queue mode is unavailable.
+     * Resolve the app's durable {@link DurableEngineLike}. The provider wires this from the
+     * container; without it there is no engine to register the workflow ON, and durable mode
+     * cannot work — see {@link DurableEngineLike} for why registration is not optional.
      */
-    queueDispatch?: (event: WebhookEvent) => Promise<{
-        jobId?: string;
-    }>;
+    durableEngine?: () => Promise<DurableEngineLike>;
 }
-/** The minimal durable surface we use: a workflow class with a static `dispatch`. */
-export interface DurableWorkflowLike {
-    dispatch(input: {
-        event: WebhookEvent;
-    }): Promise<{
-        runId: string;
-    }>;
+/**
+ * The slice of `@adonis-agora/durable`'s `WorkflowEngine` this needs.
+ *
+ * Both halves are load-bearing. `start` alone is not enough: the engine looks the workflow
+ * up by NAME in its registry and throws `workflow … is not registered` for anything it has
+ * not been told about, so the webhook workflow has to be REGISTERED before the first
+ * dispatch. This class used to build an anonymous `class extends BaseWorkflow` and call its
+ * static `dispatch`, which registers nothing and has no `static workflow = { name }` — so
+ * every delivery threw `workflow class PaymentsWebhookWorkflow has no registered name`, was
+ * collected as a failed event, and the route answered 500. In an app with durable installed
+ * — which is exactly what `'auto'` selects — that was every webhook, forever.
+ */
+export interface DurableEngineLike {
+    register(name: string, version: string, fn: (ctx: unknown, input: never) => Promise<void>): void;
+    start(name: string, input: unknown, runId: string): Promise<unknown>;
+}
+/**
+ * The durable workflow's identity. Stable and explicit: the engine registry is keyed by
+ * name, an in-flight run records the name+version it started on, and a name that changed
+ * between deploys would strand runs mid-flight.
+ */
+export declare const WEBHOOK_WORKFLOW_NAME = "payments-webhook";
+export declare const WEBHOOK_WORKFLOW_VERSION = "1";
+/** One event of a delivery that did not get through, and why. */
+export interface WebhookDeliveryFailure {
+    event: WebhookEvent;
+    error: Error;
+}
+/**
+ * What became of one webhook DELIVERY — which may carry several events (Adyen's
+ * `notificationItems`, Efí's `pix` array).
+ *
+ * The route turns this into the HTTP status: any failure at all means a non-2xx, because
+ * a 2xx is a promise to the gateway that it never has to send this again.
+ */
+export interface WebhookDeliveryResult {
+    /** How many events the delivery carried. */
+    total: number;
+    /** How many were processed (in-process) or accepted by durable/queue. */
+    dispatched: number;
+    /** The ones that threw, in delivery order. Empty on a clean delivery. */
+    failures: WebhookDeliveryFailure[];
 }
 /**
  * Runs webhook events through the {@link WebhookProcessor}. In `auto` mode (the default)
@@ -73,7 +105,54 @@ export declare class WebhookDispatcher {
     dispatch(event: WebhookEvent): Promise<{
         runId?: string;
     }>;
+    /**
+     * Dispatch a whole DELIVERY: one event, or the several a batched envelope carried.
+     *
+     * **The loop lives here, not in the route.** Everything it has to get right — the ledger
+     * claim, the retry policy, which backend runs the work — is already this class's job; the
+     * route's job is to turn the outcome into a status code. It also makes the batch testable
+     * without standing up an HTTP context.
+     *
+     * **Sequential, deliberately.** Two events in one envelope routinely touch the same row
+     * (an Adyen AUTHORISATION and its CAPTURE; a Pix and its devolução), and running them
+     * concurrently would race the ledger claim and the payment upsert against each other,
+     * which is how you get a `paid` row overwritten by the `pending` that preceded it. The
+     * gateway's order is the order the money moved in, so it is the order they run in.
+     *
+     * **One failure does not cancel its siblings.** Event 2 of 4 throwing says nothing about
+     * events 3 and 4 — they are different payments, and refusing to process them because a
+     * neighbour failed loses money for a reason unrelated to them. So every event is attempted
+     * and the failures are COLLECTED. The caller is then responsible for the other half:
+     * reporting a non-2xx so the gateway redelivers, since a 200 tells it the failed one is
+     * done and it is never sent again. The redelivery re-runs only the failed event — the
+     * ledger claims a `failed` row again, while the ones that succeeded answer `null` and skip.
+     */
+    dispatchAll(events: WebhookEvent | WebhookEvent[]): Promise<WebhookDeliveryResult>;
     /** Whether durable-backed processing is active. */
     get mode(): WebhookDispatchMode;
+    /**
+     * Resolve when nothing this dispatcher accepted is still being processed.
+     *
+     * **The asymmetry this fixes.** In `in-process` mode `dispatchAll` resolves when the event
+     * has been PROCESSED, so a test can assert straight after it. In `durable` mode it
+     * resolves when the event has been ACCEPTED — the run executes out of band — so the same
+     * assertion races the workflow. Every app that pairs `billing.dispatcher` with durable
+     * writes the same polling `waitFor(() => ...)` helper to paper over it, and then cannot
+     * write a NEGATIVE assertion at all: "nothing was granted" against a poll is a timed
+     * sleep, which is slow when it passes and lies when the machine is loaded.
+     *
+     * `await dispatcher.flushWebhooks()` is that assertion made possible: after it, an
+     * unchanged row means the webhook genuinely changed nothing.
+     *
+     * It waits for the background in-process RETRIES too, which have exactly the same problem
+     * — the first attempt is awaited and the retries are not.
+     *
+     * Only reaches work this process accepted. A worker-role deployment runs the events in
+     * another process, and no in-process await can see those; the timeout says so rather than
+     * hanging.
+     */
+    flushWebhooks(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
 }
 //# sourceMappingURL=webhook_dispatcher.d.ts.map

package/dist/src/billing/webhook_dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook_dispatcher.d.ts","sourceRoot":"","sources":["../../../src/billing/webhook_dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE;QACR,mDAAmD;QACnD,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,qCAAqC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,uCAAuC;QACvC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,YAAY,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;;gBAUhB,OAAO,EAAE,wBAAwB;IAS7C;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAUhE,mDAAmD;IACnD,IAAI,IAAI,IAAI,mBAAmB,CAE9B;CAkFF"}
+{"version":3,"file":"webhook_dispatcher.d.ts","sourceRoot":"","sources":["../../../src/billing/webhook_dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE;QACR,mDAAmD;QACnD,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,qCAAqC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,uCAAuC;QACvC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;;gBAqBhB,OAAO,EAAE,wBAAwB;IAU7C;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAKhE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA+CxF,mDAAmD;IACnD,IAAI,IAAI,IAAI,mBAAmB,CAE9B;IA8GD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAmBzE"}