@ultimat3/mail 1.0.0

package/src/driver-resend.ts

@@ -0,0 +1,184 @@
+// Single responsibility: the Resend HTTPS transport. One POST per message onto the shared
+// MailDriver contract — no SDK, `fetch` is the whole client. Construction fails fast on a
+// missing key or an empty from address, so a misconfiguration never waits for the first send.
+
+import { ConfigInvalidError, EnvMissingError, logger, nanoid } from '@ultimat3/core';
+import type { MailDriver, MailMessage, SendResult } from './driver';
+import { messageHeaders, resultFor } from './driver';
+import { sendFailed } from './errors';
+import { mailIdempotencyKey } from './idempotency';
+
+export const RESEND_BASE_URL = 'https://api.resend.com';
+
+/** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
+export type MailFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_DETAIL_LENGTH = 200;
+
+// A 4xx here means the same request, unchanged, might land: a throttle or a momentary
+// conflict. Every other 4xx is a config problem retrying cannot fix.
+const RETRYABLE_STATUSES = new Set([408, 409, 425, 429]);
+
+export interface ResendDriverOptions {
+  /** Read from `RESEND_API_KEY`. A literal key in app.config.ts is a key in git. */
+  readonly apiKey: string;
+  /** `Postly <no-reply@postly.test>`. Must be a domain verified with Resend. */
+  readonly from: string;
+  /** Override for a self-hosted proxy or a test double. Defaults to `RESEND_BASE_URL`. */
+  readonly baseUrl?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: MailFetch | undefined;
+}
+
+function requireApiKey(apiKey: string): string {
+  if (apiKey.trim() !== '') return apiKey;
+  throw new EnvMissingError({
+    cause: 'RESEND_API_KEY is not set, so the resend driver cannot authenticate',
+    fix: "set RESEND_API_KEY in .env (or the container's secret store), then re-run",
+    meta: { missing: 'RESEND_API_KEY' },
+  });
+}
+
+function requireFrom(from: string): string {
+  if (from.trim() !== '') return from;
+  throw new ConfigInvalidError({
+    cause: 'the resend driver was configured without a from address',
+    fix: 'set mail.from in app.config.ts to a domain verified with Resend',
+  });
+}
+
+/** `retryable` for a throttle or a transient conflict; everything else is a config problem. */
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || RETRYABLE_STATUSES.has(status);
+}
+
+function fixFor(status: number): string {
+  if (status === 401 || status === 403) {
+    return 'set RESEND_API_KEY to a current key from https://resend.com/api-keys, then retry';
+  }
+  if (status === 422) {
+    return 'verify the sending domain in the Resend dashboard: https://resend.com/domains';
+  }
+  if (status === 429) {
+    return 'the job already retries with backoff — raise the rate limit on the Resend plan';
+  }
+  return 'check the request against https://resend.com/docs/api-reference/emails/send-email';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Prefers Resend's own message; falls back to the raw body, capped so a huge page can't flood logs. */
+async function detailFor(response: Response): Promise<string> {
+  const text = await response.text().catch(() => '');
+  if (text === '') return `HTTP ${response.status} with an empty body`;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    const message = isRecord(parsed) ? parsed['message'] : undefined;
+    if (typeof message === 'string' && message !== '') return message;
+  } catch {
+    // Not JSON — fall through to the truncated raw text below.
+  }
+  return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+}
+
+/** A 2xx is acceptance regardless of body shape; the id is best-effort, never a reason to fail. */
+async function idFor(response: Response, message: MailMessage): Promise<string> {
+  const parsed: unknown = await response.json().catch(() => undefined);
+  const id = isRecord(parsed) ? parsed['id'] : undefined;
+  if (typeof id === 'string' && id !== '') return id;
+  const local = `resend_${nanoid(12)}`;
+  logger.warn('mail.resend.no_id', { mailId: message.mailId, id: local });
+  return local;
+}
+
+interface ResendRequestBody {
+  readonly from: string;
+  readonly to: readonly string[];
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly cc?: readonly string[];
+  readonly bcc?: readonly string[];
+  readonly reply_to?: string;
+}
+
+/** `bcc` travels in the body here — Resend builds the envelope, so this is the one place a
+ * blind list legitimately leaves the process. Absent fields are omitted, never null: Resend
+ * rejects nulls outright. */
+function bodyFor(message: MailMessage, from: string): ResendRequestBody {
+  return {
+    from,
+    to: message.to,
+    subject: message.subject,
+    html: message.html,
+    text: message.text,
+    headers: messageHeaders(message),
+    ...(message.cc === undefined ? {} : { cc: message.cc }),
+    ...(message.bcc === undefined ? {} : { bcc: message.bcc }),
+    ...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
+  };
+}
+
+export function createResendDriver(options: ResendDriverOptions): MailDriver {
+  const apiKey = requireApiKey(options.apiKey);
+  const from = requireFrom(options.from);
+  const baseUrl = options.baseUrl ?? RESEND_BASE_URL;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  // A bare reference to `globalThis.fetch` risks "Illegal invocation" on some hosts; closing
+  // over the call keeps it detached from any receiver, in production and in tests alike.
+  const doFetch: MailFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+
+  return {
+    name: 'resend',
+
+    async send(message: MailMessage): Promise<SendResult> {
+      // Always sent, and content-derived rather than taken from the envelope: a job retry after a
+      // timeout hands Resend the identical message, and this header is what makes that one email.
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        'Idempotency-Key': mailIdempotencyKey(message),
+      };
+
+      let response: Response;
+      try {
+        response = await doFetch(`${baseUrl}/emails`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(bodyFor(message, from)),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (error) {
+        // DNS/TLS/reset, or the timeout firing — none of them got far enough to have a status,
+        // and every one of them can succeed unchanged on the job's next attempt.
+        const reason =
+          error instanceof Error ? error.message : 'the request failed before a response';
+        throw sendFailed({
+          driver: 'resend',
+          stage: 'request',
+          detail: `${reason} — nothing left this host for ${baseUrl}/emails (egress, DNS or TLS)`,
+          retryable: true,
+          fix: `curl -sS -m 5 -o /dev/null ${baseUrl}/emails`,
+        });
+      }
+
+      if (!response.ok) {
+        throw sendFailed({
+          driver: 'resend',
+          stage: 'request',
+          detail: await detailFor(response),
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          fix: fixFor(response.status),
+        });
+      }
+
+      return resultFor('resend', message, await idFor(response, message));
+    },
+  };
+}

package/src/driver-smtp.ts

@@ -0,0 +1,209 @@
+// Single responsibility: the SMTP transport as a `MailDriver` — parse `SMTP_URL` once at boot,
+// render the envelope to MIME, and run one conversation per message over one connection. The
+// protocol lives in `smtp-client.ts` and the socket in `smtp-socket.ts`; this file wires them.
+
+import {
+  type Clock,
+  ConfigInvalidError,
+  isUltimateError,
+  nanoid,
+  systemClock,
+} from '@ultimat3/core';
+import type { SendResult } from './driver';
+import { envelopeRecipients, type MailDriver, type MailMessage, resultFor } from './driver';
+import { sendFailed } from './errors';
+import { addressDomain, addressSpec, buildMimeMessage } from './mime';
+import {
+  type SmtpConnector,
+  type SmtpSessionOptions,
+  type SmtpTarget,
+  smtpDeliver,
+} from './smtp-client';
+import { bunSmtpStream } from './smtp-socket';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_POOL_SIZE = 4;
+const IMPLICIT_TLS_PORT = 465;
+const SUBMISSION_PORT = 587;
+
+export interface SmtpDriverOptions {
+  /** `smtps://user:pass@host:465`. Read from `SMTP_URL`, never hardcoded. */
+  readonly url: string;
+  /** `Postly <no-reply@postly.test>`. Also the envelope sender and the Message-ID domain. */
+  readonly from: string;
+  /** Max connections open at once. A burst of sends queues instead of opening one socket each. */
+  readonly poolSize?: number | undefined;
+  /** Deadline for any single read or write. Default 30s. */
+  readonly timeoutMs?: number | undefined;
+  /** The `EHLO` name. Defaults to the from address's domain, which is what SPF checks anyway. */
+  readonly clientName?: string | undefined;
+  /** Speak to a server that offers no STARTTLS. Off by default: mail and password in the clear. */
+  readonly allowInsecure?: boolean | undefined;
+  readonly clock?: Clock | undefined;
+  /** Injected in tests; production dials with `Bun.connect`. */
+  readonly connect?: SmtpConnector | undefined;
+}
+
+interface SmtpUrl {
+  readonly host: string;
+  readonly port: number;
+  readonly tls: boolean;
+  readonly user?: string | undefined;
+  readonly password?: string | undefined;
+}
+
+/** `smtps://` is implicit TLS on 465; `smtp://` starts in the clear and upgrades with STARTTLS. */
+function parseSmtpUrl(raw: string): SmtpUrl {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ConfigInvalidError({
+      cause: 'SMTP_URL is not a URL',
+      fix: 'set SMTP_URL to smtps://user:pass@host:465 (implicit TLS) or smtp://host:587',
+    });
+  }
+  if (url.protocol !== 'smtp:' && url.protocol !== 'smtps:') {
+    throw new ConfigInvalidError({
+      cause: `SMTP_URL uses the "${url.protocol}" scheme, which is not an SMTP one`,
+      fix: 'set SMTP_URL to smtps://user:pass@host:465 (implicit TLS) or smtp://host:587',
+    });
+  }
+  if (url.hostname === '') {
+    throw new ConfigInvalidError({
+      cause: 'SMTP_URL names no host',
+      fix: 'set SMTP_URL to smtps://user:pass@host:465 (implicit TLS) or smtp://host:587',
+    });
+  }
+  const tls = url.protocol === 'smtps:';
+  return {
+    host: url.hostname,
+    port: url.port === '' ? (tls ? IMPLICIT_TLS_PORT : SUBMISSION_PORT) : Number(url.port),
+    tls,
+    // Credentials are percent-encoded in a URL; a password with `@` or `/` is otherwise unusable.
+    ...(url.username === '' ? {} : { user: decodeURIComponent(url.username) }),
+    ...(url.password === '' ? {} : { password: decodeURIComponent(url.password) }),
+  };
+}
+
+/**
+ * `poolSize: 0` is the one config mistake this driver could not report: the limiter would park
+ * every send on a slot that is never handed out, with no deadline on the wait, so the job would
+ * neither fail nor retry and the worker slot would be gone until the process restarted. A silent
+ * deadlock is worse than any error, so this fails at construction like every other bad value.
+ */
+function resolvePoolSize(poolSize: number | undefined): number {
+  if (poolSize === undefined) return DEFAULT_POOL_SIZE;
+  if (!Number.isInteger(poolSize) || poolSize < 1) {
+    throw new ConfigInvalidError({
+      cause: `the smtp driver was configured with poolSize: ${poolSize}, which opens no connection`,
+      fix: `set poolSize to a whole number >= 1 in app.config.ts, or drop it for ${DEFAULT_POOL_SIZE}`,
+      meta: { poolSize },
+    });
+  }
+  return poolSize;
+}
+
+/** At most `size` conversations at a time — the honest meaning of `poolSize` for one-shot sends. */
+function createLimiter(size: number): (run: () => Promise<SendResult>) => Promise<SendResult> {
+  const waiting: (() => void)[] = [];
+  let active = 0;
+  // The slot is handed straight to the next waiter rather than freed and re-taken, so the count
+  // is never momentarily wrong: "free it, then let whoever wakes first claim it" only holds while
+  // nothing can run between the two, which is a scheduling detail, not an invariant.
+  const release = (): void => {
+    const next = waiting.shift();
+    if (next === undefined) active -= 1;
+    else next();
+  };
+  return async (run) => {
+    if (active >= size) await new Promise<void>((resolve) => waiting.push(resolve));
+    else active += 1;
+    try {
+      return await run();
+    } finally {
+      release();
+    }
+  };
+}
+
+export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
+  const target = parseSmtpUrl(options.url);
+  if (options.from.trim() === '') {
+    throw new ConfigInvalidError({
+      cause: 'the smtp driver was configured without a from address',
+      fix: 'set mail.from in app.config.ts to an address the SMTP server will relay for',
+    });
+  }
+  const clock = options.clock ?? systemClock;
+  const connect = options.connect ?? bunSmtpStream;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const limit = createLimiter(resolvePoolSize(options.poolSize));
+  const session: SmtpSessionOptions = {
+    clientName: options.clientName ?? addressDomain(options.from),
+    secure: target.tls,
+    allowInsecure: options.allowInsecure ?? false,
+    timeoutMs,
+    ...(target.user === undefined ? {} : { user: target.user }),
+    ...(target.password === undefined ? {} : { password: target.password }),
+  };
+  const dial: SmtpTarget = { host: target.host, port: target.port, tls: target.tls, timeoutMs };
+  // `smtps://` is encrypted from the first byte; a submission port has to be told to upgrade, or
+  // the probe named in the fix lines below opens a socket and then waits forever for a handshake.
+  const starttls = target.tls ? '' : ' -starttls smtp';
+
+  return {
+    name: 'smtp',
+    send: (message: MailMessage): Promise<SendResult> => limit(() => deliver(message)),
+  };
+
+  async function deliver(message: MailMessage): Promise<SendResult> {
+    // The Message-ID is the id the recipient's mailbox shows, so it is also the id we report: an
+    // SMTP `250` carries no identifier a caller could correlate with anything. It is deliberately
+    // NOT derived from the idempotency key — that key holds the recipient list, and a Message-ID
+    // is visible to every recipient, blind ones included.
+    const messageId = `<${message.mailId}.${nanoid(16)}@${addressDomain(options.from)}>`;
+    const data = buildMimeMessage(message, {
+      from: options.from,
+      messageId,
+      date: clock.now(),
+      boundary: `x-ultimate-${nanoid(20)}`,
+    });
+
+    const stream = await connect(dial).catch((error: unknown) => {
+      throw sendFailed({
+        driver: 'smtp',
+        stage: 'connect',
+        detail: `${target.host}:${target.port}, from SMTP_URL in .env — ${messageOf(error)}`,
+        retryable: true,
+        fix: `openssl s_client${starttls} -connect ${target.host}:${target.port}`,
+      });
+    });
+
+    try {
+      await smtpDeliver(
+        stream,
+        { from: addressSpec(options.from), recipients: envelopeRecipients(message), data },
+        session,
+      );
+      return resultFor('smtp', message, messageId);
+    } catch (error) {
+      // A framework error already names its stage; anything else (a socket reset mid-DATA) would
+      // otherwise escape as a bare Error and lose the code the queue's dead-letter view reads.
+      if (isUltimateError(error)) throw error;
+      throw sendFailed({
+        driver: 'smtp',
+        stage: 'data',
+        detail: `${messageOf(error)} — the mail log on ${target.host} records why it dropped this`,
+        retryable: true,
+        fix: `openssl s_client -crlf${starttls} -connect ${target.host}:${target.port}`,
+      });
+    } finally {
+      stream.close();
+    }
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/driver.d.ts

@@ -0,0 +1,79 @@
+/** The rendered envelope. Everything a transport needs; nothing it does not. */
+export interface MailMessage {
+    readonly mailId: string;
+    readonly to: readonly string[];
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    readonly locale: string;
+    readonly tz: string;
+    readonly replyTo?: string | undefined;
+    readonly cc?: readonly string[] | undefined;
+    readonly bcc?: readonly string[] | undefined;
+    readonly unsubscribeUrl?: string | undefined;
+    readonly idempotencyKey?: string | undefined;
+}
+export interface SendResult {
+    /** Provider message id, or a local id for the memory/log drivers. */
+    readonly id: string;
+    readonly driver: string;
+    readonly accepted: readonly string[];
+    /** True when the message was handed to the queue instead of a transport. */
+    readonly queued: boolean;
+    readonly idempotencyKey: string;
+}
+export interface MailDriver {
+    readonly name: string;
+    send(message: MailMessage): Promise<SendResult>;
+}
+/**
+ * RFC 8058 one-click unsubscribe. Gmail and Yahoo require it for bulk senders and
+ * reward it for transactional ones, so it is computed here rather than per driver.
+ */
+export declare function messageHeaders(message: MailMessage): Readonly<Record<string, string>>;
+export interface SentMail {
+    readonly at: Date;
+    readonly message: MailMessage;
+    readonly result: SendResult;
+}
+/**
+ * Dev + test driver. Retains every message it accepts and exposes them, which is what the
+ * `/_x` mail panel reads to show the last mails rendered by the running app — a real inbox
+ * is not part of the local loop.
+ */
+export interface MemoryMailDriver extends MailDriver {
+    readonly name: 'memory';
+    readonly sent: readonly SentMail[];
+    /** Newest first, so the panel and assertions do not index backwards. */
+    outbox(): readonly SentMail[];
+    lastTo(address: string): SentMail | undefined;
+    clear(): void;
+}
+export declare function createMemoryDriver(): MemoryMailDriver;
+/**
+ * Structured log line per message through core's `logger` — the default for a worker that
+ * has no credentials yet. Bodies are never logged; a mail body is user data.
+ */
+export declare function createLogDriver(logger?: import("@ultimat3/core").Logger): MailDriver;
+export interface SmtpDriverOptions {
+    /** `smtps://user:pass@host:465`. Read from `SMTP_URL`, never hardcoded. */
+    readonly url: string;
+    readonly from: string;
+    readonly poolSize?: number | undefined;
+}
+/** Interface-complete; the wire protocol is not in this build. */
+export declare function createSmtpDriver(options: SmtpDriverOptions): MailDriver;
+export interface ResendDriverOptions {
+    /** Read from `RESEND_API_KEY`. */
+    readonly apiKey: string;
+    readonly from: string;
+}
+/** Interface-complete; the HTTP call is not in this build. */
+export declare function createResendDriver(options: ResendDriverOptions): MailDriver;
+/** Set once at boot from `app.config.ts`. One driver per process, like the job driver. */
+export declare function setMailDriver(driver: MailDriver): void;
+export declare function tryMailDriver(): MailDriver | undefined;
+/** Throws `X_MAIL_DRIVER_UNAVAILABLE` rather than silently dropping mail on the floor. */
+export declare function mailDriver(): MailDriver;
+export declare function resetMailDriver(): void;
+//# sourceMappingURL=driver.d.ts.map

package/src/driver.d.ts.map

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

package/src/driver.js

@@ -0,0 +1,115 @@
+// Single responsibility: the transport seam. One `MailDriver` interface, four implementations,
+// and a module-level ambient driver so `send()` never knows which one is installed. Swapping
+// SMTP for Resend is an `app.config.ts` line and zero template changes.
+import { nanoid, logger as rootLogger } from '@ultimat3/core';
+import { driverUnavailable, transportNotImplemented } from './errors';
+/**
+ * RFC 8058 one-click unsubscribe. Gmail and Yahoo require it for bulk senders and
+ * reward it for transactional ones, so it is computed here rather than per driver.
+ */
+export function messageHeaders(message) {
+    const headers = { 'Auto-Submitted': 'auto-generated' };
+    if (message.replyTo !== undefined)
+        headers['Reply-To'] = message.replyTo;
+    if (message.unsubscribeUrl !== undefined) {
+        headers['List-Unsubscribe'] = `<${message.unsubscribeUrl}>`;
+        headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
+    }
+    return headers;
+}
+function accepted(message) {
+    return [...message.to, ...(message.cc ?? []), ...(message.bcc ?? [])];
+}
+function resultFor(driver, message, id) {
+    return {
+        id,
+        driver,
+        accepted: accepted(message),
+        queued: false,
+        idempotencyKey: message.idempotencyKey ?? id,
+    };
+}
+export function createMemoryDriver() {
+    const sent = [];
+    return {
+        name: 'memory',
+        sent,
+        send(message) {
+            const result = resultFor('memory', message, `mem_${nanoid(12)}`);
+            sent.push({ at: new Date(), message, result });
+            return Promise.resolve(result);
+        },
+        outbox: () => [...sent].reverse(),
+        lastTo: (address) => [...sent].reverse().find((entry) => entry.message.to.includes(address)),
+        clear: () => {
+            sent.length = 0;
+        },
+    };
+}
+/**
+ * Structured log line per message through core's `logger` — the default for a worker that
+ * has no credentials yet. Bodies are never logged; a mail body is user data.
+ */
+export function createLogDriver(logger = rootLogger) {
+    return {
+        name: 'log',
+        send(message) {
+            const result = resultFor('log', message, `log_${nanoid(12)}`);
+            logger.info('mail.send', {
+                mailId: message.mailId,
+                to: message.to.length,
+                subject: message.subject,
+                locale: message.locale,
+                idempotencyKey: result.idempotencyKey,
+            });
+            return Promise.resolve(result);
+        },
+    };
+}
+/** Interface-complete; the wire protocol is not in this build. */
+export function createSmtpDriver(options) {
+    return {
+        name: 'smtp',
+        send(_message) {
+            throw transportNotImplemented('smtp', `set SMTP_URL (currently "${redactUrl(options.url)}") and run: x mail doctor --json`);
+        },
+    };
+}
+/** Interface-complete; the HTTP call is not in this build. */
+export function createResendDriver(options) {
+    return {
+        name: 'resend',
+        send(_message) {
+            const state = options.apiKey === '' ? 'empty' : 'set';
+            throw transportNotImplemented('resend', `set RESEND_API_KEY (currently ${state}), then run: x mail doctor --json`);
+        },
+    };
+}
+function redactUrl(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.password = '';
+        return parsed.href;
+    }
+    catch {
+        return 'not a URL';
+    }
+}
+let ambient;
+/** Set once at boot from `app.config.ts`. One driver per process, like the job driver. */
+export function setMailDriver(driver) {
+    ambient = driver;
+}
+export function tryMailDriver() {
+    return ambient;
+}
+/** Throws `X_MAIL_DRIVER_UNAVAILABLE` rather than silently dropping mail on the floor. */
+export function mailDriver() {
+    if (ambient === undefined)
+        throw driverUnavailable('setMailDriver() was never called');
+    return ambient;
+}
+export function resetMailDriver() {
+    ambient = undefined;
+}
+//# sourceMappingURL=driver.js.map

package/src/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["driver.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,6FAA6F;AAC7F,wEAAwE;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAiCtE;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,MAAM,OAAO,GAA2B,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;IAC/E,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IACzE,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,OAAO,CAAC,cAAc,GAAG,CAAC;QAC5D,OAAO,CAAC,uBAAuB,CAAC,GAAG,4BAA4B,CAAC;IAClE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,QAAQ,CAAC,OAAoB;IACpC,OAAO,CAAC,GAAG,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,OAAoB,EAAE,EAAU;IACjE,OAAO;QACL,EAAE;QACF,MAAM;QACN,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC3B,MAAM,EAAE,KAAK;QACb,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,EAAE;KAC7C,CAAC;AACJ,CAAC;AAsBD,MAAM,UAAU,kBAAkB;IAChC,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,IAAI;QACJ,IAAI,CAAC,OAAoB;YACvB,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACjE,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/C,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE;QACjC,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC5F,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAM,GAAG,UAAU;IACjD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,IAAI,CAAC,OAAoB;YACvB,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;gBACvB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,MAAM;gBACrB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,cAAc,EAAE,MAAM,CAAC,cAAc;aACtC,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC;AASD,kEAAkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,CAAC,QAAqB;YACxB,MAAM,uBAAuB,CAC3B,MAAM,EACN,4BAA4B,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAkC,CACrF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAQD,8DAA8D;AAC9D,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,IAAI,CAAC,QAAqB;YACxB,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;YACtD,MAAM,uBAAuB,CAC3B,QAAQ,EACR,iCAAiC,KAAK,mCAAmC,CAC1E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC;QACrB,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC;AAED,IAAI,OAA+B,CAAC;AAEpC,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,MAAkB;IAC9C,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,UAAU;IACxB,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,iBAAiB,CAAC,kCAAkC,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}