@adonis-agora/payments 0.2.0 → 0.4.0

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

@@ -0,0 +1,85 @@
+import { type BillingStore, type DisputeListItem, type WebhookEventBreakdownLine } from './billing_store.js';
+export interface BillingHealthOptions {
+    /** Milliseconds an event may sit in `received` before it counts as stuck. Default 15 min. */
+    stuckAfter?: number;
+    /** Milliseconds a `pending` payment may age before it counts as unconfirmed. Default 2 h. */
+    unconfirmedAfter?: number;
+    /** The window `failed` events are counted over. Default 24 h. */
+    failedWithin?: number;
+    /**
+     * How far ahead to look for a dispute whose evidence window is about to close. Default 72 h.
+     *
+     * In milliseconds like every other threshold here, though the store's read takes hours —
+     * the conversion happens once, at the call.
+     */
+    disputeDueWithin?: number;
+    /** The window rejected deliveries are counted over. Default 24 h. */
+    rejectedWithin?: number;
+    /** Overridable clock — the tests pass a fixed instant. Defaults to now. */
+    now?: Date;
+}
+export interface BillingHealthCheck {
+    key: 'stuck_webhooks' | 'failed_webhooks' | 'unconfirmed_payments' | 'disputes_due' | 'open_disputes' | 'rejected_deliveries';
+    label: string;
+    count: number;
+    /** `true` when `count` is zero — every check here is a "should be nothing" check. */
+    healthy: boolean;
+    /** What a non-zero count means, and what to do about it. */
+    hint: string;
+}
+export interface BillingHealth {
+    /** `false` when any check is non-zero — the exit code `payments:health` returns. */
+    healthy: boolean;
+    checkedAt: Date;
+    checks: BillingHealthCheck[];
+    /** Which provider/event pairs make up `failed_webhooks`, worst first. */
+    failures: WebhookEventBreakdownLine[];
+    /**
+     * The disputes behind `disputes_due`, soonest deadline first — WHICH windows are closing,
+     * not just how many. Capped at {@link DISPUTE_DEADLINE_SAMPLE}; `disputes_due.count` is the
+     * full number, so a report can name twenty and still say there are fifty.
+     */
+    deadlines: DisputeListItem[];
+    /**
+     * The disputes behind `open_disputes`, OLDEST first — the ones nobody has answered, whether or
+     * not a deadline was ever published for them. Capped at {@link OPEN_DISPUTE_SAMPLE}.
+     *
+     * Overlaps `deadlines` on purpose: a dispute that has both a deadline and no answer belongs in
+     * both lists, and suppressing it from one of them to keep them disjoint would make the
+     * deadline-free check quietly incomplete on exactly the install it exists for.
+     */
+    openDisputes: DisputeListItem[];
+}
+/**
+ * The six operational questions about a billing install that nothing else answers, asked
+ * through the store instead of by hand against the tables.
+ *
+ * Each is a silent failure — the kind where the endpoint keeps returning `200` and revenue
+ * quietly stops landing:
+ *
+ * - **Stuck events**: claimed in the ledger, never finished. Almost always the worker the
+ *   dispatcher depends on (`durable:work` / `queue:listen`) is not running.
+ * - **Failed events**: the handler threw and retries were exhausted, so the effect that
+ *   event described — the grant, the activation — never happened.
+ * - **Unconfirmed charges**: created and never confirmed. This is what a webhook endpoint
+ *   that stopped being reachable looks like from the inside, and nothing errors.
+ * - **Closing dispute windows**: an open chargeback whose evidence deadline is inside the
+ *   next three days. This is the only check here that alerts on a CLOCK rather than on a
+ *   failure — nothing is broken, and the money is lost anyway if the window closes
+ *   unanswered, by default rather than on the merits.
+ * - **Open disputes**: the same money, without the clock. `disputes_due` can only ever see a
+ *   dispute whose gateway PUBLISHED a deadline, and most do not — Asaas' comes from
+ *   `chargeback.deadlineToSendDisputeDocuments`, which no published webhook example contains.
+ *   On such an install the deadline check is zero forever while a chargeback sits open with the
+ *   money already pulled back, and the report says healthy. This one asks the question the
+ *   deadline cannot.
+ * - **Rejected deliveries**: gateway calls the endpoint REFUSED — a bad signature, an unparsable
+ *   body, a provider nobody configured. They never become ledger rows, so a rotated webhook
+ *   token used to look exactly like a quiet week: zero events, zero failures, every check green.
+ *   `unconfirmed_payments` eventually notices, but only for charges the app itself created;
+ *   refunds, chargebacks and dispute closures produce no pending payment and simply vanish.
+ *
+ * Pure store reads, no gateway calls — safe to run on a schedule and to alert on.
+ */
+export declare function billingHealth(store: BillingStore, options?: BillingHealthOptions): Promise<BillingHealth>;
+//# sourceMappingURL=billing_health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing_health.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_health.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAkC5B,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EACC,gBAAgB,GAChB,iBAAiB,GACjB,sBAAsB,GACtB,cAAc,GACd,eAAe,GACf,qBAAqB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC;;;;OAIG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B;;;;;;;OAOG;IACH,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CA6FxB"}

package/dist/src/billing/billing_health.js

@@ -0,0 +1,155 @@
+import { AUDIT_ACTIONS, } from './billing_store.js';
+/** 15 minutes — an event claimed but unfinished for longer is not slow, it is abandoned. */
+const DEFAULT_STUCK_AFTER = 15 * 60 * 1000;
+/** 2 hours — every gateway confirms or fails a charge well inside this. */
+const DEFAULT_UNCONFIRMED_AFTER = 2 * 60 * 60 * 1000;
+/** 24 hours — the window failures are counted over. */
+const DEFAULT_FAILED_WITHIN = 24 * 60 * 60 * 1000;
+/**
+ * 72 hours — how far ahead a closing evidence window is worth shouting about.
+ *
+ * Gateways give between 7 and 21 days to respond, so three days is late enough that the
+ * check is not permanently red and early enough that somebody can still gather a receipt, a
+ * delivery confirmation and an IP log before the window shuts. Past-due disputes stay
+ * counted: the window closing is what makes it urgent, not what makes it finished.
+ */
+const DEFAULT_DISPUTE_DUE_WITHIN = 72 * 60 * 60 * 1000;
+/**
+ * 24 hours — the window rejected deliveries are counted over.
+ *
+ * A rejection is not a slow-burning condition like a stuck event: a rotated webhook token, a
+ * secret that never made it into the deploy, a gateway pointed at the wrong route, all produce
+ * rejections immediately and continuously. A day is long enough to survive a redeploy and short
+ * enough that the number means "right now".
+ */
+const DEFAULT_REJECTED_WITHIN = 24 * 60 * 60 * 1000;
+/** How many closing windows the report NAMES. The count is unbounded; this is the list. */
+const DISPUTE_DEADLINE_SAMPLE = 20;
+/** How many open disputes the report NAMES, oldest first. The count is unbounded. */
+const OPEN_DISPUTE_SAMPLE = 20;
+/**
+ * The six operational questions about a billing install that nothing else answers, asked
+ * through the store instead of by hand against the tables.
+ *
+ * Each is a silent failure — the kind where the endpoint keeps returning `200` and revenue
+ * quietly stops landing:
+ *
+ * - **Stuck events**: claimed in the ledger, never finished. Almost always the worker the
+ *   dispatcher depends on (`durable:work` / `queue:listen`) is not running.
+ * - **Failed events**: the handler threw and retries were exhausted, so the effect that
+ *   event described — the grant, the activation — never happened.
+ * - **Unconfirmed charges**: created and never confirmed. This is what a webhook endpoint
+ *   that stopped being reachable looks like from the inside, and nothing errors.
+ * - **Closing dispute windows**: an open chargeback whose evidence deadline is inside the
+ *   next three days. This is the only check here that alerts on a CLOCK rather than on a
+ *   failure — nothing is broken, and the money is lost anyway if the window closes
+ *   unanswered, by default rather than on the merits.
+ * - **Open disputes**: the same money, without the clock. `disputes_due` can only ever see a
+ *   dispute whose gateway PUBLISHED a deadline, and most do not — Asaas' comes from
+ *   `chargeback.deadlineToSendDisputeDocuments`, which no published webhook example contains.
+ *   On such an install the deadline check is zero forever while a chargeback sits open with the
+ *   money already pulled back, and the report says healthy. This one asks the question the
+ *   deadline cannot.
+ * - **Rejected deliveries**: gateway calls the endpoint REFUSED — a bad signature, an unparsable
+ *   body, a provider nobody configured. They never become ledger rows, so a rotated webhook
+ *   token used to look exactly like a quiet week: zero events, zero failures, every check green.
+ *   `unconfirmed_payments` eventually notices, but only for charges the app itself created;
+ *   refunds, chargebacks and dispute closures produce no pending payment and simply vanish.
+ *
+ * Pure store reads, no gateway calls — safe to run on a schedule and to alert on.
+ */
+export async function billingHealth(store, options = {}) {
+    const now = options.now ?? new Date();
+    const stuckAfter = options.stuckAfter ?? DEFAULT_STUCK_AFTER;
+    const unconfirmedAfter = options.unconfirmedAfter ?? DEFAULT_UNCONFIRMED_AFTER;
+    const failedWithin = options.failedWithin ?? DEFAULT_FAILED_WITHIN;
+    const disputeDueWithin = options.disputeDueWithin ?? DEFAULT_DISPUTE_DUE_WITHIN;
+    const rejectedWithin = options.rejectedWithin ?? DEFAULT_REJECTED_WITHIN;
+    const since = (ms) => new Date(now.getTime() - ms);
+    // The store's deadline read takes HOURS; every other threshold here is milliseconds.
+    const withinHours = disputeDueWithin / 3_600_000;
+    const [stuck, failed, unconfirmed, failures, disputesDue, deadlines, openDisputeCount, openDisputes, rejected,] = await Promise.all([
+        store.countWebhookEvents({ status: 'received', createdBefore: since(stuckAfter) }),
+        store.countWebhookEvents({ status: 'failed', createdAfter: since(failedWithin) }),
+        store.countPayments({ status: 'pending', createdBefore: since(unconfirmedAfter) }),
+        store.webhookEventBreakdown({ status: 'failed', createdAfter: since(failedWithin) }),
+        // Counted separately from the list, and unbounded: a count taken from a capped page
+        // saturates at the cap, and this number is what the exit code is decided on.
+        store.countDisputesDueWithin({ withinHours, now }),
+        store.listDisputesDueWithin({ withinHours, now, limit: DISPUTE_DEADLINE_SAMPLE }),
+        // No window and no deadline: an open dispute is unanswered however old it is, and on a
+        // gateway that publishes no deadline this is the ONLY read that can see it at all.
+        store.countOpenDisputes({}),
+        store.listOpenDisputes({ limit: OPEN_DISPUTE_SAMPLE }),
+        store.countAuditEvents({
+            action: AUDIT_ACTIONS.webhookRejected,
+            createdAfter: since(rejectedWithin),
+        }),
+    ]);
+    const checks = [
+        {
+            key: 'stuck_webhooks',
+            label: `Events claimed but unfinished for over ${formatDuration(stuckAfter)}`,
+            count: stuck,
+            healthy: stuck === 0,
+            hint: 'Nothing is consuming the dispatcher. Check that the worker is running (durable:work / queue:listen).',
+        },
+        {
+            key: 'failed_webhooks',
+            label: `Events the dispatcher gave up on in the last ${formatDuration(failedWithin)}`,
+            count: failed,
+            healthy: failed === 0,
+            hint: 'Handlers threw and retries ran out; those events never took effect. Read the errors with listWebhookEvents({ status: "failed" }), fix the cause, then replay them from the gateway dashboard.',
+        },
+        {
+            key: 'unconfirmed_payments',
+            label: `Charges created over ${formatDuration(unconfirmedAfter)} ago and still pending`,
+            count: unconfirmed,
+            healthy: unconfirmed === 0,
+            hint: 'Charges are being created but never confirmed — the shape of a webhook endpoint that stopped being reachable. Check the gateway dashboard delivery log.',
+        },
+        {
+            key: 'disputes_due',
+            label: `Open disputes whose evidence window closes within ${formatDuration(disputeDueWithin)}`,
+            count: disputesDue,
+            healthy: disputesDue === 0,
+            hint: 'A chargeback window is closing. Past it the dispute is lost by default rather than on the merits, and nothing can be done — submit evidence at the gateway, or refund if it is cheaper than the fee. Rows already past their deadline are counted here too: they are still open, and still unanswered.',
+        },
+        {
+            key: 'open_disputes',
+            label: 'Disputes still open and unanswered',
+            count: openDisputeCount,
+            healthy: openDisputeCount === 0,
+            hint: 'A chargeback is open and the money is already out of the account. This check does NOT need a deadline, which is the point: most gateways publish none, and on those installs the deadline check reports zero forever. Answer it at the gateway, then close it here (POST <dashboard>/api/disputes/:gatewayId/resolve) — several gateways never send a lost-dispute event, so nothing else will ever close the row.',
+        },
+        {
+            key: 'rejected_deliveries',
+            label: `Gateway deliveries refused in the last ${formatDuration(rejectedWithin)}`,
+            count: rejected,
+            healthy: rejected === 0,
+            hint: 'The webhook endpoint answered 400: a signature that did not verify, a body it could not parse, or a provider nobody configured. The usual cause is a rotated webhook secret that never reached the deployment — and the deliveries lost that way are invisible everywhere else, because a rejected delivery never becomes a ledger row. Read them with listAuditEvents({ action: "webhook.rejected" }).',
+        },
+    ];
+    return {
+        healthy: checks.every((check) => check.healthy),
+        checkedAt: now,
+        checks,
+        failures,
+        deadlines,
+        openDisputes,
+    };
+}
+/** `900000` reads as nothing in a label; `15m` reads as a threshold. */
+function formatDuration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = minutes / 60;
+    if (hours < 24)
+        return `${trim(hours)}h`;
+    return `${trim(hours / 24)}d`;
+}
+function trim(value) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+//# sourceMappingURL=billing_health.js.map

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

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

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

@@ -15,9 +15,10 @@ export interface BillingOverview {
 }
 /**
  * Compute a billing overview from the store — the data foundation a billing dashboard
- * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue
- * (sum of paid payments), active subscriptions, and usage per meter. Pure store queries
- * (no gateway calls), so it works headless and is trivially testable.
+ * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue —
+ * BOTH gross (`revenue`, the sum of paid payments) and net of refunds (`net_revenue`,
+ * `amount - refunded_amount` over the same rows) — active subscriptions, and usage per meter.
+ * Pure store queries (no gateway calls), so it works headless and is trivially testable.
  */
 export declare function billingOverview(store: BillingStore, options: {
     from: Date;

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

@@ -1 +1 @@
-{"version":3,"file":"billing_overview.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IACjC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAChC,OAAO,CAAC,eAAe,CAAC,CAqB1B"}
+{"version":3,"file":"billing_overview.d.ts","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;IACjC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAChC,OAAO,CAAC,eAAe,CAAC,CA6B1B"}

package/dist/src/billing/billing_overview.js

@@ -1,18 +1,27 @@
 /**
  * Compute a billing overview from the store — the data foundation a billing dashboard
- * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue
- * (sum of paid payments), active subscriptions, and usage per meter. Pure store queries
- * (no gateway calls), so it works headless and is trivially testable.
+ * (Agora dashboard pattern) renders. Aggregates KPIs over a `from`/`to` window: revenue —
+ * BOTH gross (`revenue`, the sum of paid payments) and net of refunds (`net_revenue`,
+ * `amount - refunded_amount` over the same rows) — active subscriptions, and usage per meter.
+ * Pure store queries (no gateway calls), so it works headless and is trivially testable.
  */
 export async function billingOverview(store, options) {
     const { from, to } = options;
-    const [revenue, activeSubscriptions, usage] = await Promise.all([
+    const [revenue, netRevenue, activeSubscriptions, usage] = await Promise.all([
         store.revenue({ from, to }),
+        store.netRevenue({ from, to }),
         store.countActiveSubscriptions(),
         store.usageReport({ from, to }),
     ]);
     const metrics = [
-        { key: 'revenue', label: 'Revenue (cents)', value: revenue },
+        // Two money lines, and the labels are load-bearing. `revenue` was the only one for two
+        // releases, and it is GROSS: a charge that was half refunded counts at its full value in
+        // it. Nothing on the screen said so, so a partial refund was invisible in the console's
+        // headline number. Both figures are legitimate — gross is what was collected, net is what
+        // was kept — and the fix is to publish both under names that cannot be confused, not to
+        // quietly redefine the one apps already read.
+        { key: 'revenue', label: 'Revenue, gross (cents)', value: revenue },
+        { key: 'net_revenue', label: 'Revenue, net of refunds (cents)', value: netRevenue },
         { key: 'active_subscriptions', label: 'Active subscriptions', value: activeSubscriptions },
     ];
     for (const line of usage) {

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

@@ -1 +1 @@
-{"version":3,"file":"billing_overview.js","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAmB,EACnB,OAAiC;IAEjC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9D,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,wBAAwB,EAAE;QAChC,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KAChC,CAAC,CAAC;IAEH,MAAM,OAAO,GAA4B;QACvC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,EAAE;QAC5D,EAAE,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,mBAAmB,EAAE;KAC3F,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,GAAG,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE;YAC1B,KAAK,EAAE,WAAW,IAAI,CAAC,KAAK,EAAE;YAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ;SACrB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"billing_overview.js","sourceRoot":"","sources":["../../../src/billing/billing_overview.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAmB,EACnB,OAAiC;IAEjC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1E,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC3B,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC9B,KAAK,CAAC,wBAAwB,EAAE;QAChC,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KAChC,CAAC,CAAC;IAEH,MAAM,OAAO,GAA4B;QACvC,uFAAuF;QACvF,yFAAyF;QACzF,wFAAwF;QACxF,0FAA0F;QAC1F,wFAAwF;QACxF,8CAA8C;QAC9C,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,OAAO,EAAE;QACnE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,iCAAiC,EAAE,KAAK,EAAE,UAAU,EAAE;QACnF,EAAE,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,mBAAmB,EAAE;KAC3F,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,GAAG,EAAE,SAAS,IAAI,CAAC,KAAK,EAAE;YAC1B,KAAK,EAAE,WAAW,IAAI,CAAC,KAAK,EAAE;YAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ;SACrB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC"}