cata-centavo 0.1.0

package/dist/pluggy/transport.js

@@ -0,0 +1,170 @@
+import { classify, parse, readJson } from "./errors.js";
+import { AUTH_RESPONSE } from "./wire.js";
+/**
+ * How early we stop trusting the key. Pluggy's `apiKey` lives two hours, and
+ * expiring at its full lifetime means a token with milliseconds left passes the
+ * check and the request 401s anyway — which is exactly what `pluggy-sdk` does
+ * (`payload.exp <= now` in its `isJwtExpired`). ADR §15 Phase 0.
+ */
+export const KEY_MARGIN_MS = 10 * 60 * 1000;
+/** Used only when the key is not a JWT we can read an `exp` out of. */
+const KEY_FALLBACK_LIFETIME_MS = 2 * 60 * 60 * 1000;
+/**
+ * Disputed: the project spec says 360/min per IP, the prior Go implementation
+ * hardcodes 360 per *hour*, and ADR Phase 0.5 step 4 exists to settle which.
+ * Until it does, this errs high, because guessing too high costs a 429 and a
+ * retry while guessing too low makes the Phase 1 fan-out crawl and look broken.
+ */
+export const RATE_LIMIT = { requests: 360, windowMs: 60_000 };
+/** How many times a 429 is worth waiting out before it becomes the caller's problem. */
+export const RATE_LIMIT_RETRIES = 2;
+/** What Pluggy's `Retry-After` says when it says nothing: their docs always send 60. */
+const RETRY_AFTER_FALLBACK_MS = 60_000;
+const DEFAULT_BASE_URL = "https://api.pluggy.ai";
+/**
+ * Construction performs no I/O. A bad credential has to be reportable by
+ * `init`, and `init` cannot report a condition that already killed the process
+ * (§16.2).
+ */
+export function createTransport(options) {
+    const send = sender(options);
+    const key = keyResolver(options, send);
+    const sleep = options.sleep ?? delay;
+    async function authorized(method, path, body) {
+        let response = await send(method, path, { apiKey: await key(), body });
+        if (response.status === 401) {
+            response = await send(method, path, { apiKey: await key(true), body });
+        }
+        for (let retry = 0; retry < RATE_LIMIT_RETRIES && response.status === 429; retry += 1) {
+            options.log.warn({ method, path, attempt: retry + 1, maxRetries: RATE_LIMIT_RETRIES }, "rate limit response; retrying");
+            await sleep(retryAfterMs(response));
+            response = await send(method, path, { apiKey: await key(), body });
+        }
+        return response;
+    }
+    return { key: () => key(), authorized };
+}
+/**
+ * The single send function. Everything reaching Pluggy passes through here, so
+ * the rate limiter cannot be forgotten by a new endpoint — the bug §16.2 found
+ * wired to two of nine call sites.
+ */
+function sender(options) {
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const limiter = options.limiter ?? slidingWindowLimiter(options.clock);
+    return async (method, path, extras) => {
+        await limiter.acquire();
+        const headers = { "content-type": "application/json" };
+        if (extras.apiKey !== undefined) {
+            headers["X-API-KEY"] = extras.apiKey;
+        }
+        const init = { method, headers };
+        if (extras.body !== undefined) {
+            init.body = JSON.stringify(extras.body);
+        }
+        return options.fetch(`${baseUrl}${path}`, init);
+    };
+}
+/**
+ * The key, resolved lazily per request and cached, guarded by a single-flight so
+ * the account fan-out of §14.1 cannot issue N concurrent `POST /auth`.
+ */
+function keyResolver(options, send) {
+    let key = null;
+    let refreshing = null;
+    async function authenticate() {
+        const response = await send("POST", "/auth", { body: options.credentials });
+        if (!response.ok) {
+            throw classify(response.status, "authenticating");
+        }
+        return parse(AUTH_RESPONSE, await readJson(response), "the /auth response").apiKey;
+    }
+    return async (force = false) => {
+        const now = options.clock.now().getTime();
+        if (!force && key !== null && now < key.expiresAt) {
+            return key.value;
+        }
+        refreshing ??= authenticate()
+            .then((value) => {
+            key = { value, expiresAt: expiryOf(value, now) };
+            return value;
+        })
+            .finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
+}
+function retryAfterMs(response) {
+    const header = response.headers.get("retry-after");
+    let seconds;
+    if (header === null) {
+        seconds = Number.NaN;
+    }
+    else {
+        seconds = Number(header);
+    }
+    if (Number.isFinite(seconds) && seconds > 0) {
+        return seconds * 1000;
+    }
+    return RETRY_AFTER_FALLBACK_MS;
+}
+function expiryOf(token, now) {
+    return (jwtExpiry(token) ?? now + KEY_FALLBACK_LIFETIME_MS) - KEY_MARGIN_MS;
+}
+/** Reads `exp` out of a JWT without a library. Returns null for anything else. */
+function jwtExpiry(token) {
+    const exp = jwtPayload(token)?.["exp"];
+    if (typeof exp === "number") {
+        return exp * 1000;
+    }
+    return null;
+}
+function jwtPayload(token) {
+    const encoded = token.split(".")[1];
+    if (encoded === undefined) {
+        return null;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        if (typeof decoded === "object" && decoded !== null) {
+            return decoded;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const delay = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+/**
+ * Waits rather than rejecting, because a caller that is merely early should not
+ * have to know about the limit.
+ */
+export function slidingWindowLimiter(clock, limit = RATE_LIMIT.requests, windowMs = RATE_LIMIT.windowMs, sleep = delay) {
+    let hits = [];
+    return {
+        acquire: async () => {
+            for (;;) {
+                const now = clock.now().getTime();
+                hits = hits.filter((at) => now - at < windowMs);
+                if (hits.length < limit) {
+                    hits = [...hits, now];
+                    return;
+                }
+                const oldest = hits[0];
+                let waitMs;
+                if (oldest === undefined) {
+                    waitMs = windowMs;
+                }
+                else {
+                    waitMs = oldest + windowMs - now;
+                }
+                await sleep(waitMs);
+            }
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/pluggy/transport.js.map

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

package/dist/pluggy/wire.js

@@ -0,0 +1,207 @@
+import { z } from "zod";
+/**
+ * The raw bodies we read from Pluggy, described rather than assumed.
+ *
+ * We do not reuse the SDK's entity types here, and the reason is specific: they
+ * declare fields like `lastUpdatedAt` as `Date`, which is only true inside the
+ * SDK, where a reviver installed in `got` turns every ISO-8601 string into a
+ * `Date` (`transforms.js`). Parsing the body ourselves, the value is a string
+ * and the type would be lying. Inferring from a schema makes that impossible.
+ *
+ * This is also ADR Phase 0.5 step 5 as code: trust nothing but the raw body.
+ * The prior implementation could never observe that free-tier `category` comes
+ * back null, because its own serializer deleted the evidence first (§16.2).
+ *
+ * Unknown keys are dropped, not rejected. Pluggy adding a field is not our
+ * problem; Pluggy removing one we read is, and that is what these catch.
+ */
+export const AUTH_RESPONSE = z.object({
+    apiKey: z.string().min(1),
+});
+/**
+ * Why `statusDetail` may fall back to nothing rather than failing the parse: it
+ * is a bag keyed by product name, its shape is documented only by example, and
+ * what we read out of it is advisory — which product could not be updated this
+ * time. Losing a whole completed sync to an unexpected key in an advisory field
+ * would be the worse trade. Nothing about the money passes through here.
+ */
+const STATUS_DETAIL = z
+    .record(z.string(), z
+    .object({ warnings: z.array(z.object({ message: z.string() })).nullish() })
+    .nullish())
+    .nullish()
+    .catch(null);
+export const ITEM = z.object({
+    id: z.string().min(1),
+    connector: z.object({ name: z.string() }),
+    status: z.string(),
+    executionStatus: z.string().nullish(),
+    lastUpdatedAt: z.string().nullable(),
+    /** Present when the institution is waiting on a human. */
+    parameter: z.object({ name: z.string(), label: z.string() }).nullish(),
+    statusDetail: STATUS_DETAIL,
+    consecutiveFailedLoginAttempts: z.number().nullish(),
+});
+/**
+ * `GET /consents?itemId=` — the paged envelope of the consent behind one item.
+ *
+ * The consent's own `itemId` deliberately does not enter this schema.
+ * `docs/research/2026-07-26-phase-0-5-recon.md` §"`GET /consents?itemId=`
+ * returns a consent belonging to a different item" found it carries the UUID
+ * of the inner MeuPluggy item — a different one on each of the three
+ * connections observed, none matching a configured id. Reading it only
+ * creates the temptation to join a consent back to our connection by that
+ * field, which would silently produce zero matches. The only reliable
+ * association is "this is what the endpoint returned when asked about that
+ * item".
+ */
+export const CONSENT = z.object({
+    id: z.string().min(1),
+    expiresAt: z.string().nullish(),
+    revokedAt: z.string().nullish(),
+    products: z.array(z.string()).nullish(),
+});
+export const CONSENT_PAGE = z.object({
+    results: z.array(CONSENT),
+    total: z.number(),
+    totalPages: z.number(),
+    page: z.number(),
+});
+export const ACCOUNT = z.object({
+    id: z.string().min(1),
+    itemId: z.string().min(1),
+    type: z.string(),
+    subtype: z.string().nullish(),
+    name: z.string(),
+    marketingName: z.string().nullish(),
+    balance: z.number(),
+    currencyCode: z.string(),
+    creditData: z
+        .object({
+        brand: z.string().nullish(),
+        balanceCloseDate: z.string().nullish(),
+        balanceDueDate: z.string().nullish(),
+        availableCreditLimit: z.number().nullish(),
+        creditLimit: z.number().nullish(),
+        disaggregatedCreditLimits: z
+            .array(z.object({
+            creditLineLimitType: z.string().nullish(),
+            customizedLimitAmount: z.number().nullish(),
+        }))
+            .nullish(),
+    })
+        .nullish(),
+});
+/** Pluggy's offset envelope for `/accounts`. */
+export const ACCOUNT_PAGE = z.object({
+    total: z.number(),
+    totalPages: z.number(),
+    page: z.number(),
+    results: z.array(ACCOUNT),
+});
+const BILL_AMOUNT = z.object({
+    amount: z.number(),
+});
+/** The raw `GET /bills?accountId=` body for one credit-card statement. */
+export const BILL = z.object({
+    id: z.string(),
+    accountId: z.string().optional(),
+    billClosingDate: z.string().nullish(),
+    dueDate: z.string(),
+    totalAmount: z.number(),
+    totalAmountCurrencyCode: z.string().nullish(),
+    minimumPaymentAmount: z.number().nullish(),
+    allowsInstallments: z.boolean().nullish(),
+    financeCharges: z.array(BILL_AMOUNT),
+    payments: z.array(BILL_AMOUNT),
+});
+/** Pluggy's offset envelope for `/bills`. */
+export const BILL_PAGE = z.object({
+    total: z.number(),
+    totalPages: z.number(),
+    page: z.number(),
+    results: z.array(BILL),
+});
+/** Nested fields Pluggy omits entirely when a card row has no such detail. */
+export const CREDIT_CARD_METADATA = z.object({
+    billId: z.string().optional(),
+    installmentNumber: z.number().optional(),
+    totalInstallments: z.number().optional(),
+    cardNumber: z.string().optional(),
+    payeeMCC: z.number().optional(),
+    purchaseDate: z.string().optional(),
+    feeType: z.string().optional(),
+    billForecastDate: z.string().optional(),
+});
+export const PAYMENT_DATA = z.object({
+    receiver: z
+        .object({
+        name: z.string().nullish(),
+        documentNumber: z.object({ value: z.string().optional(), type: z.string().optional() }).optional(),
+    })
+        .nullish(),
+    paymentMethod: z.string().nullish(),
+});
+export const TRANSACTION = z.object({
+    id: z.string(),
+    accountId: z.string(),
+    date: z.string(),
+    description: z.string(),
+    descriptionRaw: z.string().nullish(),
+    amount: z.number(),
+    amountInAccountCurrency: z.number().nullish(),
+    currencyCode: z.string().nullish(),
+    category: z.string().nullish(),
+    categoryId: z.string().nullish(),
+    status: z.string().nullish(),
+    creditCardMetadata: CREDIT_CARD_METADATA.nullish(),
+    paymentData: PAYMENT_DATA.nullish(),
+});
+/** The cursor-paginated envelope for `/v2/transactions`. */
+export const TRANSACTION_PAGE = z.object({
+    results: z.array(TRANSACTION),
+    next: z.string().nullable(),
+});
+export const CATEGORY = z.object({
+    id: z.string(),
+    description: z.string(),
+    descriptionTranslated: z.string().nullish(),
+    parentId: z.string().nullish(),
+    parentDescription: z.string().nullish(),
+});
+export const CATEGORY_PAGE = z.object({
+    results: z.array(CATEGORY),
+    total: z.number(),
+    totalPages: z.number(),
+    page: z.number(),
+});
+/** Reduces the one supported category page into the pure core taxonomy shape. */
+export function parseCategoryPage(page) {
+    if (page.totalPages !== 1) {
+        throw new Error(`Categories totalPages is ${page.totalPages}; expected one complete page`);
+    }
+    return page.results.map((category) => ({
+        id: category.id,
+        parentId: category.parentId ?? null,
+        parentDescription: category.parentDescription ?? null,
+    }));
+}
+/**
+ * Pluggy's error envelope. Read on every non-2xx, because the status alone is not
+ * a diagnosis: one 400 means a malformed request, another means a consent the
+ * user revoked, and only `codeDescription` and `message` separate them. Throwing
+ * "Pluggy returned 400" and dropping the rest is §16.2's scar, where the evidence
+ * was deleted before a human could see it.
+ *
+ * Every field is optional and `data` falls back rather than failing, because an
+ * error we cannot fully parse is still an error worth reporting.
+ */
+export const API_ERROR = z.object({
+    codeDescription: z.string().nullish(),
+    message: z.string().nullish(),
+    data: z
+        .object({ canRetryAfterDate: z.string().nullish() })
+        .nullish()
+        .catch(null),
+});
+//# sourceMappingURL=wire.js.map

package/dist/pluggy/wire.js.map

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

package/dist/storage/categories.js

@@ -0,0 +1,101 @@
+import { isDocument } from "../core/counterparty.js";
+const systemClock = { now: () => new Date() };
+const OVERRIDE_UPSERT = `
+  INSERT INTO userdata.category_overrides (transaction_id, category, created_at)
+  VALUES (?, ?, ?)
+  ON CONFLICT(transaction_id) DO UPDATE SET
+    category = excluded.category,
+    created_at = excluded.created_at
+`;
+const COUNTERPARTY_UPSERT = `
+  INSERT INTO userdata.counterparty_categories (document, category, origin, samples, agreeing, created_at)
+  VALUES (?, ?, 'manual', NULL, NULL, ?)
+  ON CONFLICT(document) DO UPDATE SET
+    category = excluded.category,
+    origin = 'manual',
+    samples = NULL,
+    agreeing = NULL,
+    created_at = excluded.created_at
+`;
+/**
+ * How many cached rows this counterparty now answers for.
+ *
+ * Rows carrying an override are excluded, because an override outranks the
+ * counterparty branch and those rows do not move. Counting them would overstate
+ * the blast radius in the one number a user reads to decide whether a write was
+ * broader than they meant (ADR §12.6).
+ */
+const AFFECTED_COUNT = `
+  SELECT COUNT(*) AS affected FROM transactions t
+  WHERE t.document = ?
+    AND NOT EXISTS (SELECT 1 FROM userdata.category_overrides o WHERE o.transaction_id = t.id)
+`;
+export function createCategoryWriter(db, clock = systemClock) {
+    const context = {
+        db,
+        clock,
+        override: db.prepare(OVERRIDE_UPSERT),
+        counterparty: db.prepare(COUNTERPARTY_UPSERT),
+        affected: db.prepare(AFFECTED_COUNT),
+    };
+    return {
+        setCategory: (ids, category) => setCategory(context, ids, category),
+        setCounterpartyCategory: (document, category) => setCounterpartyCategory(context, document, category),
+    };
+}
+/**
+ * The ids we hold, so unknown ones can be reported rather than raised. An agent
+ * working from a stale listing should get its known rows written and the rest
+ * named back (PRD item 4).
+ */
+function knownIds(db, ids) {
+    const sql = `SELECT id FROM transactions WHERE id IN (${placeholders(ids.length)})`;
+    const rows = db.prepare(sql).all(...ids);
+    return new Set(rows.map((row) => String(row.id)));
+}
+function setCategory(context, ids, category) {
+    if (ids.length === 0) {
+        return { updated: 0, unknownIds: [] };
+    }
+    const known = knownIds(context.db, ids);
+    const unknownIds = ids.filter((id) => !known.has(id));
+    if (known.size === 0) {
+        return { updated: 0, unknownIds };
+    }
+    const now = context.clock.now().toISOString();
+    inTransaction(context.db, () => {
+        for (const id of known) {
+            context.override.run(id, category, now);
+        }
+    });
+    return { updated: known.size, unknownIds };
+}
+function setCounterpartyCategory(context, document, category) {
+    const digits = document.replace(/\D/gu, "");
+    if (!isDocument(digits)) {
+        throw new Error("document must be an 11-digit CPF or 14-digit CNPJ");
+    }
+    const now = context.clock.now().toISOString();
+    let affected = 0;
+    inTransaction(context.db, () => {
+        context.counterparty.run(digits, category, now);
+        const row = context.affected.get(digits);
+        affected = Number(row?.affected ?? 0);
+    });
+    return { affected };
+}
+function inTransaction(db, work) {
+    db.exec("BEGIN");
+    try {
+        work();
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+function placeholders(count) {
+    return Array.from({ length: count }, () => "?").join(", ");
+}
+//# sourceMappingURL=categories.js.map

package/dist/storage/categories.js.map

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

package/dist/storage/category-sql.js

@@ -0,0 +1,37 @@
+import { BRANCHES } from "../core/category-source.js";
+/**
+ * The six branches as six columns, plus the durable leaf.
+ *
+ * `c_leaf` is the finest category we still know for the row: what Pluggy sends
+ * today, and what the snapshot remembers once it stops sending anything. It is
+ * not a seventh branch — it is not rolled up and never competes for the derived
+ * category. It exists because the self-transfer exclusion in `core/aggregate.ts`
+ * distinguishes a credit card payment from an ordinary transfer, and only the
+ * leaf carries that distinction. Reading `transactions.category_id` directly
+ * there would let every card bill payment re-enter `spent` the day the plan
+ * drops to free.
+ *
+ * Resolution happens in `core/category-source.ts`, driven by the same array
+ * that builds this.
+ *
+ * There is deliberately no `CREATE VIEW`. A view living in the droppable file
+ * and referencing `userdata.` would couple `cache.db`'s schema to a schema name
+ * that has to be attached already — including during the migration run at
+ * startup, before any attach has happened.
+ */
+export const DERIVED_COLUMNS = `
+  (SELECT o.category FROM userdata.category_overrides o
+     WHERE o.transaction_id = t.id)                                AS c_override,
+  (SELECT c.category FROM userdata.counterparty_categories c
+     WHERE t.document IS NOT NULL AND c.document = t.document AND c.origin = 'manual')        AS c_counterparty,
+  t.top_category_id                                                AS c_pluggy,
+  (SELECT s.top_category_id FROM userdata.category_snapshot s
+     WHERE s.transaction_id = t.id)                                AS c_snapshot,
+  (SELECT c.category FROM userdata.counterparty_categories c
+     WHERE t.document IS NOT NULL AND c.document = t.document AND c.origin = 'learned')       AS c_learned,
+  (SELECT m.category FROM mcc_categories m WHERE m.mcc = t.mcc)    AS c_mcc,
+  COALESCE(t.category_id, (SELECT s.category_id FROM userdata.category_snapshot s
+     WHERE s.transaction_id = t.id))                               AS c_leaf
+`;
+export const DERIVED_CATEGORY = `COALESCE(${BRANCHES.map((branch) => `c_${branch}`).join(", ")})`;
+//# sourceMappingURL=category-sql.js.map

package/dist/storage/category-sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"category-sql.js","sourceRoot":"","sources":["../../src/storage/category-sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;CAa9B,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC"}

package/dist/storage/closing-days.js

@@ -0,0 +1,27 @@
+const CLOSING_DAY_UPSERT = `
+  INSERT INTO userdata.card_closing_day (account_id, day, created_at, updated_at)
+  VALUES (?, ?, ?, ?)
+  ON CONFLICT(account_id) DO UPDATE SET
+    day = excluded.day,
+    updated_at = excluded.updated_at
+`;
+const systemClock = { now: () => new Date() };
+/** Builds the local store for user-provided card billing-cycle closing days. */
+export function createClosingDayStore(db, clock = systemClock) {
+    const upsert = db.prepare(CLOSING_DAY_UPSERT);
+    const list = db.prepare("SELECT account_id, day FROM userdata.card_closing_day ORDER BY account_id");
+    const remove = db.prepare("DELETE FROM userdata.card_closing_day WHERE account_id = ?");
+    return {
+        list: () => listClosingDays(list),
+        set: (accountId, day) => {
+            const now = clock.now().toISOString();
+            upsert.run(accountId, day, now, now);
+        },
+        delete: (accountId) => Number(remove.run(accountId).changes),
+    };
+}
+function listClosingDays(statement) {
+    const rows = statement.all();
+    return rows.map((row) => ({ accountId: String(row["account_id"]), day: Number(row["day"]) }));
+}
+//# sourceMappingURL=closing-days.js.map

package/dist/storage/closing-days.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closing-days.js","sourceRoot":"","sources":["../../src/storage/closing-days.ts"],"names":[],"mappings":"AAIA,MAAM,kBAAkB,GAAG;;;;;;CAM1B,CAAC;AAEF,MAAM,WAAW,GAAU,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AAErD,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,EAAgB,EAAE,QAAe,WAAW;IAChF,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,2EAA2E,CAAC,CAAC;IACrG,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,4DAA4D,CAAC,CAAC;IAExF,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC;QACjC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE;YACtB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACvC,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,SAA8C;IACrE,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAA+B,CAAC;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChG,CAAC"}