@warlock.js/core 5.23.2 → 5.25.0

package/esm/mail/send-mail.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"send-mail.mjs","names":[],"sources":["../../../../../../../core/src/mail/send-mail.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { readFile } from \"node:fs/promises\";\nimport type { Options as NodemailerOptions } from \"nodemailer/lib/mailer\";\nimport { isDevelopmentMode, isTestMode, resolveMailConfig } from \"./config\";\nimport { MAIL_EVENTS, generateMailId, mailEvents } from \"./events\";\nimport { getMailer } from \"./mailer-pool\";\nimport { renderReactMail } from \"./react-mail\";\nimport { captureMail } from \"./test-mailbox\";\nimport {\n  MailError,\n  type CapturedMail,\n  type MailAttachment,\n  type MailOptions,\n  type MailPriority,\n  type MailResult,\n  type NormalizedMail,\n} from \"./types\";\n\n/**\n * Normalize recipients to array\n */\nfunction normalizeRecipients(recipients: string | string[] | undefined): string[] {\n  if (!recipients) {\n    return [];\n  }\n\n  return Array.isArray(recipients) ? recipients : [recipients];\n}\n\n/**\n * Map priority to nodemailer format\n */\nfunction mapPriority(priority: MailPriority): \"high\" | \"normal\" | \"low\" {\n  return priority;\n}\n\n/**\n * Normalize mail options to internal format\n */\nfunction normalizeMail(options: MailOptions): NormalizedMail {\n  const config = resolveMailConfig(options);\n\n  return {\n    to: normalizeRecipients(options.to),\n    cc: normalizeRecipients(options.cc),\n    bcc: normalizeRecipients(options.bcc),\n    replyTo: options.replyTo,\n    from: options.from || config.from || { name: \"No Reply\", address: \"noreply@localhost\" },\n    subject: options.subject,\n    html: options.html,\n    text: options.text,\n    attachments: options.attachments || [],\n    priority: options.priority || \"normal\",\n    headers: options.headers || {},\n    tags: options.tags || [],\n    correlationId: options.correlationId,\n    config,\n  };\n}\n\n/**\n * Resolve attachment - read file if path is provided\n */\nasync function resolveAttachment(attachment: MailAttachment): Promise<{\n  filename: string;\n  content: Buffer | string;\n  contentType?: string;\n  encoding?: string;\n  cid?: string;\n}> {\n  // If path is provided, read the file\n  if (attachment.path) {\n    try {\n      const content = await readFile(attachment.path);\n      return {\n        filename: attachment.filename,\n        content,\n        contentType: attachment.contentType,\n        encoding: attachment.encoding,\n        cid: attachment.cid,\n      };\n    } catch (error) {\n      throw new MailError(\n        `Failed to read attachment file \"${attachment.path}\": ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"CONFIG_ERROR\",\n        error instanceof Error ? error : undefined,\n      );\n    }\n  }\n\n  // Already has content\n  return {\n    filename: attachment.filename,\n    content: attachment.content!,\n    contentType: attachment.contentType,\n    encoding: attachment.encoding,\n    cid: attachment.cid,\n  };\n}\n\n/**\n * Build nodemailer options from normalized mail\n */\nasync function buildNodemailerOptions(normalized: NormalizedMail): Promise<NodemailerOptions> {\n  const options: NodemailerOptions = {\n    to: normalized.to,\n    // nodemailer encodes/escapes {name, address} objects itself\n    from: normalized.from,\n    subject: normalized.subject,\n    priority: mapPriority(normalized.priority),\n  };\n\n  if (normalized.cc.length > 0) {\n    options.cc = normalized.cc;\n  }\n\n  if (normalized.bcc.length > 0) {\n    options.bcc = normalized.bcc;\n  }\n\n  if (normalized.replyTo) {\n    options.replyTo = normalized.replyTo;\n  }\n\n  if (normalized.html) {\n    options.html = normalized.html;\n  }\n\n  if (normalized.text) {\n    options.text = normalized.text;\n  }\n\n  if (normalized.attachments.length > 0) {\n    // Resolve all attachments (read files if needed)\n    const resolvedAttachments = await Promise.all(\n      normalized.attachments.map((att) => resolveAttachment(att as MailAttachment)),\n    );\n\n    options.attachments = resolvedAttachments.map((att) => ({\n      filename: att.filename,\n      content: att.content,\n      contentType: att.contentType,\n      encoding: att.encoding,\n      cid: att.cid,\n    }));\n  }\n\n  if (Object.keys(normalized.headers).length > 0) {\n    options.headers = normalized.headers;\n  }\n\n  return options;\n}\n\n/**\n * Map a send failure to a MailError code, preferring nodemailer's `code` / `responseCode`\n */\nfunction detectErrorCode(error: unknown): MailError[\"code\"] {\n  if (error instanceof MailError) {\n    return error.code;\n  }\n\n  const { code, responseCode } = (error ?? {}) as { code?: string; responseCode?: number };\n\n  if (code === \"EAUTH\" || responseCode === 535 || responseCode === 534) return \"AUTH_ERROR\";\n\n  if ([\"ECONNECTION\", \"ECONNREFUSED\", \"ENOTFOUND\", \"ESOCKET\"].includes(code as string)) {\n    return \"CONNECTION_ERROR\";\n  }\n\n  if ([\"ETIMEDOUT\", \"ETIMEOUT\", \"ECONNECTIONTIMEOUT\"].includes(code as string)) return \"TIMEOUT\";\n  if (code === \"EENVELOPE\") return \"INVALID_ADDRESS\";\n  if (responseCode && [421, 450, 451, 452].includes(responseCode)) return \"RATE_LIMIT\";\n\n  const message = error instanceof Error ? error.message : \"\";\n\n  if (message.includes(\"ECONNREFUSED\") || message.includes(\"ENOTFOUND\")) return \"CONNECTION_ERROR\";\n  if (message.includes(\"authentication\") || message.includes(\"auth\")) return \"AUTH_ERROR\";\n  if (message.includes(\"timeout\") || message.includes(\"ETIMEDOUT\")) return \"TIMEOUT\";\n  if (message.includes(\"rate\") || message.includes(\"limit\")) return \"RATE_LIMIT\";\n\n  return \"UNKNOWN\";\n}\n\n/**\n * Run per-mail event handler\n */\nasync function runMailEvent<T extends (...args: any[]) => any>(\n  handler: T | undefined,\n  ...args: Parameters<T>\n): Promise<ReturnType<T> | undefined> {\n  if (!handler) {\n    return undefined;\n  }\n\n  try {\n    return await handler(...args);\n  } catch (error) {\n    log.error(\"mail\", \"event\", `Per-mail event handler error: ${error}`);\n    return undefined;\n  }\n}\n\n/**\n * Trigger both global and mail-specific events\n */\nasync function triggerEvents(\n  mailId: string,\n  event: \"beforeSending\" | \"sent\" | \"success\" | \"error\",\n  ...args: any[]\n): Promise<any[]> {\n  try {\n    // Trigger global event (e.g., mail.success)\n    const globalEventName =\n      event === \"beforeSending\"\n        ? \"BEFORE_SENDING\"\n        : event === \"sent\"\n          ? \"SENT\"\n          : event === \"success\"\n            ? \"SUCCESS\"\n            : \"ERROR\";\n\n    const globalResults = await mailEvents.trigger(\n      globalEventName as keyof typeof MAIL_EVENTS,\n      ...args,\n    );\n\n    // Trigger mail-specific event (e.g., mail.$id.success)\n    const specificResults = await mailEvents.triggerForMail(mailId, event, ...args);\n\n    return [...(globalResults || []), ...(specificResults || [])];\n  } catch (error) {\n    log.error(\"mail\", \"event\", `Event handler error: ${error}`);\n    return [];\n  }\n}\n\n/**\n * Send an email\n *\n * @param options Mail options including recipients, content, and configuration\n * @returns Result containing success status, message ID, and accepted/rejected recipients\n *\n * @example\n * ```typescript\n * // Basic usage\n * await sendMail({\n *   to: \"user@example.com\",\n *   subject: \"Hello\",\n *   html: \"<p>World</p>\",\n * });\n *\n * // With React component\n * await sendMail({\n *   to: \"user@example.com\",\n *   subject: \"Welcome!\",\n *   component: <WelcomeEmail name=\"John\" />,\n * });\n *\n * // Track specific mail with events\n * const mailId = generateMailId();\n * mailEvents.onMailSuccess(mailId, (mail, result) => {\n *   console.log(\"This specific mail was sent!\");\n * });\n * await sendMail({ id: mailId, to: \"...\", subject: \"...\", html: \"...\" });\n * ```\n */\nexport async function sendMail(options: MailOptions): Promise<MailResult> {\n  // Generate or use provided mail ID\n  const mailId = options.id || generateMailId();\n\n  // Render React component if provided\n  if (options.component) {\n    try {\n      options.html = await renderReactMail(options.component);\n    } catch (error) {\n      const mailError = new MailError(\n        `Failed to render React component: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"RENDER_ERROR\",\n        error instanceof Error ? error : undefined,\n      );\n\n      await runMailEvent(options.onError, options, mailError);\n      await triggerEvents(mailId, \"error\", options, mailError);\n\n      throw mailError;\n    }\n  }\n\n  // Normalize mail\n  const normalized = normalizeMail(options);\n  const driver = normalized.config.driver || \"smtp\";\n\n  // Run beforeSending event (per-mail, global, and mail-specific)\n  const beforeResult = await runMailEvent(options.beforeSending, options);\n  const globalBeforeResults = await triggerEvents(mailId, \"beforeSending\", options);\n\n  // If any returns false, cancel sending\n  if (beforeResult === false || globalBeforeResults.some((r) => r === false)) {\n    log.info(`mail.${driver}`, \"cancelled\", \"Mail sending cancelled by beforeSending event\");\n\n    const result: MailResult = {\n      success: false,\n      accepted: [],\n      rejected: normalized.to,\n      response: \"Cancelled by beforeSending event\",\n    };\n\n    return result;\n  }\n\n  // Test mode - capture without sending\n  if (isTestMode()) {\n    log.info(`mail.${driver}`, \"test\", `[TEST MODE] Captured mail to: ${normalized.to.join(\", \")}`);\n\n    const result: MailResult = {\n      success: true,\n      messageId: `test-${mailId}@localhost`,\n      accepted: normalized.to,\n      rejected: [],\n      response: \"Test mode - mail captured\",\n    };\n\n    const captured: CapturedMail = {\n      options,\n      normalized,\n      timestamp: new Date(),\n      result,\n    };\n\n    captureMail(captured);\n\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  }\n\n  // Development mode - log without sending\n  if (isDevelopmentMode()) {\n    log.info(`mail.${driver}`, \"dev\", `[DEV MODE] Would send mail to: ${normalized.to.join(\", \")}`);\n    log.info(`mail.${driver}`, \"dev\", `Subject: ${normalized.subject}`);\n\n    if (normalized.html) {\n      log.info(`mail.${driver}`, \"dev\", `HTML length: ${normalized.html.length} chars`);\n    }\n\n    const result: MailResult = {\n      success: true,\n      messageId: `dev-${mailId}@localhost`,\n      accepted: normalized.to,\n      rejected: [],\n      response: \"Development mode - mail logged\",\n    };\n\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  }\n\n  // Production mode - actually send\n  try {\n    const config = resolveMailConfig(options);\n    const mailer = await getMailer(config);\n    const nodemailerOptions = await buildNodemailerOptions(normalized);\n\n    log.info(`mail.${driver}`, \"send\", `Sending mail to: ${normalized.to.join(\", \")}`);\n\n    const output = await mailer.sendMail(nodemailerOptions);\n\n    const accepted = output.accepted || (output.messageId ? normalized.to : []);\n    const rejected = output.rejected || [];\n\n    if (accepted.length === 0) {\n      throw new MailError(\n        `All recipients were rejected: ${(rejected as string[]).join(\", \")}`,\n        \"REJECTED\",\n      );\n    }\n\n    const result: MailResult = {\n      success: true,\n      messageId: output.messageId,\n      accepted: accepted as string[],\n      rejected: rejected as string[],\n      response: output.response,\n      envelope: output.envelope,\n    };\n\n    if (rejected.length > 0) {\n      log.warn(`mail.${driver}`, \"partial\", `Mail partially rejected: ${rejected.join(\", \")}`);\n    }\n\n    log.success(`mail.${driver}`, \"sent\", `Mail sent successfully (ID: ${result.messageId})`);\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  } catch (error) {\n    const errorMessage = error instanceof Error ? error.message : \"Unknown error\";\n    const code = detectErrorCode(error);\n\n    const mailError = new MailError(\n      `Failed to send mail: ${errorMessage}`,\n      code,\n      error instanceof Error ? error : undefined,\n    );\n\n    log.error(`mail.${driver}`, \"error\", mailError.message);\n\n    await runMailEvent(options.onError, options, mailError);\n    await triggerEvents(mailId, \"error\", options, mailError);\n    await runMailEvent(options.onSent, options, null, mailError);\n    await triggerEvents(mailId, \"sent\", options, null, mailError);\n\n    throw mailError;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"send-mail.mjs","names":[],"sources":["../../../../../../../core/src/mail/send-mail.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { readFile } from \"node:fs/promises\";\nimport type { Options as NodemailerOptions } from \"nodemailer/lib/mailer\";\nimport { isDevelopmentMode, isTestMode, resolveMailConfig } from \"./config\";\nimport { MAIL_EVENTS, generateMailId, mailEvents } from \"./events\";\nimport { getMailer } from \"./mailer-pool\";\nimport { renderReactMail } from \"./react-mail\";\nimport { captureMail } from \"./test-mailbox\";\nimport {\n  MailError,\n  type CapturedMail,\n  type MailAttachment,\n  type MailOptions,\n  type MailPriority,\n  type MailResult,\n  type NormalizedMail,\n} from \"./types\";\n\n/**\n * Normalize recipients to array\n */\nfunction normalizeRecipients(recipients: string | string[] | undefined): string[] {\n  if (!recipients) {\n    return [];\n  }\n\n  return Array.isArray(recipients) ? recipients : [recipients];\n}\n\n/**\n * Map priority to nodemailer format\n */\nfunction mapPriority(priority: MailPriority): \"high\" | \"normal\" | \"low\" {\n  return priority;\n}\n\n/**\n * Normalize mail options to internal format\n */\nfunction normalizeMail(options: MailOptions): NormalizedMail {\n  const config = resolveMailConfig(options);\n\n  return {\n    to: normalizeRecipients(options.to),\n    cc: normalizeRecipients(options.cc),\n    bcc: normalizeRecipients(options.bcc),\n    replyTo: options.replyTo,\n    from: options.from || config.from || { name: \"No Reply\", address: \"noreply@localhost\" },\n    subject: options.subject,\n    html: options.html,\n    text: options.text,\n    attachments: options.attachments || [],\n    priority: options.priority || \"normal\",\n    headers: options.headers || {},\n    tags: options.tags || [],\n    correlationId: options.correlationId,\n    config,\n  };\n}\n\n/**\n * Resolve attachment - read file if path is provided\n */\nasync function resolveAttachment(attachment: MailAttachment): Promise<{\n  filename: string;\n  content: Buffer | string;\n  contentType?: string;\n  encoding?: string;\n  cid?: string;\n}> {\n  // If path is provided, read the file\n  if (attachment.path) {\n    try {\n      const content = await readFile(attachment.path);\n      return {\n        filename: attachment.filename,\n        content,\n        contentType: attachment.contentType,\n        encoding: attachment.encoding,\n        cid: attachment.cid,\n      };\n    } catch (error) {\n      throw new MailError(\n        `Failed to read attachment file \"${attachment.path}\": ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"CONFIG_ERROR\",\n        error instanceof Error ? error : undefined,\n      );\n    }\n  }\n\n  // Already has content\n  return {\n    filename: attachment.filename,\n    content: attachment.content!,\n    contentType: attachment.contentType,\n    encoding: attachment.encoding,\n    cid: attachment.cid,\n  };\n}\n\n/**\n * Build nodemailer options from normalized mail\n */\nasync function buildNodemailerOptions(normalized: NormalizedMail): Promise<NodemailerOptions> {\n  const options: NodemailerOptions = {\n    to: normalized.to,\n    // nodemailer encodes/escapes {name, address} objects itself\n    from: normalized.from,\n    subject: normalized.subject,\n    priority: mapPriority(normalized.priority),\n  };\n\n  if (normalized.cc.length > 0) {\n    options.cc = normalized.cc;\n  }\n\n  if (normalized.bcc.length > 0) {\n    options.bcc = normalized.bcc;\n  }\n\n  if (normalized.replyTo) {\n    options.replyTo = normalized.replyTo;\n  }\n\n  if (normalized.html) {\n    options.html = normalized.html;\n  }\n\n  if (normalized.text) {\n    options.text = normalized.text;\n  }\n\n  if (normalized.attachments.length > 0) {\n    // Resolve all attachments (read files if needed)\n    const resolvedAttachments = await Promise.all(\n      normalized.attachments.map((att) => resolveAttachment(att as MailAttachment)),\n    );\n\n    options.attachments = resolvedAttachments.map((att) => ({\n      filename: att.filename,\n      content: att.content,\n      contentType: att.contentType,\n      encoding: att.encoding,\n      cid: att.cid,\n    }));\n  }\n\n  if (Object.keys(normalized.headers).length > 0) {\n    options.headers = normalized.headers;\n  }\n\n  return options;\n}\n\n/**\n * Map a send failure to a MailError code, preferring nodemailer's `code` / `responseCode`\n */\nfunction detectErrorCode(error: unknown): MailError[\"code\"] {\n  if (error instanceof MailError) {\n    return error.code;\n  }\n\n  const { code, responseCode } = (error ?? {}) as { code?: string; responseCode?: number };\n\n  if (code === \"EAUTH\" || responseCode === 535 || responseCode === 534) return \"AUTH_ERROR\";\n\n  if ([\"ECONNECTION\", \"ECONNREFUSED\", \"ENOTFOUND\", \"ESOCKET\"].includes(code as string)) {\n    return \"CONNECTION_ERROR\";\n  }\n\n  if ([\"ETIMEDOUT\", \"ETIMEOUT\", \"ECONNECTIONTIMEOUT\"].includes(code as string)) return \"TIMEOUT\";\n  if (code === \"EENVELOPE\") return \"INVALID_ADDRESS\";\n  if (responseCode && [421, 450, 451, 452].includes(responseCode)) return \"RATE_LIMIT\";\n\n  const message = error instanceof Error ? error.message : \"\";\n\n  if (message.includes(\"ECONNREFUSED\") || message.includes(\"ENOTFOUND\")) return \"CONNECTION_ERROR\";\n  if (message.includes(\"authentication\") || message.includes(\"auth\")) return \"AUTH_ERROR\";\n  if (message.includes(\"timeout\") || message.includes(\"ETIMEDOUT\")) return \"TIMEOUT\";\n  if (message.includes(\"rate\") || message.includes(\"limit\")) return \"RATE_LIMIT\";\n\n  return \"UNKNOWN\";\n}\n\n/**\n * Run per-mail event handler\n */\nasync function runMailEvent<T extends (...args: any[]) => any>(\n  handler: T | undefined,\n  ...args: Parameters<T>\n): Promise<ReturnType<T> | undefined> {\n  if (!handler) {\n    return undefined;\n  }\n\n  try {\n    return await handler(...args);\n  } catch (error) {\n    log.error(\"mail\", \"event\", `Per-mail event handler error: ${error}`);\n    return undefined;\n  }\n}\n\n/**\n * Trigger both global and mail-specific events\n */\nasync function triggerEvents(\n  mailId: string,\n  event: \"beforeSending\" | \"sent\" | \"success\" | \"error\",\n  ...args: any[]\n): Promise<any[]> {\n  try {\n    // Trigger global event (e.g., mail.success)\n    const globalEventName =\n      event === \"beforeSending\"\n        ? \"BEFORE_SENDING\"\n        : event === \"sent\"\n          ? \"SENT\"\n          : event === \"success\"\n            ? \"SUCCESS\"\n            : \"ERROR\";\n\n    const globalResults = await mailEvents.trigger(\n      globalEventName as keyof typeof MAIL_EVENTS,\n      ...args,\n    );\n\n    // Trigger mail-specific event (e.g., mail.$id.success)\n    const specificResults = await mailEvents.triggerForMail(mailId, event, ...args);\n\n    return [...(globalResults || []), ...(specificResults || [])];\n  } catch (error) {\n    log.error(\"mail\", \"event\", `Event handler error: ${error}`);\n    return [];\n  }\n}\n\n/**\n * Notify development and test tooling of a captured mail without allowing a\n * synchronous listener failure to interrupt delivery.\n */\nfunction triggerCapturedMail(captured: CapturedMail): void {\n  try {\n    mailEvents.trigger(\"CAPTURED\", captured);\n  } catch (error) {\n    log.error(\"mail\", \"event\", `Captured mail event handler error: ${error}`);\n  }\n}\n\n/**\n * Send an email\n *\n * @param options Mail options including recipients, content, and configuration\n * @returns Result containing success status, message ID, and accepted/rejected recipients\n *\n * @example\n * ```typescript\n * // Basic usage\n * await sendMail({\n *   to: \"user@example.com\",\n *   subject: \"Hello\",\n *   html: \"<p>World</p>\",\n * });\n *\n * // With React component\n * await sendMail({\n *   to: \"user@example.com\",\n *   subject: \"Welcome!\",\n *   component: <WelcomeEmail name=\"John\" />,\n * });\n *\n * // Track specific mail with events\n * const mailId = generateMailId();\n * mailEvents.onMailSuccess(mailId, (mail, result) => {\n *   console.log(\"This specific mail was sent!\");\n * });\n * await sendMail({ id: mailId, to: \"...\", subject: \"...\", html: \"...\" });\n * ```\n */\nexport async function sendMail(options: MailOptions): Promise<MailResult> {\n  // Generate or use provided mail ID\n  const mailId = options.id || generateMailId();\n\n  // Render React component if provided\n  if (options.component) {\n    try {\n      options.html = await renderReactMail(options.component);\n    } catch (error) {\n      const mailError = new MailError(\n        `Failed to render React component: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"RENDER_ERROR\",\n        error instanceof Error ? error : undefined,\n      );\n\n      await runMailEvent(options.onError, options, mailError);\n      await triggerEvents(mailId, \"error\", options, mailError);\n\n      throw mailError;\n    }\n  }\n\n  // Normalize mail\n  const normalized = normalizeMail(options);\n  const driver = normalized.config.driver || \"smtp\";\n\n  // Run beforeSending event (per-mail, global, and mail-specific)\n  const beforeResult = await runMailEvent(options.beforeSending, options);\n  const globalBeforeResults = await triggerEvents(mailId, \"beforeSending\", options);\n\n  // If any returns false, cancel sending\n  if (beforeResult === false || globalBeforeResults.some((r) => r === false)) {\n    log.info(`mail.${driver}`, \"cancelled\", \"Mail sending cancelled by beforeSending event\");\n\n    const result: MailResult = {\n      success: false,\n      accepted: [],\n      rejected: normalized.to,\n      response: \"Cancelled by beforeSending event\",\n    };\n\n    return result;\n  }\n\n  // Test mode - capture without sending\n  if (isTestMode()) {\n    log.info(`mail.${driver}`, \"test\", `[TEST MODE] Captured mail to: ${normalized.to.join(\", \")}`);\n\n    const result: MailResult = {\n      success: true,\n      messageId: `test-${mailId}@localhost`,\n      accepted: normalized.to,\n      rejected: [],\n      response: \"Test mode - mail captured\",\n    };\n\n    const captured: CapturedMail = {\n      id: mailId,\n      options,\n      normalized,\n      timestamp: new Date(),\n      result,\n    };\n\n    captureMail(captured);\n    triggerCapturedMail(captured);\n\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  }\n\n  // Development mode - log without sending\n  if (isDevelopmentMode()) {\n    log.info(`mail.${driver}`, \"dev\", `[DEV MODE] Would send mail to: ${normalized.to.join(\", \")}`);\n    log.info(`mail.${driver}`, \"dev\", `Subject: ${normalized.subject}`);\n\n    if (normalized.html) {\n      log.info(`mail.${driver}`, \"dev\", `HTML length: ${normalized.html.length} chars`);\n    }\n\n    const result: MailResult = {\n      success: true,\n      messageId: `dev-${mailId}@localhost`,\n      accepted: normalized.to,\n      rejected: [],\n      response: \"Development mode - mail logged\",\n    };\n\n    const captured: CapturedMail = {\n      id: mailId,\n      options,\n      normalized,\n      timestamp: new Date(),\n      result,\n    };\n\n    triggerCapturedMail(captured);\n\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  }\n\n  // Production mode - actually send\n  try {\n    const config = resolveMailConfig(options);\n    const mailer = await getMailer(config);\n    const nodemailerOptions = await buildNodemailerOptions(normalized);\n\n    log.info(`mail.${driver}`, \"send\", `Sending mail to: ${normalized.to.join(\", \")}`);\n\n    const output = await mailer.sendMail(nodemailerOptions);\n\n    const accepted = output.accepted || (output.messageId ? normalized.to : []);\n    const rejected = output.rejected || [];\n\n    if (accepted.length === 0) {\n      throw new MailError(\n        `All recipients were rejected: ${(rejected as string[]).join(\", \")}`,\n        \"REJECTED\",\n      );\n    }\n\n    const result: MailResult = {\n      success: true,\n      messageId: output.messageId,\n      accepted: accepted as string[],\n      rejected: rejected as string[],\n      response: output.response,\n      envelope: output.envelope,\n    };\n\n    if (rejected.length > 0) {\n      log.warn(`mail.${driver}`, \"partial\", `Mail partially rejected: ${rejected.join(\", \")}`);\n    }\n\n    log.success(`mail.${driver}`, \"sent\", `Mail sent successfully (ID: ${result.messageId})`);\n    await runMailEvent(options.onSuccess, options, result);\n    await triggerEvents(mailId, \"success\", options, result);\n\n    await runMailEvent(options.onSent, options, result, null);\n    await triggerEvents(mailId, \"sent\", options, result, null);\n\n    return result;\n  } catch (error) {\n    const errorMessage = error instanceof Error ? error.message : \"Unknown error\";\n    const code = detectErrorCode(error);\n\n    const mailError = new MailError(\n      `Failed to send mail: ${errorMessage}`,\n      code,\n      error instanceof Error ? error : undefined,\n    );\n\n    log.error(`mail.${driver}`, \"error\", mailError.message);\n\n    await runMailEvent(options.onError, options, mailError);\n    await triggerEvents(mailId, \"error\", options, mailError);\n    await runMailEvent(options.onSent, options, null, mailError);\n    await triggerEvents(mailId, \"sent\", options, null, mailError);\n\n    throw mailError;\n  }\n}\n"],"mappings":"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"}

package/esm/mail/types.d.mts

@@ -245,9 +245,13 @@ type NormalizedMail = {
   config: MailConfigurations;
 };
 /**
- * Captured mail for test mode
+ * Captured mail for development and test modes.
+ *
+ * Attachments retain their normalized contents so test assertions can inspect
+ * the exact mail that would be sent.
  */
 type CapturedMail = {
+  /** The mail ID used for event namespacing and result correlation. */id: string;
   options: MailOptions;
   normalized: NormalizedMail;
   timestamp: Date;

package/esm/mail/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/mail/types.ts"],"mappings":";;;;;;AAMA;KAAY,iBAAA;EACV,MAAA;EACA,WAAA;EACA,eAAA;EACA,MAAA;EACA,IAAA,GAAO,WAAW;AAAA;;;;KAMR,kBAAA,GAAqB,kBAAA,GAAqB,iBAAiB;AAAvE;;;AAAA,KAKY,QAAA;AAL2D;AAKvE;;AALuE,KAU3D,YAAA;;AALQ;AAKpB;KAKY,WAAA;EAGN,IAAA;EACA,OAAO;AAAA;AAJb;;;;AAAA,KAWY,cAAA;EACV,QAAA;EACA,WAAA;EACA,QAAA;EACA,GAAA;AAAA;EAGI,OAAA,EAAS,MAAM;EACf,IAAA;AAAA;EAGA,OAAA;EACA,IAAA;AAAA;;;;AAAI;AAqEV;;;;;;;;;;;;;AAwBoB;AAMpB;;;;;;;;;;;;;;AAQ6C;AAM7C;;;;;;;;;;;;;AAQM;AAON;;;;AAAyB;AAezB;;;;;;;;;;;;;KA1EY,kBAAA,GAAqB,aAAA,CAAc,OAAA;EA+FR;;;EA3FrC,MAAA;EA2EA;;;;EAtEA,GAAA;EA0EA;;;;EArEA,QAAA;EAwES;;;;EAnET,QAAA;EAwEa;;;;EAnEb,IAAA,GAAO,WAAW;AAAA;;;;KAMR,aAAA;EAiEuD;AAAA;AAMnE;EAnEE,OAAA,GAAU,kBAAA;;;;EAIV,OAAA,GAAU,MAAA,SAAe,kBAAA;AAAA;;;;KAMf,UAAA;EACV,OAAA;EACA,SAAA;EACA,QAAA;EACA,QAAA;EACA,QAAA;EACA,QAAA;IACE,IAAA;IACA,EAAA;EAAA;AAAA;;;;KAOQ,aAAA;;;;;KAeA,UAAA;EA8DV;;;;EAzDA,aAAA,IAAiB,IAAA,EAAM,WAAA,YAAuB,OAAA,iBAAwB,OAAA;EA8DtE;;;EA1DA,MAAA,IACE,IAAA,EAAM,WAAA,EACN,MAAA,EAAQ,UAAA,SACR,KAAA,EAAO,SAAA,mBACG,OAAA;EA4DF;;;EAxDV,SAAA,IAAa,IAAA,EAAM,WAAA,EAAa,MAAA,EAAQ,UAAA,YAAsB,OAAA;EAiEjD;;;EA7Db,OAAA,IAAW,IAAA,EAAM,WAAA,EAAa,KAAA,EAAO,SAAA,YAAqB,OAAA;AAAA;;;;KAMhD,WAAA;EAkDV;;;;;;;;;;;EAtCA,EAAA;EAGA,EAAA;EACA,EAAA;EACA,GAAA;EACA,OAAA;EAGA,OAAA;EACA,IAAA;EACA,IAAA;EACA,SAAA,GAAY,KAAA,CAAM,YAAA;EAGlB,MAAA,GAAS,kBAAA;EACT,MAAA;EACA,IAAA,GAAO,WAAA;EAGP,WAAA,GAAc,cAAA;EAGd,QAAA,GAAW,YAAA;EACX,OAAA,GAAU,MAAA;EACV,IAAA;EAGA,aAAA;AAAA,IACE,UAAA;;;;KAKQ,cAAA;EACV,EAAA;EACA,EAAA;EACA,GAAA;EACA,OAAA;EACA,IAAA,EAAM,WAAA;EACN,OAAA;EACA,IAAA;EACA,IAAA;EACA,WAAA,EAAa,cAAA;EACb,QAAA,EAAU,YAAA;EACV,OAAA,EAAS,MAAA;EACT,IAAA;EACA,aAAA;EACA,MAAA,EAAQ,kBAAA;AAAA;;;;KAME,YAAA;EACV,OAAA,EAAS,WAAA;EACT,UAAA,EAAY,cAAA;EACZ,SAAA,EAAW,IAAA;EACX,MAAA,GAAS,UAAA;EACT,KAAA,GAAQ,SAAA;AAAA;;;;cAMG,SAAA,SAAkB,KAAA;EAAA,SACb,IAAA,EAAM,aAAA;EAAA,SACN,aAAA,GAAgB,KAAA;cAEb,OAAA,UAAiB,IAAA,EAAM,aAAA,EAAe,aAAA,GAAgB,KAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/mail/types.ts"],"mappings":";;;;;;AAMA;KAAY,iBAAA;EACV,MAAA;EACA,WAAA;EACA,eAAA;EACA,MAAA;EACA,IAAA,GAAO,WAAW;AAAA;;;;KAMR,kBAAA,GAAqB,kBAAA,GAAqB,iBAAiB;AAAvE;;;AAAA,KAKY,QAAA;AAL2D;AAKvE;;AALuE,KAU3D,YAAA;;AALQ;AAKpB;KAKY,WAAA;EAGN,IAAA;EACA,OAAO;AAAA;AAJb;;;;AAAA,KAWY,cAAA;EACV,QAAA;EACA,WAAA;EACA,QAAA;EACA,GAAA;AAAA;EAGI,OAAA,EAAS,MAAM;EACf,IAAA;AAAA;EAGA,OAAA;EACA,IAAA;AAAA;;;;AAAI;AAqEV;;;;;;;;;;;;;AAwBoB;AAMpB;;;;;;;;;;;;;;AAQ6C;AAM7C;;;;;;;;;;;;;AAQM;AAON;;;;AAAyB;AAezB;;;;;;;;;;;;;KA1EY,kBAAA,GAAqB,aAAA,CAAc,OAAA;EA+FR;;;EA3FrC,MAAA;EA2EA;;;;EAtEA,GAAA;EA0EA;;;;EArEA,QAAA;EAwES;;;;EAnET,QAAA;EAwEa;;;;EAnEb,IAAA,GAAO,WAAW;AAAA;;;;KAMR,aAAA;EAiEuD;AAAA;AAMnE;EAnEE,OAAA,GAAU,kBAAA;;;;EAIV,OAAA,GAAU,MAAA,SAAe,kBAAA;AAAA;;;;KAMf,UAAA;EACV,OAAA;EACA,SAAA;EACA,QAAA;EACA,QAAA;EACA,QAAA;EACA,QAAA;IACE,IAAA;IACA,EAAA;EAAA;AAAA;;;;KAOQ,aAAA;;;;;KAeA,UAAA;EA8DV;;;;EAzDA,aAAA,IAAiB,IAAA,EAAM,WAAA,YAAuB,OAAA,iBAAwB,OAAA;EA8DtE;;;EA1DA,MAAA,IACE,IAAA,EAAM,WAAA,EACN,MAAA,EAAQ,UAAA,SACR,KAAA,EAAO,SAAA,mBACG,OAAA;EA4DF;;;EAxDV,SAAA,IAAa,IAAA,EAAM,WAAA,EAAa,MAAA,EAAQ,UAAA,YAAsB,OAAA;EAiEjD;;;EA7Db,OAAA,IAAW,IAAA,EAAM,WAAA,EAAa,KAAA,EAAO,SAAA,YAAqB,OAAA;AAAA;;;;KAMhD,WAAA;EAkDV;;;;;;;;;;;EAtCA,EAAA;EAGA,EAAA;EACA,EAAA;EACA,GAAA;EACA,OAAA;EAGA,OAAA;EACA,IAAA;EACA,IAAA;EACA,SAAA,GAAY,KAAA,CAAM,YAAA;EAGlB,MAAA,GAAS,kBAAA;EACT,MAAA;EACA,IAAA,GAAO,WAAA;EAGP,WAAA,GAAc,cAAA;EAGd,QAAA,GAAW,YAAA;EACX,OAAA,GAAU,MAAA;EACV,IAAA;EAGA,aAAA;AAAA,IACE,UAAA;;;;KAKQ,cAAA;EACV,EAAA;EACA,EAAA;EACA,GAAA;EACA,OAAA;EACA,IAAA,EAAM,WAAA;EACN,OAAA;EACA,IAAA;EACA,IAAA;EACA,WAAA,EAAa,cAAA;EACb,QAAA,EAAU,YAAA;EACV,OAAA,EAAS,MAAA;EACT,IAAA;EACA,aAAA;EACA,MAAA,EAAQ,kBAAA;AAAA;;;;;;;KASE,YAAA;EAesB,qEAbhC,EAAA;EACA,OAAA,EAAS,WAAA;EACT,UAAA,EAAY,cAAA;EACZ,SAAA,EAAW,IAAA;EACX,MAAA,GAAS,UAAA;EACT,KAAA,GAAQ,SAAA;AAAA;AAUsE;;;AAAA,cAJnE,SAAA,SAAkB,KAAA;EAAA,SACb,IAAA,EAAM,aAAA;EAAA,SACN,aAAA,GAAgB,KAAA;cAEb,OAAA,UAAiB,IAAA,EAAM,aAAA,EAAe,aAAA,GAAgB,KAAA;AAAA"}

package/esm/mail/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../core/src/mail/types.ts"],"sourcesContent":["import type SMTPTransport from \"nodemailer/lib/smtp-transport\";\nimport type React from \"react\";\n\n/**\n * AWS SES mail configuration\n */\nexport type SESConfigurations = {\n  driver: \"ses\";\n  accessKeyId: string;\n  secretAccessKey: string;\n  region: string;\n  from?: MailAddress;\n};\n\n/**\n * Any mail configuration (SMTP or SES)\n */\nexport type MailConfigurations = SMTPConfigurations | SESConfigurations;\n\n/**\n * Mail mode determines how emails are handled\n */\nexport type MailMode = \"production\" | \"development\" | \"test\";\n\n/**\n * Mail priority levels\n */\nexport type MailPriority = \"high\" | \"normal\" | \"low\";\n\n/**\n * Email address with optional name\n */\nexport type MailAddress =\n  | string\n  | {\n      name: string;\n      address: string;\n    };\n\n/**\n * Mail attachment\n * Supports both buffer/string content and file paths\n */\nexport type MailAttachment = {\n  filename: string;\n  contentType?: string;\n  encoding?: \"base64\" | \"binary\" | \"hex\";\n  cid?: string; // Content-ID for inline attachments\n} & (\n  | {\n      content: Buffer | string;\n      path?: never;\n    }\n  | {\n      content?: never;\n      path: string; // File path - will be read automatically\n    }\n);\n\n/**\n * Mail configuration for SMTP transport\n *\n * ## Basic Configuration\n *\n * ```typescript\n * setMailConfigurations({\n *   host: \"smtp.gmail.com\",\n *   port: 587,\n *   secure: false,           // true for 465, false for other ports\n *   tls: true,               // Use STARTTLS\n *   username: \"user@gmail.com\",\n *   password: \"app-password\",\n *   from: { name: \"My App\", address: \"noreply@myapp.com\" },\n * });\n * ```\n *\n * ## Configuration Options\n *\n * | Option | Type | Default | Description |\n * |--------|------|---------|-------------|\n * | `host` | `string` | - | SMTP server hostname (e.g., \"smtp.gmail.com\") |\n * | `port` | `number` | 587 | SMTP port. Common: 25, 465 (SSL), 587 (TLS) |\n * | `secure` | `boolean` | false | Use SSL/TLS. Set `true` for port 465 |\n * | `tls` | `boolean` | true | Enable STARTTLS upgrade. For port 587 |\n * | `requireTLS` | `boolean` | - | Fail if STARTTLS upgrade fails |\n * | `username` | `string` | - | SMTP auth username (convenience alias) |\n * | `password` | `string` | - | SMTP auth password (convenience alias) |\n * | `auth` | `object` | - | Full auth object: `{ user, pass, type }` |\n * | `from` | `MailAddress` | - | Default sender for all emails |\n *\n * ## Provider Examples\n *\n * ### Gmail\n * ```typescript\n * { host: \"smtp.gmail.com\", port: 587, tls: true, username: \"...\", password: \"...\" }\n * ```\n *\n * ### SendGrid\n * ```typescript\n * { host: \"smtp.sendgrid.net\", port: 587, username: \"apikey\", password: \"SG.xxx\" }\n * ```\n *\n * ### AWS SES\n * ```typescript\n * { host: \"email-smtp.us-east-1.amazonaws.com\", port: 587, username: \"...\", password: \"...\" }\n * ```\n *\n * ### Mailgun\n * ```typescript\n * { host: \"smtp.mailgun.org\", port: 587, username: \"postmaster@...\", password: \"...\" }\n * ```\n *\n * ## Multi-tenant Usage\n *\n * For multi-tenant apps, pass config per-mail instead of globally:\n * ```typescript\n * await sendMail({\n *   config: tenant.mailSettings,  // Tenant-specific config\n *   to: \"user@example.com\",\n *   subject: \"Hello\",\n *   html: \"<p>World</p>\",\n * });\n * ```\n */\nexport type SMTPConfigurations = SMTPTransport.Options & {\n  /**\n   * Transport driver type\n   */\n  driver?: \"smtp\";\n  /**\n   * Enable STARTTLS upgrade (alias for requireTLS)\n   * Set to `true` for port 587\n   */\n  tls?: boolean;\n  /**\n   * SMTP authentication username\n   * Convenience alias - can also use `auth.user`\n   */\n  username?: string;\n  /**\n   * SMTP authentication password\n   * Convenience alias - can also use `auth.pass`\n   */\n  password?: string;\n  /**\n   * Default sender for all emails\n   * Can be string (\"noreply@app.com\") or object ({ name, address })\n   */\n  from?: MailAddress;\n};\n\n/**\n * Named mailers configuration\n */\nexport type MailersConfig = {\n  /**\n   * Default mailer configuration\n   */\n  default?: MailConfigurations;\n  /**\n   * Named mailer configurations\n   */\n  mailers?: Record<string, MailConfigurations>;\n};\n\n/**\n * Mail result after sending\n */\nexport type MailResult = {\n  success: boolean;\n  messageId?: string;\n  accepted: string[];\n  rejected: string[];\n  response?: string;\n  envelope?: {\n    from: string;\n    to: string[];\n  };\n};\n\n/**\n * Error codes for mail operations\n */\nexport type MailErrorCode =\n  | \"CONNECTION_ERROR\"\n  | \"AUTH_ERROR\"\n  | \"RATE_LIMIT\"\n  | \"INVALID_ADDRESS\"\n  | \"REJECTED\"\n  | \"TIMEOUT\"\n  | \"RENDER_ERROR\"\n  | \"CONFIG_ERROR\"\n  | \"UNKNOWN\";\n\n/**\n * Mail event callbacks (per-mail)\n * For global events, use mailEvents.on() from events.ts\n */\nexport type MailEvents = {\n  /**\n   * Called before sending the email\n   * Can be used to modify the mail or cancel sending\n   */\n  beforeSending?: (mail: MailOptions) => void | Promise<void> | false | Promise<false>;\n  /**\n   * Called after send attempt (success or failure)\n   */\n  onSent?: (\n    mail: MailOptions,\n    result: MailResult | null,\n    error: MailError | null,\n  ) => void | Promise<void>;\n  /**\n   * Called only on successful send\n   */\n  onSuccess?: (mail: MailOptions, result: MailResult) => void | Promise<void>;\n  /**\n   * Called only on error\n   */\n  onError?: (mail: MailOptions, error: MailError) => void | Promise<void>;\n};\n\n/**\n * Mail options for sending\n */\nexport type MailOptions = {\n  /**\n   * Unique mail ID for event namespacing\n   * If not provided, one will be auto-generated\n   *\n   * Use this to subscribe to events for a specific mail:\n   * ```typescript\n   * const mailId = generateMailId();\n   * mailEvents.onMailSuccess(mailId, (mail, result) => { ... });\n   * await sendMail({ id: mailId, to: \"...\", subject: \"...\", html: \"...\" });\n   * ```\n   */\n  id?: string;\n\n  // Recipients\n  to: string | string[];\n  cc?: string | string[];\n  bcc?: string | string[];\n  replyTo?: string;\n\n  // Content\n  subject: string;\n  html?: string;\n  text?: string;\n  component?: React.ReactElement;\n\n  // Configuration\n  config?: MailConfigurations;\n  mailer?: string;\n  from?: MailAddress;\n\n  // Attachments\n  attachments?: MailAttachment[];\n\n  // Options\n  priority?: MailPriority;\n  headers?: Record<string, string>;\n  tags?: string[];\n\n  // Meta\n  correlationId?: string;\n} & MailEvents;\n\n/**\n * Internal normalized mail data\n */\nexport type NormalizedMail = {\n  to: string[];\n  cc: string[];\n  bcc: string[];\n  replyTo?: string;\n  from: MailAddress;\n  subject: string;\n  html?: string;\n  text?: string;\n  attachments: MailAttachment[];\n  priority: MailPriority;\n  headers: Record<string, string>;\n  tags: string[];\n  correlationId?: string;\n  config: MailConfigurations;\n};\n\n/**\n * Captured mail for test mode\n */\nexport type CapturedMail = {\n  options: MailOptions;\n  normalized: NormalizedMail;\n  timestamp: Date;\n  result?: MailResult;\n  error?: MailError;\n};\n\n/**\n * Mail error class\n */\nexport class MailError extends Error {\n  public readonly code: MailErrorCode;\n  public readonly originalError?: Error;\n\n  public constructor(message: string, code: MailErrorCode, originalError?: Error) {\n    super(message);\n    this.name = \"MailError\";\n    this.code = code;\n    this.originalError = originalError;\n  }\n}\n"],"mappings":";;;;AA8SA,IAAa,YAAb,cAA+B,MAAM;CAInC,AAAO,YAAY,SAAiB,MAAqB,eAAuB;EAC9E,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,gBAAgB;CACvB;AACF"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../core/src/mail/types.ts"],"sourcesContent":["import type SMTPTransport from \"nodemailer/lib/smtp-transport\";\nimport type React from \"react\";\n\n/**\n * AWS SES mail configuration\n */\nexport type SESConfigurations = {\n  driver: \"ses\";\n  accessKeyId: string;\n  secretAccessKey: string;\n  region: string;\n  from?: MailAddress;\n};\n\n/**\n * Any mail configuration (SMTP or SES)\n */\nexport type MailConfigurations = SMTPConfigurations | SESConfigurations;\n\n/**\n * Mail mode determines how emails are handled\n */\nexport type MailMode = \"production\" | \"development\" | \"test\";\n\n/**\n * Mail priority levels\n */\nexport type MailPriority = \"high\" | \"normal\" | \"low\";\n\n/**\n * Email address with optional name\n */\nexport type MailAddress =\n  | string\n  | {\n      name: string;\n      address: string;\n    };\n\n/**\n * Mail attachment\n * Supports both buffer/string content and file paths\n */\nexport type MailAttachment = {\n  filename: string;\n  contentType?: string;\n  encoding?: \"base64\" | \"binary\" | \"hex\";\n  cid?: string; // Content-ID for inline attachments\n} & (\n  | {\n      content: Buffer | string;\n      path?: never;\n    }\n  | {\n      content?: never;\n      path: string; // File path - will be read automatically\n    }\n);\n\n/**\n * Mail configuration for SMTP transport\n *\n * ## Basic Configuration\n *\n * ```typescript\n * setMailConfigurations({\n *   host: \"smtp.gmail.com\",\n *   port: 587,\n *   secure: false,           // true for 465, false for other ports\n *   tls: true,               // Use STARTTLS\n *   username: \"user@gmail.com\",\n *   password: \"app-password\",\n *   from: { name: \"My App\", address: \"noreply@myapp.com\" },\n * });\n * ```\n *\n * ## Configuration Options\n *\n * | Option | Type | Default | Description |\n * |--------|------|---------|-------------|\n * | `host` | `string` | - | SMTP server hostname (e.g., \"smtp.gmail.com\") |\n * | `port` | `number` | 587 | SMTP port. Common: 25, 465 (SSL), 587 (TLS) |\n * | `secure` | `boolean` | false | Use SSL/TLS. Set `true` for port 465 |\n * | `tls` | `boolean` | true | Enable STARTTLS upgrade. For port 587 |\n * | `requireTLS` | `boolean` | - | Fail if STARTTLS upgrade fails |\n * | `username` | `string` | - | SMTP auth username (convenience alias) |\n * | `password` | `string` | - | SMTP auth password (convenience alias) |\n * | `auth` | `object` | - | Full auth object: `{ user, pass, type }` |\n * | `from` | `MailAddress` | - | Default sender for all emails |\n *\n * ## Provider Examples\n *\n * ### Gmail\n * ```typescript\n * { host: \"smtp.gmail.com\", port: 587, tls: true, username: \"...\", password: \"...\" }\n * ```\n *\n * ### SendGrid\n * ```typescript\n * { host: \"smtp.sendgrid.net\", port: 587, username: \"apikey\", password: \"SG.xxx\" }\n * ```\n *\n * ### AWS SES\n * ```typescript\n * { host: \"email-smtp.us-east-1.amazonaws.com\", port: 587, username: \"...\", password: \"...\" }\n * ```\n *\n * ### Mailgun\n * ```typescript\n * { host: \"smtp.mailgun.org\", port: 587, username: \"postmaster@...\", password: \"...\" }\n * ```\n *\n * ## Multi-tenant Usage\n *\n * For multi-tenant apps, pass config per-mail instead of globally:\n * ```typescript\n * await sendMail({\n *   config: tenant.mailSettings,  // Tenant-specific config\n *   to: \"user@example.com\",\n *   subject: \"Hello\",\n *   html: \"<p>World</p>\",\n * });\n * ```\n */\nexport type SMTPConfigurations = SMTPTransport.Options & {\n  /**\n   * Transport driver type\n   */\n  driver?: \"smtp\";\n  /**\n   * Enable STARTTLS upgrade (alias for requireTLS)\n   * Set to `true` for port 587\n   */\n  tls?: boolean;\n  /**\n   * SMTP authentication username\n   * Convenience alias - can also use `auth.user`\n   */\n  username?: string;\n  /**\n   * SMTP authentication password\n   * Convenience alias - can also use `auth.pass`\n   */\n  password?: string;\n  /**\n   * Default sender for all emails\n   * Can be string (\"noreply@app.com\") or object ({ name, address })\n   */\n  from?: MailAddress;\n};\n\n/**\n * Named mailers configuration\n */\nexport type MailersConfig = {\n  /**\n   * Default mailer configuration\n   */\n  default?: MailConfigurations;\n  /**\n   * Named mailer configurations\n   */\n  mailers?: Record<string, MailConfigurations>;\n};\n\n/**\n * Mail result after sending\n */\nexport type MailResult = {\n  success: boolean;\n  messageId?: string;\n  accepted: string[];\n  rejected: string[];\n  response?: string;\n  envelope?: {\n    from: string;\n    to: string[];\n  };\n};\n\n/**\n * Error codes for mail operations\n */\nexport type MailErrorCode =\n  | \"CONNECTION_ERROR\"\n  | \"AUTH_ERROR\"\n  | \"RATE_LIMIT\"\n  | \"INVALID_ADDRESS\"\n  | \"REJECTED\"\n  | \"TIMEOUT\"\n  | \"RENDER_ERROR\"\n  | \"CONFIG_ERROR\"\n  | \"UNKNOWN\";\n\n/**\n * Mail event callbacks (per-mail)\n * For global events, use mailEvents.on() from events.ts\n */\nexport type MailEvents = {\n  /**\n   * Called before sending the email\n   * Can be used to modify the mail or cancel sending\n   */\n  beforeSending?: (mail: MailOptions) => void | Promise<void> | false | Promise<false>;\n  /**\n   * Called after send attempt (success or failure)\n   */\n  onSent?: (\n    mail: MailOptions,\n    result: MailResult | null,\n    error: MailError | null,\n  ) => void | Promise<void>;\n  /**\n   * Called only on successful send\n   */\n  onSuccess?: (mail: MailOptions, result: MailResult) => void | Promise<void>;\n  /**\n   * Called only on error\n   */\n  onError?: (mail: MailOptions, error: MailError) => void | Promise<void>;\n};\n\n/**\n * Mail options for sending\n */\nexport type MailOptions = {\n  /**\n   * Unique mail ID for event namespacing\n   * If not provided, one will be auto-generated\n   *\n   * Use this to subscribe to events for a specific mail:\n   * ```typescript\n   * const mailId = generateMailId();\n   * mailEvents.onMailSuccess(mailId, (mail, result) => { ... });\n   * await sendMail({ id: mailId, to: \"...\", subject: \"...\", html: \"...\" });\n   * ```\n   */\n  id?: string;\n\n  // Recipients\n  to: string | string[];\n  cc?: string | string[];\n  bcc?: string | string[];\n  replyTo?: string;\n\n  // Content\n  subject: string;\n  html?: string;\n  text?: string;\n  component?: React.ReactElement;\n\n  // Configuration\n  config?: MailConfigurations;\n  mailer?: string;\n  from?: MailAddress;\n\n  // Attachments\n  attachments?: MailAttachment[];\n\n  // Options\n  priority?: MailPriority;\n  headers?: Record<string, string>;\n  tags?: string[];\n\n  // Meta\n  correlationId?: string;\n} & MailEvents;\n\n/**\n * Internal normalized mail data\n */\nexport type NormalizedMail = {\n  to: string[];\n  cc: string[];\n  bcc: string[];\n  replyTo?: string;\n  from: MailAddress;\n  subject: string;\n  html?: string;\n  text?: string;\n  attachments: MailAttachment[];\n  priority: MailPriority;\n  headers: Record<string, string>;\n  tags: string[];\n  correlationId?: string;\n  config: MailConfigurations;\n};\n\n/**\n * Captured mail for development and test modes.\n *\n * Attachments retain their normalized contents so test assertions can inspect\n * the exact mail that would be sent.\n */\nexport type CapturedMail = {\n  /** The mail ID used for event namespacing and result correlation. */\n  id: string;\n  options: MailOptions;\n  normalized: NormalizedMail;\n  timestamp: Date;\n  result?: MailResult;\n  error?: MailError;\n};\n\n/**\n * Mail error class\n */\nexport class MailError extends Error {\n  public readonly code: MailErrorCode;\n  public readonly originalError?: Error;\n\n  public constructor(message: string, code: MailErrorCode, originalError?: Error) {\n    super(message);\n    this.name = \"MailError\";\n    this.code = code;\n    this.originalError = originalError;\n  }\n}\n"],"mappings":";;;;AAmTA,IAAa,YAAb,cAA+B,MAAM;CAInC,AAAO,YAAY,SAAiB,MAAqB,eAAuB;EAC9E,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,gBAAgB;CACvB;AACF"}

package/esm/manifest/manifest-manager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-manager.mjs","names":[],"sources":["../../../../../../../core/src/manifest/manifest-manager.ts"],"sourcesContent":["import { getJsonFileAsync, putJsonFileAsync, unlinkAsync } from \"@warlock.js/fs\";\r\nimport { warlockPath } from \"../utils\";\r\n\r\n/**\r\n * Stored option metadata in manifest\r\n */\r\nexport type ManifestCommandOption = {\r\n  name: string;\r\n  text: string;\r\n  alias?: string;\r\n  description?: string;\r\n  type?: \"string\" | \"boolean\" | \"number\";\r\n  required?: boolean;\r\n  defaultValue?: string | boolean | number;\r\n};\r\n\r\n/**\r\n * Command metadata stored in commands.json\r\n */\r\nexport type ManifestCommandData = {\r\n  relativePath?: string;\r\n  source: \"framework\" | \"plugin\" | \"project\";\r\n  description?: string;\r\n  alias?: string;\r\n  options?: ManifestCommandOption[];\r\n};\r\n\r\ntype ManifestCommandsJson = {\r\n  commands: Record<string, ManifestCommandData>;\r\n};\r\n\r\nexport class ManifestManager {\r\n  /**\r\n   * commands json\r\n   */\r\n  protected _commandsJson?: ManifestCommandsJson;\r\n\r\n  /**\r\n   * Check if commands json is changed\r\n   */\r\n  protected _hasChanges = false;\r\n\r\n  /**\r\n   * Whether commands json is loaded\r\n   */\r\n  protected _isLoaded = false;\r\n\r\n  /**\r\n   * Get if commands json has changes\r\n   */\r\n  public get hasChanges() {\r\n    return this._hasChanges;\r\n  }\r\n\r\n  /**\r\n   * Check if commands json is loaded\r\n   */\r\n  public get isCommandLoaded() {\r\n    return this._isLoaded;\r\n  }\r\n\r\n  /**\r\n   * Load commands.json file\r\n   */\r\n  public async loadCommands(): Promise<ManifestCommandsJson | undefined> {\r\n    // now try to locate it in .warlock folder\r\n    if (this._isLoaded) return this._commandsJson;\r\n\r\n    try {\r\n      this._commandsJson = await getJsonFileAsync(warlockPath(\"commands.json\"));\r\n\r\n      this._isLoaded = true;\r\n\r\n      return this._commandsJson;\r\n    } catch {\r\n      return;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get commands json content\r\n   */\r\n  public get commandsJson() {\r\n    return this._commandsJson;\r\n  }\r\n\r\n  /**\r\n   * Save commands in commands.json file\r\n   */\r\n  public async saveCommands() {\r\n    await putJsonFileAsync(warlockPath(\"commands.json\"), this._commandsJson);\r\n\r\n    this._isLoaded = true;\r\n    this._hasChanges = false;\r\n  }\r\n\r\n  /**\r\n   * Add command info to commands list (But do not save commands)\r\n   */\r\n  public addCommandToList(name: string, command: ManifestCommandsJson[\"commands\"][string]) {\r\n    if (!this._commandsJson) {\r\n      this._commandsJson = {\r\n        commands: {},\r\n      };\r\n    }\r\n\r\n    this._commandsJson.commands[name] = command;\r\n\r\n    this._hasChanges = true;\r\n  }\r\n\r\n  /**\r\n   * Clear commands cache\r\n   */\r\n  public clearCommandsCache() {\r\n    this._commandsJson = undefined;\r\n    this._hasChanges = false;\r\n    this._isLoaded = false;\r\n  }\r\n\r\n  /**\r\n   * Remove commands.json file\r\n   */\r\n  public async removeCommandsFile() {\r\n    try {\r\n      await unlinkAsync(warlockPath(\"commands.json\"));\r\n    } catch {\r\n      // do nothing\r\n    }\r\n  }\r\n}\r\n\r\nexport const manifestManager = new ManifestManager();\r\n"],"mappings":";;;;;AA+BA,IAAa,kBAAb,MAA6B;;qBASH;mBAKF;;;;;CAKtB,IAAW,aAAa;EACtB,OAAO,KAAK;CACd;;;;CAKA,IAAW,kBAAkB;EAC3B,OAAO,KAAK;CACd;;;;CAKA,MAAa,eAA0D;EAErE,IAAI,KAAK,WAAW,OAAO,KAAK;EAEhC,IAAI;GACF,KAAK,gBAAgB,MAAM,iBAAiB,YAAY,eAAe,CAAC;GAExE,KAAK,YAAY;GAEjB,OAAO,KAAK;EACd,QAAQ;GACN;EACF;CACF;;;;CAKA,IAAW,eAAe;EACxB,OAAO,KAAK;CACd;;;;CAKA,MAAa,eAAe;EAC1B,MAAM,iBAAiB,YAAY,eAAe,GAAG,KAAK,aAAa;EAEvE,KAAK,YAAY;EACjB,KAAK,cAAc;CACrB;;;;CAKA,AAAO,iBAAiB,MAAc,SAAmD;EACvF,IAAI,CAAC,KAAK,eACR,KAAK,gBAAgB,EACnB,UAAU,CAAC,EACb;EAGF,KAAK,cAAc,SAAS,QAAQ;EAEpC,KAAK,cAAc;CACrB;;;;CAKA,AAAO,qBAAqB;EAC1B,KAAK,gBAAgB;EACrB,KAAK,cAAc;EACnB,KAAK,YAAY;CACnB;;;;CAKA,MAAa,qBAAqB;EAChC,IAAI;GACF,MAAM,YAAY,YAAY,eAAe,CAAC;EAChD,QAAQ,CAER;CACF;AACF;AAEA,MAAa,kBAAkB,IAAI,gBAAgB"}
+{"version":3,"file":"manifest-manager.mjs","names":[],"sources":["../../../../../../../core/src/manifest/manifest-manager.ts"],"sourcesContent":["import { getJsonFileAsync, putJsonFileAsync, unlinkAsync } from \"@warlock.js/fs\";\nimport { warlockPath } from \"../utils\";\n\n/**\n * Stored option metadata in manifest\n */\nexport type ManifestCommandOption = {\n  name: string;\n  text: string;\n  alias?: string;\n  description?: string;\n  type?: \"string\" | \"boolean\" | \"number\";\n  required?: boolean;\n  defaultValue?: string | boolean | number;\n};\n\n/**\n * Command metadata stored in commands.json\n */\nexport type ManifestCommandData = {\n  relativePath?: string;\n  source: \"framework\" | \"plugin\" | \"project\";\n  description?: string;\n  alias?: string;\n  options?: ManifestCommandOption[];\n};\n\ntype ManifestCommandsJson = {\n  commands: Record<string, ManifestCommandData>;\n};\n\nexport class ManifestManager {\n  /**\n   * commands json\n   */\n  protected _commandsJson?: ManifestCommandsJson;\n\n  /**\n   * Check if commands json is changed\n   */\n  protected _hasChanges = false;\n\n  /**\n   * Whether commands json is loaded\n   */\n  protected _isLoaded = false;\n\n  /**\n   * Get if commands json has changes\n   */\n  public get hasChanges() {\n    return this._hasChanges;\n  }\n\n  /**\n   * Check if commands json is loaded\n   */\n  public get isCommandLoaded() {\n    return this._isLoaded;\n  }\n\n  /**\n   * Load commands.json file\n   */\n  public async loadCommands(): Promise<ManifestCommandsJson | undefined> {\n    // now try to locate it in .warlock folder\n    if (this._isLoaded) return this._commandsJson;\n\n    try {\n      this._commandsJson = await getJsonFileAsync(warlockPath(\"commands.json\"));\n\n      this._isLoaded = true;\n\n      return this._commandsJson;\n    } catch {\n      return;\n    }\n  }\n\n  /**\n   * Get commands json content\n   */\n  public get commandsJson() {\n    return this._commandsJson;\n  }\n\n  /**\n   * Save commands in commands.json file\n   */\n  public async saveCommands() {\n    await putJsonFileAsync(warlockPath(\"commands.json\"), this._commandsJson);\n\n    this._isLoaded = true;\n    this._hasChanges = false;\n  }\n\n  /**\n   * Add command info to commands list (But do not save commands)\n   */\n  public addCommandToList(name: string, command: ManifestCommandsJson[\"commands\"][string]) {\n    if (!this._commandsJson) {\n      this._commandsJson = {\n        commands: {},\n      };\n    }\n\n    this._commandsJson.commands[name] = command;\n\n    this._hasChanges = true;\n  }\n\n  /**\n   * Clear commands cache\n   */\n  public clearCommandsCache() {\n    this._commandsJson = undefined;\n    this._hasChanges = false;\n    this._isLoaded = false;\n  }\n\n  /**\n   * Remove commands.json file\n   */\n  public async removeCommandsFile() {\n    try {\n      await unlinkAsync(warlockPath(\"commands.json\"));\n    } catch {\n      // do nothing\n    }\n  }\n}\n\nexport const manifestManager = new ManifestManager();\n"],"mappings":";;;;;AA+BA,IAAa,kBAAb,MAA6B;;qBASH;mBAKF;;;;;CAKtB,IAAW,aAAa;EACtB,OAAO,KAAK;CACd;;;;CAKA,IAAW,kBAAkB;EAC3B,OAAO,KAAK;CACd;;;;CAKA,MAAa,eAA0D;EAErE,IAAI,KAAK,WAAW,OAAO,KAAK;EAEhC,IAAI;GACF,KAAK,gBAAgB,MAAM,iBAAiB,YAAY,eAAe,CAAC;GAExE,KAAK,YAAY;GAEjB,OAAO,KAAK;EACd,QAAQ;GACN;EACF;CACF;;;;CAKA,IAAW,eAAe;EACxB,OAAO,KAAK;CACd;;;;CAKA,MAAa,eAAe;EAC1B,MAAM,iBAAiB,YAAY,eAAe,GAAG,KAAK,aAAa;EAEvE,KAAK,YAAY;EACjB,KAAK,cAAc;CACrB;;;;CAKA,AAAO,iBAAiB,MAAc,SAAmD;EACvF,IAAI,CAAC,KAAK,eACR,KAAK,gBAAgB,EACnB,UAAU,CAAC,EACb;EAGF,KAAK,cAAc,SAAS,QAAQ;EAEpC,KAAK,cAAc;CACrB;;;;CAKA,AAAO,qBAAqB;EAC1B,KAAK,gBAAgB;EACrB,KAAK,cAAc;EACnB,KAAK,YAAY;CACnB;;;;CAKA,MAAa,qBAAqB;EAChC,IAAI;GACF,MAAM,YAAY,YAAY,eAAe,CAAC;EAChD,QAAQ,CAER;CACF;AACF;AAEA,MAAa,kBAAkB,IAAI,gBAAgB"}

package/esm/production/build-contributions.mjs

@@ -10,7 +10,11 @@ const ErrorWithCause = Error;
 * posture as the `tsconfig` guard in `resolve-build-config`: dropping the key
 * quietly would leave the author believing their plugin ran.
 */
-const ALLOWED_CONTRIBUTION_KEYS = ["generate", "emit"];
+const ALLOWED_CONTRIBUTION_KEYS = [
+	"generate",
+	"emit",
+	"typings"
+];
 /**
 * Reject a contribution object carrying anything but the two hooks.
 *
@@ -21,7 +25,7 @@ function assertClosedContribution(connector) {
 	if (!contribution) return;
 	for (const key of Object.keys(contribution)) {
 		if (ALLOWED_CONTRIBUTION_KEYS.includes(key)) continue;
-		throw new Error(`Connector "${connector.name}" declares an unsupported build contribution key "${key}". A build contribution carries exactly two optional hooks — ${ALLOWED_CONTRIBUTION_KEYS.join(" and ")} — and no data. Anything a hook needs (plugins, pipelines, aliases) must be constructed inside that hook, so it never lands in the connector's static import graph.`);
+		throw new Error(`Connector "${connector.name}" declares an unsupported build contribution key "${key}". A build contribution carries exactly these optional hooks — ${ALLOWED_CONTRIBUTION_KEYS.join(", ")} — and no data. Anything a hook needs (plugins, pipelines, aliases) must be constructed inside that hook, so it never lands in the connector's static import graph.`);
 	}
 }
 /**
@@ -66,6 +70,18 @@ async function runEmitContributions(connectors, context) {
 	}
 }
 /**
+* Drain every connector's `typings` hook, in array order, sequentially.
+* Connectors without one — every API-only app — are skipped without error.
+*/
+async function runTypingsContributions(connectors, context) {
+	for (const connector of connectors) {
+		assertClosedContribution(connector);
+		const typings = connector.build?.typings;
+		if (!typings) continue;
+		await runHook(connector, "typings", () => typings(context));
+	}
+}
+/**
 * Merge two contributor patches. Later wins, except:
 *
 * - `define` merges per key — two contributors defining different
@@ -114,5 +130,5 @@ async function runHook(connector, hook, run) {
 }
 
 //#endregion
-export { dedupe, runEmitContributions, runGenerateContributions };
+export { dedupe, runEmitContributions, runGenerateContributions, runTypingsContributions };
 //# sourceMappingURL=build-contributions.mjs.map

package/esm/production/build-contributions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"build-contributions.mjs","names":[],"sources":["../../../../../../../core/src/production/build-contributions.ts"],"sourcesContent":["import type { Connector, ConnectorBuildContext, ConnectorEsbuildPatch } from \"../connectors/types\";\n\n/**\n * `Error` with the `cause` option typed. Same shim as\n * `application.ts` — lib.es2022 declares `cause` on `ErrorOptions`, but the\n * package still compiles against an older lib in some consumers.\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * The only keys a `build` contribution may carry.\n *\n * The runtime half of the closed-contribution constraint: the\n * type already makes `build: { plugins: [...] }` unrepresentable, but a\n * plain `warlock.config.js`, an `as any`, or a connector compiled against an\n * older core all slip past the type. Rejected rather than ignored — the same\n * posture as the `tsconfig` guard in `resolve-build-config`: dropping the key\n * quietly would leave the author believing their plugin ran.\n */\nconst ALLOWED_CONTRIBUTION_KEYS = [\"generate\", \"emit\"] as const;\n\n/**\n * What the generate pass produced, merged across every contributor.\n */\nexport type GenerateContributionsResult = {\n  /** Entry lines in contributor order, appended after `./routes` */\n  entryImports: string[];\n  /** The contributors' esbuild patches, merged into one */\n  esbuild: ConnectorEsbuildPatch;\n};\n\n/**\n * Reject a contribution object carrying anything but the two hooks.\n *\n * @throws Error naming the connector and the offending key\n */\nexport function assertClosedContribution(connector: Connector): void {\n  const contribution = connector.build;\n\n  if (!contribution) return;\n\n  for (const key of Object.keys(contribution)) {\n    if ((ALLOWED_CONTRIBUTION_KEYS as readonly string[]).includes(key)) continue;\n\n    throw new Error(\n      `Connector \"${connector.name}\" declares an unsupported build contribution key \"${key}\". ` +\n        `A build contribution carries exactly two optional hooks — ` +\n        `${ALLOWED_CONTRIBUTION_KEYS.join(\" and \")} — and no data. ` +\n        `Anything a hook needs (plugins, pipelines, aliases) must be constructed inside ` +\n        `that hook, so it never lands in the connector's static import graph.`,\n    );\n  }\n}\n\n/**\n * Drain every connector's `generate` hook, in array order, sequentially.\n *\n * Semantics are copied from `Application.runStartupValidators`\n * (`application.ts:304-329`) on purpose: ordered, awaited one at a time, and\n * a throw is rethrown wrapped in an error NAMING the contributor. A\n * contributor failure IS the build failing — that is what makes\n * \"green build, no client bundle\" unrepresentable rather than merely\n * unlikely.\n */\nexport async function runGenerateContributions(\n  connectors: readonly Connector[],\n  context: ConnectorBuildContext,\n): Promise<GenerateContributionsResult> {\n  const entryImports: string[] = [];\n  let esbuild: ConnectorEsbuildPatch = {};\n\n  for (const connector of connectors) {\n    assertClosedContribution(connector);\n\n    const generate = connector.build?.generate;\n\n    if (!generate) continue;\n\n    const result = await runHook(connector, \"generate\", () => generate(context));\n\n    if (!result) continue;\n\n    if (result.entryImports) {\n      entryImports.push(...result.entryImports);\n    }\n\n    if (result.esbuild) {\n      esbuild = mergeEsbuildPatches(esbuild, result.esbuild);\n    }\n  }\n\n  return { entryImports, esbuild };\n}\n\n/**\n * Drain every connector's `emit` hook, in array order, sequentially.\n *\n * Runs after esbuild and before `.warlock/production` is removed, so a hook\n * may still read what `generate` wrote there.\n */\nexport async function runEmitContributions(\n  connectors: readonly Connector[],\n  context: ConnectorBuildContext,\n): Promise<void> {\n  for (const connector of connectors) {\n    assertClosedContribution(connector);\n\n    const emit = connector.build?.emit;\n\n    if (!emit) continue;\n\n    await runHook(connector, \"emit\", () => emit(context));\n  }\n}\n\n/**\n * Merge two contributor patches. Later wins, except:\n *\n * - `define` merges per key — two contributors defining different\n *   `import.meta.env.*` entries must both survive; a wholesale replace would\n *   drop one silently.\n * - `external` concatenates and dedupes — it is a set of package names, and\n *   under `singleBundle` each contributor adds its own optional peers.\n * - `loader` merges per extension, for the same reason as `define`.\n * - `plugins` concatenate in contribution order. They are constructed inside\n *   a hook, so this does not reopen the closed-contribution constraint.\n */\nexport function mergeEsbuildPatches(\n  base: ConnectorEsbuildPatch,\n  patch: ConnectorEsbuildPatch,\n): ConnectorEsbuildPatch {\n  const merged: ConnectorEsbuildPatch = { ...base, ...patch };\n\n  if (base.define || patch.define) {\n    merged.define = { ...base.define, ...patch.define };\n  }\n\n  if (base.external || patch.external) {\n    merged.external = dedupe([...(base.external ?? []), ...(patch.external ?? [])]);\n  }\n\n  if (base.loader || patch.loader) {\n    merged.loader = { ...base.loader, ...patch.loader };\n  }\n\n  if (base.plugins || patch.plugins) {\n    merged.plugins = [...(base.plugins ?? []), ...(patch.plugins ?? [])];\n  }\n\n  return merged;\n}\n\n/**\n * Concatenation order preserved — esbuild does not care, but a stable order\n * keeps build output diffable.\n */\nexport function dedupe(values: string[]): string[] {\n  return [...new Set(values)];\n}\n\n/**\n * Run one hook and rename its failure after the connector that owns it.\n */\nasync function runHook<Result>(\n  connector: Connector,\n  hook: \"generate\" | \"emit\",\n  run: () => Result | Promise<Result>,\n): Promise<Result> {\n  try {\n    return await run();\n  } catch (error) {\n    const cause = error instanceof Error ? error.message : String(error);\n\n    throw new ErrorWithCause(\n      `Build contribution \"${connector.name}\" failed during ${hook}: ${cause}. ` +\n        `The build cannot continue — an artifact this connector was responsible for ` +\n        `is missing, and shipping the bundle without it would fail at runtime instead.`,\n      { cause: error },\n    );\n  }\n}\n"],"mappings":";AASA,MAAM,iBAAiB;;;;;;;;;;;AAYvB,MAAM,4BAA4B,CAAC,YAAY,MAAM;;;;;;AAiBrD,SAAgB,yBAAyB,WAA4B;CACnE,MAAM,eAAe,UAAU;CAE/B,IAAI,CAAC,cAAc;CAEnB,KAAK,MAAM,OAAO,OAAO,KAAK,YAAY,GAAG;EAC3C,IAAK,0BAAgD,SAAS,GAAG,GAAG;EAEpE,MAAM,IAAI,MACR,cAAc,UAAU,KAAK,oDAAoD,IAAI,+DAEhF,0BAA0B,KAAK,OAAO,EAAE,oKAG/C;CACF;AACF;;;;;;;;;;;AAYA,eAAsB,yBACpB,YACA,SACsC;CACtC,MAAM,eAAyB,CAAC;CAChC,IAAI,UAAiC,CAAC;CAEtC,KAAK,MAAM,aAAa,YAAY;EAClC,yBAAyB,SAAS;EAElC,MAAM,WAAW,UAAU,OAAO;EAElC,IAAI,CAAC,UAAU;EAEf,MAAM,SAAS,MAAM,QAAQ,WAAW,kBAAkB,SAAS,OAAO,CAAC;EAE3E,IAAI,CAAC,QAAQ;EAEb,IAAI,OAAO,cACT,aAAa,KAAK,GAAG,OAAO,YAAY;EAG1C,IAAI,OAAO,SACT,UAAU,oBAAoB,SAAS,OAAO,OAAO;CAEzD;CAEA,OAAO;EAAE;EAAc;CAAQ;AACjC;;;;;;;AAQA,eAAsB,qBACpB,YACA,SACe;CACf,KAAK,MAAM,aAAa,YAAY;EAClC,yBAAyB,SAAS;EAElC,MAAM,OAAO,UAAU,OAAO;EAE9B,IAAI,CAAC,MAAM;EAEX,MAAM,QAAQ,WAAW,cAAc,KAAK,OAAO,CAAC;CACtD;AACF;;;;;;;;;;;;;AAcA,SAAgB,oBACd,MACA,OACuB;CACvB,MAAM,SAAgC;EAAE,GAAG;EAAM,GAAG;CAAM;CAE1D,IAAI,KAAK,UAAU,MAAM,QACvB,OAAO,SAAS;EAAE,GAAG,KAAK;EAAQ,GAAG,MAAM;CAAO;CAGpD,IAAI,KAAK,YAAY,MAAM,UACzB,OAAO,WAAW,OAAO,CAAC,GAAI,KAAK,YAAY,CAAC,GAAI,GAAI,MAAM,YAAY,CAAC,CAAE,CAAC;CAGhF,IAAI,KAAK,UAAU,MAAM,QACvB,OAAO,SAAS;EAAE,GAAG,KAAK;EAAQ,GAAG,MAAM;CAAO;CAGpD,IAAI,KAAK,WAAW,MAAM,SACxB,OAAO,UAAU,CAAC,GAAI,KAAK,WAAW,CAAC,GAAI,GAAI,MAAM,WAAW,CAAC,CAAE;CAGrE,OAAO;AACT;;;;;AAMA,SAAgB,OAAO,QAA4B;CACjD,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC5B;;;;AAKA,eAAe,QACb,WACA,MACA,KACiB;CACjB,IAAI;EACF,OAAO,MAAM,IAAI;CACnB,SAAS,OAAO;EACd,MAAM,QAAQ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EAEnE,MAAM,IAAI,eACR,uBAAuB,UAAU,KAAK,kBAAkB,KAAK,IAAI,MAAM,6JAGvE,EAAE,OAAO,MAAM,CACjB;CACF;AACF"}
+{"version":3,"file":"build-contributions.mjs","names":[],"sources":["../../../../../../../core/src/production/build-contributions.ts"],"sourcesContent":["import type { Connector, ConnectorBuildContext, ConnectorEsbuildPatch } from \"../connectors/types\";\n\n/**\n * `Error` with the `cause` option typed. Same shim as\n * `application.ts` — lib.es2022 declares `cause` on `ErrorOptions`, but the\n * package still compiles against an older lib in some consumers.\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * The only keys a `build` contribution may carry.\n *\n * The runtime half of the closed-contribution constraint: the\n * type already makes `build: { plugins: [...] }` unrepresentable, but a\n * plain `warlock.config.js`, an `as any`, or a connector compiled against an\n * older core all slip past the type. Rejected rather than ignored — the same\n * posture as the `tsconfig` guard in `resolve-build-config`: dropping the key\n * quietly would leave the author believing their plugin ran.\n */\nconst ALLOWED_CONTRIBUTION_KEYS = [\"generate\", \"emit\", \"typings\"] as const;\n\n/**\n * What the generate pass produced, merged across every contributor.\n */\nexport type GenerateContributionsResult = {\n  /** Entry lines in contributor order, appended after `./routes` */\n  entryImports: string[];\n  /** The contributors' esbuild patches, merged into one */\n  esbuild: ConnectorEsbuildPatch;\n};\n\n/**\n * Reject a contribution object carrying anything but the two hooks.\n *\n * @throws Error naming the connector and the offending key\n */\nexport function assertClosedContribution(connector: Connector): void {\n  const contribution = connector.build;\n\n  if (!contribution) return;\n\n  for (const key of Object.keys(contribution)) {\n    if ((ALLOWED_CONTRIBUTION_KEYS as readonly string[]).includes(key)) continue;\n\n    throw new Error(\n      `Connector \"${connector.name}\" declares an unsupported build contribution key \"${key}\". ` +\n        `A build contribution carries exactly these optional hooks — ` +\n        `${ALLOWED_CONTRIBUTION_KEYS.join(\", \")} — and no data. ` +\n        `Anything a hook needs (plugins, pipelines, aliases) must be constructed inside ` +\n        `that hook, so it never lands in the connector's static import graph.`,\n    );\n  }\n}\n\n/**\n * Drain every connector's `generate` hook, in array order, sequentially.\n *\n * Semantics are copied from `Application.runStartupValidators`\n * (`application.ts:304-329`) on purpose: ordered, awaited one at a time, and\n * a throw is rethrown wrapped in an error NAMING the contributor. A\n * contributor failure IS the build failing — that is what makes\n * \"green build, no client bundle\" unrepresentable rather than merely\n * unlikely.\n */\nexport async function runGenerateContributions(\n  connectors: readonly Connector[],\n  context: ConnectorBuildContext,\n): Promise<GenerateContributionsResult> {\n  const entryImports: string[] = [];\n  let esbuild: ConnectorEsbuildPatch = {};\n\n  for (const connector of connectors) {\n    assertClosedContribution(connector);\n\n    const generate = connector.build?.generate;\n\n    if (!generate) continue;\n\n    const result = await runHook(connector, \"generate\", () => generate(context));\n\n    if (!result) continue;\n\n    if (result.entryImports) {\n      entryImports.push(...result.entryImports);\n    }\n\n    if (result.esbuild) {\n      esbuild = mergeEsbuildPatches(esbuild, result.esbuild);\n    }\n  }\n\n  return { entryImports, esbuild };\n}\n\n/**\n * Drain every connector's `emit` hook, in array order, sequentially.\n *\n * Runs after esbuild and before `.warlock/production` is removed, so a hook\n * may still read what `generate` wrote there.\n */\nexport async function runEmitContributions(\n  connectors: readonly Connector[],\n  context: ConnectorBuildContext,\n): Promise<void> {\n  for (const connector of connectors) {\n    assertClosedContribution(connector);\n\n    const emit = connector.build?.emit;\n\n    if (!emit) continue;\n\n    await runHook(connector, \"emit\", () => emit(context));\n  }\n}\n\n/**\n * Drain every connector's `typings` hook, in array order, sequentially.\n * Connectors without one — every API-only app — are skipped without error.\n */\nexport async function runTypingsContributions(\n  connectors: readonly Connector[],\n  context: ConnectorBuildContext,\n): Promise<void> {\n  for (const connector of connectors) {\n    assertClosedContribution(connector);\n\n    const typings = connector.build?.typings;\n\n    if (!typings) continue;\n\n    await runHook(connector, \"typings\", () => typings(context));\n  }\n}\n\n/**\n * Merge two contributor patches. Later wins, except:\n *\n * - `define` merges per key — two contributors defining different\n *   `import.meta.env.*` entries must both survive; a wholesale replace would\n *   drop one silently.\n * - `external` concatenates and dedupes — it is a set of package names, and\n *   under `singleBundle` each contributor adds its own optional peers.\n * - `loader` merges per extension, for the same reason as `define`.\n * - `plugins` concatenate in contribution order. They are constructed inside\n *   a hook, so this does not reopen the closed-contribution constraint.\n */\nexport function mergeEsbuildPatches(\n  base: ConnectorEsbuildPatch,\n  patch: ConnectorEsbuildPatch,\n): ConnectorEsbuildPatch {\n  const merged: ConnectorEsbuildPatch = { ...base, ...patch };\n\n  if (base.define || patch.define) {\n    merged.define = { ...base.define, ...patch.define };\n  }\n\n  if (base.external || patch.external) {\n    merged.external = dedupe([...(base.external ?? []), ...(patch.external ?? [])]);\n  }\n\n  if (base.loader || patch.loader) {\n    merged.loader = { ...base.loader, ...patch.loader };\n  }\n\n  if (base.plugins || patch.plugins) {\n    merged.plugins = [...(base.plugins ?? []), ...(patch.plugins ?? [])];\n  }\n\n  return merged;\n}\n\n/**\n * Concatenation order preserved — esbuild does not care, but a stable order\n * keeps build output diffable.\n */\nexport function dedupe(values: string[]): string[] {\n  return [...new Set(values)];\n}\n\n/**\n * Run one hook and rename its failure after the connector that owns it.\n */\nasync function runHook<Result>(\n  connector: Connector,\n  hook: \"generate\" | \"emit\" | \"typings\",\n  run: () => Result | Promise<Result>,\n): Promise<Result> {\n  try {\n    return await run();\n  } catch (error) {\n    const cause = error instanceof Error ? error.message : String(error);\n\n    throw new ErrorWithCause(\n      `Build contribution \"${connector.name}\" failed during ${hook}: ${cause}. ` +\n        `The build cannot continue — an artifact this connector was responsible for ` +\n        `is missing, and shipping the bundle without it would fail at runtime instead.`,\n      { cause: error },\n    );\n  }\n}\n"],"mappings":";AASA,MAAM,iBAAiB;;;;;;;;;;;AAYvB,MAAM,4BAA4B;CAAC;CAAY;CAAQ;AAAS;;;;;;AAiBhE,SAAgB,yBAAyB,WAA4B;CACnE,MAAM,eAAe,UAAU;CAE/B,IAAI,CAAC,cAAc;CAEnB,KAAK,MAAM,OAAO,OAAO,KAAK,YAAY,GAAG;EAC3C,IAAK,0BAAgD,SAAS,GAAG,GAAG;EAEpE,MAAM,IAAI,MACR,cAAc,UAAU,KAAK,oDAAoD,IAAI,iEAEhF,0BAA0B,KAAK,IAAI,EAAE,oKAG5C;CACF;AACF;;;;;;;;;;;AAYA,eAAsB,yBACpB,YACA,SACsC;CACtC,MAAM,eAAyB,CAAC;CAChC,IAAI,UAAiC,CAAC;CAEtC,KAAK,MAAM,aAAa,YAAY;EAClC,yBAAyB,SAAS;EAElC,MAAM,WAAW,UAAU,OAAO;EAElC,IAAI,CAAC,UAAU;EAEf,MAAM,SAAS,MAAM,QAAQ,WAAW,kBAAkB,SAAS,OAAO,CAAC;EAE3E,IAAI,CAAC,QAAQ;EAEb,IAAI,OAAO,cACT,aAAa,KAAK,GAAG,OAAO,YAAY;EAG1C,IAAI,OAAO,SACT,UAAU,oBAAoB,SAAS,OAAO,OAAO;CAEzD;CAEA,OAAO;EAAE;EAAc;CAAQ;AACjC;;;;;;;AAQA,eAAsB,qBACpB,YACA,SACe;CACf,KAAK,MAAM,aAAa,YAAY;EAClC,yBAAyB,SAAS;EAElC,MAAM,OAAO,UAAU,OAAO;EAE9B,IAAI,CAAC,MAAM;EAEX,MAAM,QAAQ,WAAW,cAAc,KAAK,OAAO,CAAC;CACtD;AACF;;;;;AAMA,eAAsB,wBACpB,YACA,SACe;CACf,KAAK,MAAM,aAAa,YAAY;EAClC,yBAAyB,SAAS;EAElC,MAAM,UAAU,UAAU,OAAO;EAEjC,IAAI,CAAC,SAAS;EAEd,MAAM,QAAQ,WAAW,iBAAiB,QAAQ,OAAO,CAAC;CAC5D;AACF;;;;;;;;;;;;;AAcA,SAAgB,oBACd,MACA,OACuB;CACvB,MAAM,SAAgC;EAAE,GAAG;EAAM,GAAG;CAAM;CAE1D,IAAI,KAAK,UAAU,MAAM,QACvB,OAAO,SAAS;EAAE,GAAG,KAAK;EAAQ,GAAG,MAAM;CAAO;CAGpD,IAAI,KAAK,YAAY,MAAM,UACzB,OAAO,WAAW,OAAO,CAAC,GAAI,KAAK,YAAY,CAAC,GAAI,GAAI,MAAM,YAAY,CAAC,CAAE,CAAC;CAGhF,IAAI,KAAK,UAAU,MAAM,QACvB,OAAO,SAAS;EAAE,GAAG,KAAK;EAAQ,GAAG,MAAM;CAAO;CAGpD,IAAI,KAAK,WAAW,MAAM,SACxB,OAAO,UAAU,CAAC,GAAI,KAAK,WAAW,CAAC,GAAI,GAAI,MAAM,WAAW,CAAC,CAAE;CAGrE,OAAO;AACT;;;;;AAMA,SAAgB,OAAO,QAA4B;CACjD,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC5B;;;;AAKA,eAAe,QACb,WACA,MACA,KACiB;CACjB,IAAI;EACF,OAAO,MAAM,IAAI;CACnB,SAAS,OAAO;EACd,MAAM,QAAQ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EAEnE,MAAM,IAAI,eACR,uBAAuB,UAAU,KAAK,kBAAkB,KAAK,IAAI,MAAM,6JAGvE,EAAE,OAAO,MAAM,CACjB;CACF;AACF"}

package/esm/production/production-builder.mjs

@@ -4,7 +4,7 @@ import { assertNoReservedConnectorNames } from "../connectors/assert-no-reserved
 import { assertUniqueConnectorNames } from "../connectors/assert-unique-connector-names.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
 import { tsconfigManager } from "../dev-server/tsconfig-manager.mjs";
-import { isConfigFile, isEventFile, isLocaleFile, isMainFile, isRouteFile } from "../dev-server/special-file-patterns.mjs";
+import { isConfigFile, isEventFile, isLocaleFile, isMainFile, isRouteFile, isWorkerFile } from "../dev-server/special-file-patterns.mjs";
 import { configKeyFromPath } from "../config/config-key-from-path.mjs";
 import { assertGeneratedImportsAreDeclared } from "./assert-generated-imports.mjs";
 import { bundleFrameworkDependencies } from "./bundle-framework-dependencies.mjs";
@@ -86,7 +86,8 @@ var ProductionBuilder = class {
 			locales: false,
 			events: false,
 			main: false,
-			routes: false
+			routes: false,
+			workers: false
 		};
 	}
 	/**
@@ -177,7 +178,10 @@ var ProductionBuilder = class {
 			await clearOwnedRouteTypes(rootPath());
 			return;
 		}
-		this.namedApiRoutes = (await collectRouteRegistrationSnapshot({ cwd: rootPath() })).routes;
+		this.namedApiRoutes = (await collectRouteRegistrationSnapshot({
+			cwd: rootPath(),
+			timeoutMs: this.options.routeRegistrationTimeoutMs
+		})).routes;
 	}
 	/**
 	* Drain the `generate` hooks and fold what they returned back into the
@@ -213,17 +217,19 @@ var ProductionBuilder = class {
 		console.log(colors.yellow("   Generating production files..."));
 		await this.generateBootstrap();
 		await this.generateConfigLoader();
-		const [locales, events, main, routes] = await Promise.all([
+		const [locales, events, main, routes, workers] = await Promise.all([
 			this.generateLocales(),
 			this.generateEvents(),
 			this.generateMain(),
-			this.generateRoutes()
+			this.generateRoutes(),
+			this.generateWorkers()
 		]);
 		this.generatedFiles = {
 			locales,
 			events,
 			main,
-			routes
+			routes,
+			workers
 		};
 	}
 	/**
@@ -355,6 +361,16 @@ bootstrap();
 		return true;
 	}
 	/**
+	* Generate workers.ts (only if there are worker files)
+	* @returns true if file was generated with content
+	*/
+	async generateWorkers() {
+		const files = await this.globModule(isWorkerFile);
+		if (files.length === 0) return false;
+		await this.generateImportsFile(files, "workers.ts");
+		return true;
+	}
+	/**
 	* Generate a file with imports from all given files
 	*/
 	async generateImportsFile(importPaths, outputFile) {
@@ -397,7 +413,9 @@ bootstrap();
 			"//     a bind-and-release on a socket that is never served, and it reports",
 			"//     on stderr because no log channel is configured this early.",
 			"import { Application, connectorsManager, ConnectorLifecyclePhase, preflightConfiguredHttpPort } from \"@warlock.js/core\";",
-			"await preflightConfiguredHttpPort();",
+			"if (Application.hasRole(\"api\") || Application.hasRole(\"web\")) {",
+			"  await preflightConfiguredHttpPort();",
+			"}",
 			"",
 			"// 3. Start early-phase connectors (database, cache, logger, ...)",
 			"//    so data sources, cache, etc. are ready before app code runs",
@@ -407,7 +425,8 @@ bootstrap();
 		if (this.generatedFiles.events) imports.push("await import(\"./events\");");
 		if (this.generatedFiles.locales) imports.push("await import(\"./locales\");");
 		if (this.generatedFiles.main) imports.push("await import(\"./main\");");
-		if (this.generatedFiles.routes) imports.push("await import(\"./routes\");");
+		if (this.generatedFiles.routes) imports.push("if (Application.hasRole(\"api\")) {", "  await import(\"./routes\");", "}");
+		if (this.generatedFiles.workers) imports.push("if (Application.hasRole(\"worker\")) {", "  await import(\"./workers\");", "}");
 		imports.push(...contributedImports);
 		imports.push("", "// 5. Run startup validators registered via Application.onValidateBoot(...)", "await Application.runStartupValidators();");
 		imports.push("", "// 6. Start late-phase connectors (http, socket) — routes and", "//    listeners registered by app code are now ready to bind", "await connectorsManager.startPhase(ConnectorLifecyclePhase.Late);", "", "// 7. Signal a complete boot so `Application.onceBooted(...)` listeners fire", "Application.markBooted({ environment: Application.environment, runtimeStrategy: Application.runtimeStrategy });", "connectorsManager.shutdownOnProcessKill();");
@@ -438,6 +457,7 @@ bootstrap();
 		delete esbuildOptions.singleBundle;
 		delete esbuildOptions.esmShim;
 		delete esbuildOptions.banner;
+		delete esbuildOptions.routeRegistrationTimeoutMs;
 		await ensureDirectoryAsync(writeOutDir);
 		const alias = this.buildAliasMapFromTsconfig();
 		const perEdgeExternals = !singleBundle && esbuildOptions.packages === void 0;