@baruk/core 0.3.1 → 0.4.2

package/dist/collection/copy.d.ts

@@ -0,0 +1,50 @@
+import type { TenantBranding } from './branding.js';
+import type { EmailBlock } from './email-layout.js';
+import type { PaymentBlock } from './payment-block.js';
+import type { StepTone } from './policy.js';
+/**
+ * Textos da régua.
+ *
+ * A progressão vai de lembrete cordial a pedido claro de regularização — e para
+ * por aí. Nenhum texto menciona medida judicial, negativação, protesto ou
+ * suspensão de serviço: o escritório é quem decide se e quando falar disso, com
+ * o cliente dele, e uma automação que escala sozinha para ameaça é onde cobrança
+ * automatizada vira problema jurídico e de relacionamento.
+ *
+ * O assunto também mudou de registro. "Lembrete: vencimento em 2026-08-15" é
+ * saída de sistema; quem recebe quer reconhecer o remetente e o assunto de
+ * imediato.
+ */
+export interface CopyContext {
+    clientName: string;
+    branding: TenantBranding;
+    outstandingAmount: number;
+    dueDate: string | null;
+    competence: string | null;
+    description: string | null;
+    daysOverdue: number;
+    /** Já entrou parte do valor? Muda o texto — e evita cobrar o que já foi pago. */
+    hasPartialPayment: boolean;
+    originalAmount: number;
+    /**
+     * Como pagar, quando já existe cobrança emitida.
+     *
+     * Opcional porque a régua roda com ou sem provider conectado: um escritório
+     * sem conta de pagamento continua recebendo a comunicação completa, só sem o
+     * botão. O e-mail nunca promete um caminho de pagamento que não existe.
+     */
+    payment?: PaymentBlock;
+}
+export interface RenderedCopy {
+    subject: string;
+    block: EmailBlock;
+}
+/**
+ * Anexa o pagamento a qualquer etapa da régua.
+ *
+ * Fica fora do `switch` de propósito: o bloco de pagamento é o mesmo em D-3, D0
+ * e D+3, e cada etapa tendo a própria cópia da regra é a forma garantida de uma
+ * delas ficar para trás — foi assim que a etapa de atraso ficaria sem botão.
+ */
+export declare function renderCopy(tone: StepTone, ctx: CopyContext): RenderedCopy;
+//# sourceMappingURL=copy.d.ts.map

package/dist/collection/copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../../src/collection/copy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC;CACnB;AAuBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,YAAY,CAIzE"}

package/dist/collection/copy.js

@@ -0,0 +1,122 @@
+import { formatBRL, formatDateBR, formatOverdue, describeReference } from './format.js';
+/** Frase que identifica a dívida sem inventar dado que não existe. */
+function referenceSentence(ctx) {
+    const ref = describeReference({ competence: ctx.competence, description: ctx.description });
+    return ref ? `Referente a ${ref}.` : null;
+}
+/**
+ * Quando houve pagamento parcial, o texto precisa dizer isso.
+ *
+ * Mandar "o valor de X está em aberto" para quem já pagou metade soa como se o
+ * pagamento não tivesse sido registrado — e é a mensagem que mais gera ligação
+ * irritada para o escritório.
+ */
+function partialSentence(ctx) {
+    if (!ctx.hasPartialPayment)
+        return null;
+    return (`Registramos o pagamento parcial de ${formatBRL(ctx.originalAmount - ctx.outstandingAmount)}. ` +
+        `O saldo restante é de ${formatBRL(ctx.outstandingAmount)}.`);
+}
+/**
+ * Anexa o pagamento a qualquer etapa da régua.
+ *
+ * Fica fora do `switch` de propósito: o bloco de pagamento é o mesmo em D-3, D0
+ * e D+3, e cada etapa tendo a própria cópia da regra é a forma garantida de uma
+ * delas ficar para trás — foi assim que a etapa de atraso ficaria sem botão.
+ */
+export function renderCopy(tone, ctx) {
+    const rendered = renderCopyBody(tone, ctx);
+    if (!ctx.payment)
+        return rendered;
+    return { ...rendered, block: { ...rendered.block, payment: ctx.payment } };
+}
+function renderCopyBody(tone, ctx) {
+    const office = ctx.branding.officeName;
+    const amount = formatBRL(ctx.outstandingAmount);
+    const due = formatDateBR(ctx.dueDate);
+    // Razão social brasileira termina em ponto com frequência ("Ltda.", "S.A.",
+    // "ME."). Somar o nosso produziria "Olá, Padaria Exemplo Ltda.." — pequeno,
+    // mas é a primeira linha que o cliente lê.
+    const greeting = `Olá, ${ctx.clientName}${/[.!?…]$/.test(ctx.clientName.trim()) ? '' : '.'}`;
+    const ref = referenceSentence(ctx);
+    const partial = partialSentence(ctx);
+    const highlight = {
+        label: ctx.hasPartialPayment ? 'Saldo em aberto' : 'Valor',
+        amount,
+        dueLabel: tone === 'reminder' ? 'Vencimento em' : 'Vencimento:',
+        dueValue: due,
+    };
+    switch (tone) {
+        case 'reminder':
+            return {
+                subject: `Lembrete de vencimento — ${office}`,
+                block: {
+                    greeting,
+                    paragraphs: [
+                        `Passando para lembrar que você tem um valor a vencer em ${due}.`,
+                        ...(ref ? [ref] : []),
+                        ...(partial ? [partial] : []),
+                    ],
+                    highlight,
+                    closing: 'Se o pagamento já foi feito, é só desconsiderar.',
+                },
+            };
+        case 'due_notice':
+            return {
+                subject: `Seu honorário vence hoje — ${office}`,
+                block: {
+                    greeting,
+                    paragraphs: [
+                        'O valor abaixo vence hoje.',
+                        ...(ref ? [ref] : []),
+                        ...(partial ? [partial] : []),
+                    ],
+                    highlight: { ...highlight, dueLabel: 'Vence hoje,' },
+                    closing: 'Se o pagamento já foi feito, é só desconsiderar.',
+                },
+            };
+        case 'friendly_collection':
+            return {
+                subject: `Pendência em aberto — ${office}`,
+                block: {
+                    greeting,
+                    paragraphs: [
+                        `Identificamos um valor em aberto, com vencimento em ${due}${ctx.daysOverdue > 0 ? ` — ${formatOverdue(ctx.daysOverdue)}` : ''}.`,
+                        ...(ref ? [ref] : []),
+                        ...(partial ? [partial] : []),
+                        'Se já tiver pago, avise-nos para darmos baixa. Se preferir, estamos à disposição para combinar a melhor forma.',
+                    ],
+                    highlight,
+                },
+            };
+        case 'overdue_collection':
+            return {
+                subject: `Regularização de pendência — ${office}`,
+                block: {
+                    greeting,
+                    paragraphs: [
+                        `O valor abaixo segue em aberto desde ${due}${ctx.daysOverdue > 0 ? ` (${formatOverdue(ctx.daysOverdue)})` : ''}.`,
+                        ...(ref ? [ref] : []),
+                        ...(partial ? [partial] : []),
+                        'Pedimos que entre em contato para regularizarmos. Se houver qualquer dificuldade, fale conosco — encontramos a melhor alternativa juntos.',
+                    ],
+                    highlight,
+                },
+            };
+        // Interno: nunca chega ao cliente. Ver a nota em `policy.ts`.
+        case 'human_escalation':
+        default:
+            return {
+                subject: `Cobrança para acompanhamento manual — ${ctx.clientName}`,
+                block: {
+                    greeting: 'Aviso interno.',
+                    paragraphs: [
+                        `A régua automática chegou ao fim para ${ctx.clientName}, com ${amount} em aberto desde ${due}.`,
+                        'A condução a partir daqui é humana.',
+                    ],
+                    highlight,
+                },
+            };
+    }
+}
+//# sourceMappingURL=copy.js.map

package/dist/collection/copy.js.map

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

package/dist/collection/delivery-callback.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Aplicação dos callbacks de entrega ao estado do produto.
+ *
+ * `communication/webhook.ts` traduz o vocabulário do provider e decide se o
+ * evento avança o estado; este arquivo é o que ESCREVE. A separação é a mesma de
+ * sempre: o motor não conhece `dunning_event`, e a régua não conhece a Meta.
+ *
+ * Três escritas, e a ordem entre elas importa menos que o fato de estarem na
+ * MESMA transação: um callback que atualiza a etapa e falha ao gravar a trilha
+ * deixaria a tela dizendo "entregue" sem nada que explique quando nem por qual
+ * caminho.
+ */
+import type { Tx } from '../db/client.js';
+import { type DeliveryEvent, type DeliveryStatus, type InboundOptOut } from '../communication/index.js';
+export type CallbackOutcome = 
+/** Estado avançado e gravado. */
+'applied'
+/** O provider mandou algo que este canal não reporta — dado inventado, recusado. */
+ | 'not_reported_by_channel'
+/** Chegou fora de ordem, ou repetido: o estado já está igual ou adiante. */
+ | 'no_progress'
+/** Nenhuma mensagem deste tenant tem esse identificador de provider. */
+ | 'unknown_message';
+export interface CallbackResult {
+    outcome: CallbackOutcome;
+    receivableId: string | null;
+    status: DeliveryStatus | null;
+}
+/**
+ * Aplica um callback de entrega.
+ *
+ * A via de acesso é o `provider_ref` — é a ÚNICA coisa que o webhook traz. Sem
+ * a coluna indexada da 0038 isso exigiria varrer a tabela, e a régua de um
+ * escritório grande tornaria cada callback caro o bastante para o provider
+ * desistir de reentregar.
+ */
+export declare function applyDeliveryCallback(tx: Tx, tenantId: string, event: DeliveryEvent): Promise<CallbackResult>;
+export type OptOutOutcome = 'registered' | 'unknown_recipient';
+/**
+ * Registra o opt-out que o cliente pediu respondendo no canal.
+ *
+ * `customer_reply` é a origem mais forte que existe: `recordConsent` impede que
+ * um operador a reverta pela tela. Por isso a resolução do telefone para cliente
+ * é feita pelo `phone_e164` canônico e nunca pelo campo digitado — casar por
+ * texto livre acertaria o cliente errado quando dois cadastros diferem só na
+ * pontuação, e bloquearia o canal de quem não pediu nada.
+ */
+export declare function applyInboundOptOut(tx: Tx, tenantId: string, optOut: InboundOptOut): Promise<OptOutOutcome>;
+//# sourceMappingURL=delivery-callback.d.ts.map

package/dist/collection/delivery-callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-callback.d.ts","sourceRoot":"","sources":["../../src/collection/delivery-callback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAInC,MAAM,MAAM,eAAe;AACzB,iCAAiC;AAC/B,SAAS;AACX,oFAAoF;GAClF,yBAAyB;AAC3B,4EAA4E;GAC1E,aAAa;AACf,wEAAwE;GACtE,iBAAiB,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAKD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,CAAC,CAmEzB;AA0CD,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAsCxB"}

package/dist/collection/delivery-callback.js

@@ -0,0 +1,147 @@
+/**
+ * Aplicação dos callbacks de entrega ao estado do produto.
+ *
+ * `communication/webhook.ts` traduz o vocabulário do provider e decide se o
+ * evento avança o estado; este arquivo é o que ESCREVE. A separação é a mesma de
+ * sempre: o motor não conhece `dunning_event`, e a régua não conhece a Meta.
+ *
+ * Três escritas, e a ordem entre elas importa menos que o fato de estarem na
+ * MESMA transação: um callback que atualiza a etapa e falha ao gravar a trilha
+ * deixaria a tela dizendo "entregue" sem nada que explique quando nem por qual
+ * caminho.
+ */
+import { randomUUID } from 'node:crypto';
+import { applyDeliveryEvent, } from '../communication/index.js';
+import { recordConsent } from './consent-repository.js';
+import { SC_PRODUCT } from './communication-bridge.js';
+/** Estados de `dunning_event` que descrevem uma mensagem já entregue ao provider. */
+const DELIVERABLE = ['sent', 'delivered', 'read', 'failed'];
+/**
+ * Aplica um callback de entrega.
+ *
+ * A via de acesso é o `provider_ref` — é a ÚNICA coisa que o webhook traz. Sem
+ * a coluna indexada da 0038 isso exigiria varrer a tabela, e a régua de um
+ * escritório grande tornaria cada callback caro o bastante para o provider
+ * desistir de reentregar.
+ */
+export async function applyDeliveryCallback(tx, tenantId, event) {
+    const rows = await tx `
+    SELECT id, receivable_id, status, idempotency_key
+      FROM dunning_event
+     WHERE provider_ref = ${event.providerRef}
+     LIMIT 1
+  `;
+    const action = rows[0];
+    // Sem ação correspondente não há o que atualizar. NÃO é erro: o mesmo número
+    // pode ter mandado mensagem por outro sistema, e um 4xx aqui faria o provider
+    // reentregar para sempre um evento que nunca vai ser reconhecido.
+    if (!action) {
+        await recordCallbackEvent(tx, tenantId, event, null, null, 'unknown_message');
+        return { outcome: 'unknown_message', receivableId: null, status: null };
+    }
+    // `advanceStatus` opera sobre estados de ENTREGA. Uma ação `scheduled`,
+    // `canceled` ou `escalated` não descreve mensagem entregue, e forçá-la para
+    // `delivered` inventaria uma entrega que a régua não fez.
+    const current = (DELIVERABLE.includes(action.status) ? action.status : 'sent');
+    const decision = applyDeliveryEvent(current, event);
+    if (!decision.apply) {
+        await recordCallbackEvent(tx, tenantId, event, action.receivable_id, action.idempotency_key, decision.reason);
+        return { outcome: decision.reason, receivableId: action.receivable_id, status: null };
+    }
+    await tx `
+    UPDATE dunning_event
+       SET status = ${decision.status},
+           delivered_at = CASE
+             WHEN ${decision.status} IN ('delivered', 'read') THEN COALESCE(delivered_at, ${event.occurredAt}::timestamptz)
+             ELSE delivered_at END,
+           read_at = CASE
+             WHEN ${decision.status} = 'read' THEN COALESCE(read_at, ${event.occurredAt}::timestamptz)
+             ELSE read_at END,
+           last_error = CASE
+             WHEN ${decision.status} = 'failed' THEN ${(event.detail ?? event.code ?? 'falha reportada pelo provider').slice(0, 300)}
+             ELSE last_error END
+     WHERE id = ${action.id}
+  `;
+    await recordCallbackEvent(tx, tenantId, event, action.receivable_id, action.idempotency_key, null, decision.status);
+    return {
+        outcome: 'applied',
+        receivableId: action.receivable_id,
+        status: decision.status,
+    };
+}
+const CALLBACK_KIND = {
+    delivered: 'callback_delivered',
+    read: 'callback_read',
+    failed: 'callback_failed',
+    opted_out: 'opt_out',
+};
+async function recordCallbackEvent(tx, tenantId, event, subjectRef, idempotencyKey, refusal, applied) {
+    // Evento recusado também vira linha. É a diferença entre "o provider nunca
+    // avisou" e "avisou e nós descartamos" — e só a segunda tem explicação.
+    const kind = refusal ? 'dispatch_skipped' : (CALLBACK_KIND[event.status] ?? 'dispatch_skipped');
+    await tx `
+    INSERT INTO communication_event (
+      id, tenant_id, product, brand, kind, channel, event_type, subject_ref,
+      recipient_ref, idempotency_key, provider_ref, skip_reason, status, code,
+      detail, occurred_at
+    ) VALUES (
+      ${randomUUID()}, ${tenantId}, ${SC_PRODUCT},
+      -- A marca vem da RESERVA que produziu a mensagem. Quando não há reserva
+      -- correspondente, o evento fica sem marca — é o caso do callback sobre um
+      -- identificador que não é nosso, e inventar um valor aqui faria a trilha
+      -- atribuir a um escritório algo que ele não enviou.
+      (SELECT brand FROM communication_dispatch
+        WHERE provider_ref = ${event.providerRef} LIMIT 1),
+      ${kind}, ${event.channel}, 'billing.dunning.callback', ${subjectRef},
+      NULL, ${idempotencyKey}, ${event.providerRef}, ${refusal},
+      ${applied ?? event.status}, ${event.code ?? null},
+      ${event.detail ? event.detail.slice(0, 300) : null}, ${event.occurredAt}::timestamptz
+    )
+  `;
+}
+/**
+ * Registra o opt-out que o cliente pediu respondendo no canal.
+ *
+ * `customer_reply` é a origem mais forte que existe: `recordConsent` impede que
+ * um operador a reverta pela tela. Por isso a resolução do telefone para cliente
+ * é feita pelo `phone_e164` canônico e nunca pelo campo digitado — casar por
+ * texto livre acertaria o cliente errado quando dois cadastros diferem só na
+ * pontuação, e bloquearia o canal de quem não pediu nada.
+ */
+export async function applyInboundOptOut(tx, tenantId, optOut) {
+    const e164 = optOut.from.startsWith('+') ? optOut.from : `+${optOut.from}`;
+    const rows = await tx `
+    SELECT id FROM client
+     WHERE phone_e164 = ${e164} AND deleted_at IS NULL
+     ORDER BY created_at
+     LIMIT 2
+  `;
+    // Dois clientes com o mesmo telefone é cadastro legítimo (marido e mulher,
+    // matriz e filial). Bloquear "o primeiro" seria escolher por sorte quem
+    // deixa de ser cobrado. Sem resolução única, nada é registrado — e o evento
+    // fica na trilha para um humano decidir.
+    if (rows.length !== 1)
+        return 'unknown_recipient';
+    await recordConsent(tx, {
+        tenantId,
+        clientId: rows[0].id,
+        channel: optOut.channel,
+        state: 'denied',
+        source: 'customer_reply',
+        note: 'opt-out recebido no canal',
+    });
+    await tx `
+    INSERT INTO communication_event (
+      id, tenant_id, product, brand, kind, channel, event_type, recipient_ref,
+      code, occurred_at
+    ) VALUES (
+      -- Opt-out é do CLIENTE, e vale para todas as marcas do escritório: o
+      -- pedido de silêncio não é por linha de produto. Sem marca, portanto.
+      ${randomUUID()}, ${tenantId}, ${SC_PRODUCT}, NULL, 'opt_out',
+      ${optOut.channel}, 'communication.opt_out', ${rows[0].id},
+      'customer_reply', ${optOut.occurredAt}::timestamptz
+    )
+  `;
+    return 'registered';
+}
+//# sourceMappingURL=delivery-callback.js.map

package/dist/collection/delivery-callback.js.map

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

package/dist/collection/email-layout.d.ts

@@ -0,0 +1,45 @@
+import type { TenantBranding } from './branding.js';
+import type { PaymentBlock } from './payment-block.js';
+/**
+ * Shell transacional do e-mail de cobrança.
+ *
+ * Escrito com tabelas e estilo inline de propósito: Gmail remove `<style>` em
+ * boa parte dos contextos e o Outlook desktop renderiza com o motor do Word, que
+ * ignora flexbox, grid e boa parte de CSS moderno. O layout que "fica bonito no
+ * navegador" é justamente o que quebra na caixa de entrada.
+ *
+ * A única imagem é a logomarca, e o cabeçalho é construído para sobreviver ao
+ * bloqueio de imagens — padrão em muitos leitores. Nenhuma informação mora só
+ * dentro do arquivo: com as imagens desligadas, o nome do escritório continua
+ * escrito no cabeçalho.
+ *
+ * Cores e tipografia vêm do tenant (`TenantBranding`), não de constantes daqui.
+ * Nenhum escritório está no código.
+ */
+export interface EmailBlock {
+    greeting: string;
+    /** Parágrafos do corpo, na ordem. */
+    paragraphs: string[];
+    /** Destaque do valor/vencimento. Omitido quando não há dívida a exibir. */
+    highlight?: {
+        label: string;
+        amount: string;
+        dueLabel: string;
+        dueValue: string;
+    };
+    closing?: string;
+    /** Como pagar. Ausente quando o recebível ainda não tem cobrança emitida. */
+    payment?: PaymentBlock;
+}
+export declare function escapeHtml(s: string): string;
+export declare function renderCollectionEmail(b: TenantBranding, block: EmailBlock): string;
+/**
+ * Versão texto puro.
+ *
+ * Não é decoração: parte dos leitores prefere `text/plain`, filtros de spam
+ * penalizam mensagem só-HTML, e leitores de tela lidam melhor com o texto. O
+ * conteúdo tem de ser o MESMO — um plain text resumido faria dois clientes
+ * receberem informações diferentes.
+ */
+export declare function renderCollectionText(b: TenantBranding, block: EmailBlock): string;
+//# sourceMappingURL=email-layout.d.ts.map

package/dist/collection/email-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-layout.d.ts","sourceRoot":"","sources":["../../src/collection/email-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAgCD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO5C;AAsID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAqElF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAmCjF"}