@warlock.js/core 5.30.0 → 5.32.0

package/esm/mail/send-mail.d.mts

@@ -1,5 +1,4 @@
 import { MailOptions, MailResult } from "./types.mjs";
-
 //#region ../../packages/core/src/mail/send-mail.d.ts
 /**
  * Send an email
@@ -31,7 +30,6 @@ import { MailOptions, MailResult } from "./types.mjs";
  * await sendMail({ id: mailId, to: "...", subject: "...", html: "..." });
  * ```
  */
-declare function sendMail(options: MailOptions): Promise<MailResult>;
+export declare function sendMail(options: MailOptions): Promise<MailResult>;
 //#endregion
-export { sendMail };
 //# sourceMappingURL=send-mail.d.mts.map

package/esm/mail/send-mail.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"send-mail.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/mail/send-mail.ts"],"mappings":";;;;;AAuRA;;;;;;;;;;;;;AAAwE;;;;;;;;;;;;;;;iBAAlD,QAAA,CAAS,OAAA,EAAS,WAAA,GAAc,OAAA,CAAQ,UAAA"}
+{"version":3,"file":"send-mail.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/mail/send-mail.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAuRsB,SAAS,SAAS,cAAc,QAAQ"}

package/esm/mail/send-mail.mjs

@@ -266,7 +266,8 @@ async function sendMail(options) {
 		return result;
 	}
 	try {
-		const mailer = await getMailer(resolveMailConfig(options));
+		const config = resolveMailConfig(options);
+		const mailer = await getMailer(config);
 		const nodemailerOptions = await buildNodemailerOptions(normalized);
 		log.info(`mail.${driver}`, "send", `Sending mail to ${normalized.to.length} recipient(s): ${normalized.to.map(maskEmail).join(", ")}`);
 		const output = await mailer.sendMail(nodemailerOptions);

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

@@ -1 +1 @@
-{"version":3,"file":"send-mail.mjs","names":[],"sources":["../../../../../../../../packages/core/src/mail/send-mail.ts"],"sourcesContent":["import { log, maskEmail, maskEmailsInText } 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(\n      `mail.${driver}`,\n      \"test\",\n      `[TEST MODE] Captured mail to: ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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(\n      `mail.${driver}`,\n      \"dev\",\n      `[DEV MODE] Would send mail to: ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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    // Recipients are personal data: log them masked (`m***@example.com`),\n    // never in full — the address sits inside the message, where key-based\n    // redaction cannot reach it.\n    log.info(\n      `mail.${driver}`,\n      \"send\",\n      `Sending mail to ${normalized.to.length} recipient(s): ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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(\n        `mail.${driver}`,\n        \"partial\",\n        `Mail partially rejected: ${(rejected as unknown[]).map((address) => maskEmail(String(address))).join(\", \")}`,\n      );\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\", maskEmailsInText(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":";;;;;;;;;;;;;AAqBA,SAAS,oBAAoB,YAAqD;CAChF,IAAI,CAAC,YACH,OAAO,CAAC;CAGV,OAAO,MAAM,QAAQ,UAAU,IAAI,aAAa,CAAC,UAAU;AAC7D;;;;AAKA,SAAS,YAAY,UAAmD;CACtE,OAAO;AACT;;;;AAKA,SAAS,cAAc,SAAsC;CAC3D,MAAM,SAAS,kBAAkB,OAAO;CAExC,OAAO;EACL,IAAI,oBAAoB,QAAQ,EAAE;EAClC,IAAI,oBAAoB,QAAQ,EAAE;EAClC,KAAK,oBAAoB,QAAQ,GAAG;EACpC,SAAS,QAAQ;EACjB,MAAM,QAAQ,QAAQ,OAAO,QAAQ;GAAE,MAAM;GAAY,SAAS;EAAoB;EACtF,SAAS,QAAQ;EACjB,MAAM,QAAQ;EACd,MAAM,QAAQ;EACd,aAAa,QAAQ,eAAe,CAAC;EACrC,UAAU,QAAQ,YAAY;EAC9B,SAAS,QAAQ,WAAW,CAAC;EAC7B,MAAM,QAAQ,QAAQ,CAAC;EACvB,eAAe,QAAQ;EACvB;CACF;AACF;;;;AAKA,eAAe,kBAAkB,YAM9B;CAED,IAAI,WAAW,MACb,IAAI;EACF,MAAM,UAAU,MAAM,SAAS,WAAW,IAAI;EAC9C,OAAO;GACL,UAAU,WAAW;GACrB;GACA,aAAa,WAAW;GACxB,UAAU,WAAW;GACrB,KAAK,WAAW;EAClB;CACF,SAAS,OAAO;EACd,MAAM,IAAI,UACR,mCAAmC,WAAW,KAAK,KAAK,iBAAiB,QAAQ,MAAM,UAAU,mBACjG,gBACA,iBAAiB,QAAQ,QAAQ,MACnC;CACF;CAIF,OAAO;EACL,UAAU,WAAW;EACrB,SAAS,WAAW;EACpB,aAAa,WAAW;EACxB,UAAU,WAAW;EACrB,KAAK,WAAW;CAClB;AACF;;;;AAKA,eAAe,uBAAuB,YAAwD;CAC5F,MAAM,UAA6B;EACjC,IAAI,WAAW;EAEf,MAAM,WAAW;EACjB,SAAS,WAAW;EACpB,UAAU,YAAY,WAAW,QAAQ;CAC3C;CAEA,IAAI,WAAW,GAAG,SAAS,GACzB,QAAQ,KAAK,WAAW;CAG1B,IAAI,WAAW,IAAI,SAAS,GAC1B,QAAQ,MAAM,WAAW;CAG3B,IAAI,WAAW,SACb,QAAQ,UAAU,WAAW;CAG/B,IAAI,WAAW,MACb,QAAQ,OAAO,WAAW;CAG5B,IAAI,WAAW,MACb,QAAQ,OAAO,WAAW;CAG5B,IAAI,WAAW,YAAY,SAAS,GAMlC,QAAQ,eAAc,MAJY,QAAQ,IACxC,WAAW,YAAY,KAAK,QAAQ,kBAAkB,GAAqB,CAAC,CAC9E,EAEyC,CAAC,KAAK,SAAS;EACtD,UAAU,IAAI;EACd,SAAS,IAAI;EACb,aAAa,IAAI;EACjB,UAAU,IAAI;EACd,KAAK,IAAI;CACX,EAAE;CAGJ,IAAI,OAAO,KAAK,WAAW,OAAO,CAAC,CAAC,SAAS,GAC3C,QAAQ,UAAU,WAAW;CAG/B,OAAO;AACT;;;;AAKA,SAAS,gBAAgB,OAAmC;CAC1D,IAAI,iBAAiB,WACnB,OAAO,MAAM;CAGf,MAAM,EAAE,MAAM,iBAAkB,SAAS,CAAC;CAE1C,IAAI,SAAS,WAAW,iBAAiB,OAAO,iBAAiB,KAAK,OAAO;CAE7E,IAAI;EAAC;EAAe;EAAgB;EAAa;CAAS,CAAC,CAAC,SAAS,IAAc,GACjF,OAAO;CAGT,IAAI;EAAC;EAAa;EAAY;CAAoB,CAAC,CAAC,SAAS,IAAc,GAAG,OAAO;CACrF,IAAI,SAAS,aAAa,OAAO;CACjC,IAAI,gBAAgB;EAAC;EAAK;EAAK;EAAK;CAAG,CAAC,CAAC,SAAS,YAAY,GAAG,OAAO;CAExE,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;CAEzD,IAAI,QAAQ,SAAS,cAAc,KAAK,QAAQ,SAAS,WAAW,GAAG,OAAO;CAC9E,IAAI,QAAQ,SAAS,gBAAgB,KAAK,QAAQ,SAAS,MAAM,GAAG,OAAO;CAC3E,IAAI,QAAQ,SAAS,SAAS,KAAK,QAAQ,SAAS,WAAW,GAAG,OAAO;CACzE,IAAI,QAAQ,SAAS,MAAM,KAAK,QAAQ,SAAS,OAAO,GAAG,OAAO;CAElE,OAAO;AACT;;;;AAKA,eAAe,aACb,SACA,GAAG,MACiC;CACpC,IAAI,CAAC,SACH;CAGF,IAAI;EACF,OAAO,MAAM,QAAQ,GAAG,IAAI;CAC9B,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,SAAS,iCAAiC,OAAO;EACnE;CACF;AACF;;;;AAKA,eAAe,cACb,QACA,OACA,GAAG,MACa;CAChB,IAAI;EAEF,MAAM,kBACJ,UAAU,kBACN,mBACA,UAAU,SACR,SACA,UAAU,YACR,YACA;EAEV,MAAM,gBAAgB,MAAM,WAAW,QACrC,iBACA,GAAG,IACL;EAGA,MAAM,kBAAkB,MAAM,WAAW,eAAe,QAAQ,OAAO,GAAG,IAAI;EAE9E,OAAO,CAAC,GAAI,iBAAiB,CAAC,GAAI,GAAI,mBAAmB,CAAC,CAAE;CAC9D,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,SAAS,wBAAwB,OAAO;EAC1D,OAAO,CAAC;CACV;AACF;;;;;AAMA,SAAS,oBAAoB,UAA8B;CACzD,IAAI;EACF,WAAW,QAAQ,YAAY,QAAQ;CACzC,SAAS,OAAO;EACd,IAAI,MAAM,QAAQ,SAAS,sCAAsC,OAAO;CAC1E;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,eAAsB,SAAS,SAA2C;CAExE,MAAM,SAAS,QAAQ,MAAM,eAAe;CAG5C,IAAI,QAAQ,WACV,IAAI;EACF,QAAQ,OAAO,MAAM,gBAAgB,QAAQ,SAAS;CACxD,SAAS,OAAO;EACd,MAAM,YAAY,IAAI,UACpB,qCAAqC,iBAAiB,QAAQ,MAAM,UAAU,mBAC9E,gBACA,iBAAiB,QAAQ,QAAQ,MACnC;EAEA,MAAM,aAAa,QAAQ,SAAS,SAAS,SAAS;EACtD,MAAM,cAAc,QAAQ,SAAS,SAAS,SAAS;EAEvD,MAAM;CACR;CAIF,MAAM,aAAa,cAAc,OAAO;CACxC,MAAM,SAAS,WAAW,OAAO,UAAU;CAG3C,MAAM,eAAe,MAAM,aAAa,QAAQ,eAAe,OAAO;CACtE,MAAM,sBAAsB,MAAM,cAAc,QAAQ,iBAAiB,OAAO;CAGhF,IAAI,iBAAiB,SAAS,oBAAoB,MAAM,MAAM,MAAM,KAAK,GAAG;EAC1E,IAAI,KAAK,QAAQ,UAAU,aAAa,+CAA+C;EASvF,OAAO;GANL,SAAS;GACT,UAAU,CAAC;GACX,UAAU,WAAW;GACrB,UAAU;EAGA;CACd;CAGA,IAAI,WAAW,GAAG;EAChB,IAAI,KACF,QAAQ,UACR,QACA,iCAAiC,WAAW,GAAG,IAAI,SAAS,CAAC,CAAC,KAAK,IAAI,GACzE;EAEA,MAAM,SAAqB;GACzB,SAAS;GACT,WAAW,QAAQ,OAAO;GAC1B,UAAU,WAAW;GACrB,UAAU,CAAC;GACX,UAAU;EACZ;EAEA,MAAM,WAAyB;GAC7B,IAAI;GACJ;GACA;GACA,2BAAW,IAAI,KAAK;GACpB;EACF;EAEA,YAAY,QAAQ;EACpB,oBAAoB,QAAQ;EAE5B,MAAM,aAAa,QAAQ,WAAW,SAAS,MAAM;EACrD,MAAM,cAAc,QAAQ,WAAW,SAAS,MAAM;EACtD,MAAM,aAAa,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EACxD,MAAM,cAAc,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EAEzD,OAAO;CACT;CAGA,IAAI,kBAAkB,GAAG;EACvB,IAAI,KACF,QAAQ,UACR,OACA,kCAAkC,WAAW,GAAG,IAAI,SAAS,CAAC,CAAC,KAAK,IAAI,GAC1E;EACA,IAAI,KAAK,QAAQ,UAAU,OAAO,YAAY,WAAW,SAAS;EAElE,IAAI,WAAW,MACb,IAAI,KAAK,QAAQ,UAAU,OAAO,gBAAgB,WAAW,KAAK,OAAO,OAAO;EAGlF,MAAM,SAAqB;GACzB,SAAS;GACT,WAAW,OAAO,OAAO;GACzB,UAAU,WAAW;GACrB,UAAU,CAAC;GACX,UAAU;EACZ;EAUA,oBAAoB;GAPlB,IAAI;GACJ;GACA;GACA,2BAAW,IAAI,KAAK;GACpB;EAGyB,CAAC;EAE5B,MAAM,aAAa,QAAQ,WAAW,SAAS,MAAM;EACrD,MAAM,cAAc,QAAQ,WAAW,SAAS,MAAM;EACtD,MAAM,aAAa,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EACxD,MAAM,cAAc,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EAEzD,OAAO;CACT;CAGA,IAAI;EAEF,MAAM,SAAS,MAAM,UADN,kBAAkB,OACG,CAAC;EACrC,MAAM,oBAAoB,MAAM,uBAAuB,UAAU;EAKjE,IAAI,KACF,QAAQ,UACR,QACA,mBAAmB,WAAW,GAAG,OAAO,iBAAiB,WAAW,GAAG,IAAI,SAAS,CAAC,CAAC,KAAK,IAAI,GACjG;EAEA,MAAM,SAAS,MAAM,OAAO,SAAS,iBAAiB;EAEtD,MAAM,WAAW,OAAO,aAAa,OAAO,YAAY,WAAW,KAAK,CAAC;EACzE,MAAM,WAAW,OAAO,YAAY,CAAC;EAErC,IAAI,SAAS,WAAW,GACtB,MAAM,IAAI,UACR,iCAAkC,SAAsB,KAAK,IAAI,KACjE,UACF;EAGF,MAAM,SAAqB;GACzB,SAAS;GACT,WAAW,OAAO;GACR;GACA;GACV,UAAU,OAAO;GACjB,UAAU,OAAO;EACnB;EAEA,IAAI,SAAS,SAAS,GACpB,IAAI,KACF,QAAQ,UACR,WACA,4BAA6B,SAAuB,KAAK,YAAY,UAAU,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,GAC5G;EAGF,IAAI,QAAQ,QAAQ,UAAU,QAAQ,+BAA+B,OAAO,UAAU,EAAE;EACxF,MAAM,aAAa,QAAQ,WAAW,SAAS,MAAM;EACrD,MAAM,cAAc,QAAQ,WAAW,SAAS,MAAM;EAEtD,MAAM,aAAa,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EACxD,MAAM,cAAc,QAAQ,QAAQ,SAAS,QAAQ,IAAI;EAEzD,OAAO;CACT,SAAS,OAAO;EACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU;EAC9D,MAAM,OAAO,gBAAgB,KAAK;EAElC,MAAM,YAAY,IAAI,UACpB,wBAAwB,gBACxB,MACA,iBAAiB,QAAQ,QAAQ,MACnC;EAEA,IAAI,MAAM,QAAQ,UAAU,SAAS,iBAAiB,UAAU,OAAO,CAAC;EAExE,MAAM,aAAa,QAAQ,SAAS,SAAS,SAAS;EACtD,MAAM,cAAc,QAAQ,SAAS,SAAS,SAAS;EACvD,MAAM,aAAa,QAAQ,QAAQ,SAAS,MAAM,SAAS;EAC3D,MAAM,cAAc,QAAQ,QAAQ,SAAS,MAAM,SAAS;EAE5D,MAAM;CACR;AACF"}
+{"version":3,"file":"send-mail.mjs","names":[],"sources":["../../../../../../../../packages/core/src/mail/send-mail.ts"],"sourcesContent":["import { log, maskEmail, maskEmailsInText } 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(\n      `mail.${driver}`,\n      \"test\",\n      `[TEST MODE] Captured mail to: ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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(\n      `mail.${driver}`,\n      \"dev\",\n      `[DEV MODE] Would send mail to: ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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    // Recipients are personal data: log them masked (`m***@example.com`),\n    // never in full — the address sits inside the message, where key-based\n    // redaction cannot reach it.\n    log.info(\n      `mail.${driver}`,\n      \"send\",\n      `Sending mail to ${normalized.to.length} recipient(s): ${normalized.to.map(maskEmail).join(\", \")}`,\n    );\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(\n        `mail.${driver}`,\n        \"partial\",\n        `Mail partially rejected: ${(rejected as unknown[]).map((address) => maskEmail(String(address))).join(\", \")}`,\n      );\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\", maskEmailsInText(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/test-mailbox.d.mts

@@ -1,50 +1,48 @@
 import { CapturedMail } from "./types.mjs";
-
 //#region ../../packages/core/src/mail/test-mailbox.d.ts
 /**
  * Add a mail to the test mailbox
  */
-declare function captureMail(mail: CapturedMail): void;
+export declare function captureMail(mail: CapturedMail): void;
 /**
  * Get all captured mails
  */
-declare function getTestMailbox(): CapturedMail[];
+export declare function getTestMailbox(): CapturedMail[];
 /**
  * Get the last captured mail
  */
-declare function getLastMail(): CapturedMail | undefined;
+export declare function getLastMail(): CapturedMail | undefined;
 /**
  * Find mails by recipient
  */
-declare function findMailsTo(email: string): CapturedMail[];
+export declare function findMailsTo(email: string): CapturedMail[];
 /**
  * Find mails by subject (partial match)
  */
-declare function findMailsBySubject(subject: string): CapturedMail[];
+export declare function findMailsBySubject(subject: string): CapturedMail[];
 /**
  * Check if a mail was sent to a specific recipient
  */
-declare function wasMailSentTo(email: string): boolean;
+export declare function wasMailSentTo(email: string): boolean;
 /**
  * Check if a mail with specific subject was sent
  */
-declare function wasMailSentWithSubject(subject: string): boolean;
+export declare function wasMailSentWithSubject(subject: string): boolean;
 /**
  * Get mailbox size
  */
-declare function getMailboxSize(): number;
+export declare function getMailboxSize(): number;
 /**
  * Clear the test mailbox
  */
-declare function clearTestMailbox(): void;
+export declare function clearTestMailbox(): void;
 /**
  * Assert helper for testing
  */
-declare function assertMailSent(predicate: (mail: CapturedMail) => boolean): CapturedMail;
+export declare function assertMailSent(predicate: (mail: CapturedMail) => boolean): CapturedMail;
 /**
  * Assert that a specific number of mails were sent
  */
-declare function assertMailCount(count: number): void;
+export declare function assertMailCount(count: number): void;
 //#endregion
-export { assertMailCount, assertMailSent, captureMail, clearTestMailbox, findMailsBySubject, findMailsTo, getLastMail, getMailboxSize, getTestMailbox, wasMailSentTo, wasMailSentWithSubject };
 //# sourceMappingURL=test-mailbox.d.mts.map

package/esm/mail/test-mailbox.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"test-mailbox.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/mail/test-mailbox.ts"],"mappings":";;;;;;iBA2EgB,WAAA,CAAY,IAAkB,EAAZ,YAAY;;;;iBAO9B,cAAA,IAAkB,YAAY;;;;iBAO9B,WAAA,IAAe,YAAY;;;;iBAO3B,WAAA,CAAY,KAAA,WAAgB,YAAY;;;;iBAUxC,kBAAA,CAAmB,OAAA,WAAkB,YAAY;;;;iBAOjD,aAAA,CAAc,KAAa;;;;iBAO3B,sBAAA,CAAuB,OAAe;;;;iBAOtC,cAAA;;;;iBAOA,gBAAA;;;;iBAOA,cAAA,CAAe,SAAA,GAAY,IAAA,EAAM,YAAA,eAA2B,YAAY;;;;iBAaxE,eAAA,CAAgB,KAAa"}
+{"version":3,"file":"test-mailbox.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/mail/test-mailbox.ts"],"mappings":";;;;;wBA2EgB,YAAY,MAAM;;;;wBAOlB,kBAAkB;;;;wBAOlB,eAAe;;;;wBAOf,YAAY,gBAAgB;;;;wBAU5B,mBAAmB,kBAAkB;;;;wBAOrC,cAAc;;;;wBAOd,uBAAuB;;;;wBAOvB;;;;wBAOA;;;;wBAOA,eAAe,YAAY,MAAM,2BAA2B;;;;wBAa5D,gBAAgB"}

package/esm/mail/types.d.mts

@@ -1,11 +1,10 @@
 import React from "react";
 import SMTPTransport from "nodemailer/lib/smtp-transport";
-
 //#region ../../packages/core/src/mail/types.d.ts
 /**
  * AWS SES mail configuration
  */
-type SESConfigurations = {
+export type SESConfigurations = {
   driver: "ses";
   accessKeyId: string;
   secretAccessKey: string;
@@ -15,19 +14,19 @@ type SESConfigurations = {
 /**
  * Any mail configuration (SMTP or SES)
  */
-type MailConfigurations = SMTPConfigurations | SESConfigurations;
+export type MailConfigurations = SMTPConfigurations | SESConfigurations;
 /**
  * Mail mode determines how emails are handled
  */
-type MailMode = "production" | "development" | "test";
+export type MailMode = "production" | "development" | "test";
 /**
  * Mail priority levels
  */
-type MailPriority = "high" | "normal" | "low";
+export type MailPriority = "high" | "normal" | "low";
 /**
  * Email address with optional name
  */
-type MailAddress = string | {
+export type MailAddress = string | {
   name: string;
   address: string;
 };
@@ -35,7 +34,7 @@ type MailAddress = string | {
  * Mail attachment
  * Supports both buffer/string content and file paths
  */
-type MailAttachment = {
+export type MailAttachment = {
   filename: string;
   contentType?: string;
   encoding?: "base64" | "binary" | "hex";
@@ -112,7 +111,7 @@ type MailAttachment = {
  * });
  * ```
  */
-type SMTPConfigurations = SMTPTransport.Options & {
+export type SMTPConfigurations = SMTPTransport.Options & {
   /**
    * Transport driver type
    */
@@ -141,7 +140,7 @@ type SMTPConfigurations = SMTPTransport.Options & {
 /**
  * Named mailers configuration
  */
-type MailersConfig = {
+export type MailersConfig = {
   /**
    * Default mailer configuration
    */
@@ -154,7 +153,7 @@ type MailersConfig = {
 /**
  * Mail result after sending
  */
-type MailResult = {
+export type MailResult = {
   success: boolean;
   messageId?: string;
   accepted: string[];
@@ -168,12 +167,12 @@ type MailResult = {
 /**
  * Error codes for mail operations
  */
-type MailErrorCode = "CONNECTION_ERROR" | "AUTH_ERROR" | "RATE_LIMIT" | "INVALID_ADDRESS" | "REJECTED" | "TIMEOUT" | "RENDER_ERROR" | "CONFIG_ERROR" | "UNKNOWN";
+export type MailErrorCode = "CONNECTION_ERROR" | "AUTH_ERROR" | "RATE_LIMIT" | "INVALID_ADDRESS" | "REJECTED" | "TIMEOUT" | "RENDER_ERROR" | "CONFIG_ERROR" | "UNKNOWN";
 /**
  * Mail event callbacks (per-mail)
  * For global events, use mailEvents.on() from events.ts
  */
-type MailEvents = {
+export type MailEvents = {
   /**
    * Called before sending the email
    * Can be used to modify the mail or cancel sending
@@ -195,7 +194,7 @@ type MailEvents = {
 /**
  * Mail options for sending
  */
-type MailOptions = {
+export type MailOptions = {
   /**
    * Unique mail ID for event namespacing
    * If not provided, one will be auto-generated
@@ -228,7 +227,7 @@ type MailOptions = {
 /**
  * Internal normalized mail data
  */
-type NormalizedMail = {
+export type NormalizedMail = {
   to: string[];
   cc: string[];
   bcc: string[];
@@ -250,8 +249,9 @@ type NormalizedMail = {
  * 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;
+export type CapturedMail = {
+  /** The mail ID used for event namespacing and result correlation. */
+  id: string;
   options: MailOptions;
   normalized: NormalizedMail;
   timestamp: Date;
@@ -261,11 +261,10 @@ type CapturedMail = {
 /**
  * Mail error class
  */
-declare class MailError extends Error {
+export declare class MailError extends Error {
   readonly code: MailErrorCode;
   readonly originalError?: Error;
   constructor(message: string, code: MailErrorCode, originalError?: Error);
 }
 //#endregion
-export { CapturedMail, MailAddress, MailAttachment, MailConfigurations, MailError, MailErrorCode, MailEvents, MailMode, MailOptions, MailPriority, MailResult, MailersConfig, NormalizedMail, SESConfigurations, SMTPConfigurations };
 //# sourceMappingURL=types.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/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"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/mail/types.ts"],"mappings":";;;;;;YAMY;EACV;EACA;EACA;EACA;EACA,OAAO;;;;;YAMG,qBAAqB,qBAAqB;;;;YAK1C;;;;YAKA;;;;YAKA;EAGN;EACA;;;;;;YAOM;EACV;EACA;EACA;EACA;;EAGI,SAAS;EACT;;EAGA;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAqEM,qBAAqB,cAAc;;;;EAI7C;;;;;EAKA;;;;;EAKA;;;;;EAKA;;;;;EAKA,OAAO;;;;;YAMG;;;;EAIV,UAAU;;;;EAIV,UAAU,eAAe;;;;;YAMf;EACV;EACA;EACA;EACA;EACA;EACA;IACE;IACA;;;;;;YAOQ;;;;;YAeA;;;;;EAKV,iBAAiB,MAAM,uBAAuB,wBAAwB;;;;EAItE,UACE,MAAM,aACN,QAAQ,mBACR,OAAO,4BACG;;;;EAIZ,aAAa,MAAM,aAAa,QAAQ,sBAAsB;;;;EAI9D,WAAW,MAAM,aAAa,OAAO,qBAAqB;;;;;YAMhD;;;;;;;;;;;;EAYV;EAGA;EACA;EACA;EACA;EAGA;EACA;EACA;EACA,YAAY,MAAM;EAGlB,SAAS;EACT;EACA,OAAO;EAGP,cAAc;EAGd,WAAW;EACX,UAAU;EACV;EAGA;IACE;;;;YAKQ;EACV;EACA;EACA;EACA;EACA,MAAM;EACN;EACA;EACA;EACA,aAAa;EACb,UAAU;EACV,SAAS;EACT;EACA;EACA,QAAQ;;;;;;;;YASE;;EAEV;EACA,SAAS;EACT,YAAY;EACZ,WAAW;EACX,SAAS;EACT,QAAQ;;;;;qBAMG,kBAAkB;WACb,MAAM;WACN,gBAAgB;EAEhC,YAAmB,iBAAiB,MAAM,eAAe,gBAAgB"}

package/esm/manifest/manifest-manager.mjs

@@ -75,5 +75,5 @@ var ManifestManager = class {
 const manifestManager = new ManifestManager();
 
 //#endregion
-export { manifestManager };
+export { ManifestManager, manifestManager };
 //# sourceMappingURL=manifest-manager.mjs.map

package/esm/net/index.d.mts

@@ -0,0 +1,2 @@
+import { isPrivateOrReservedIp } from "../storage/utils/classify-ip-address.mjs";
+export { isPrivateOrReservedIp };

package/esm/net/index.mjs

@@ -0,0 +1,3 @@
+import { isPrivateOrReservedIp } from "../storage/utils/classify-ip-address.mjs";
+
+export { isPrivateOrReservedIp };

package/esm/openapi/build-openapi-document.d.mts

@@ -1,8 +1,7 @@
 import { OpenApiBuildResult, OpenApiContext, OpenApiRouteInput } from "./types.mjs";
-
 //#region ../../packages/core/src/openapi/build-openapi-document.d.ts
 /** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */
-declare const OPENAPI_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export declare const OPENAPI_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
 /**
  * Build an OpenAPI 3.1 document from registered routes.
  *
@@ -11,7 +10,6 @@ declare const OPENAPI_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-
  * `warnings`. It never throws for a single route it cannot document; that route is
  * documented as far as possible and a warning explains what was left out.
  */
-declare function buildOpenApiDocument(routes: readonly OpenApiRouteInput[], context: OpenApiContext): OpenApiBuildResult;
+export declare function buildOpenApiDocument(routes: readonly OpenApiRouteInput[], context: OpenApiContext): OpenApiBuildResult;
 //#endregion
-export { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument };
 //# sourceMappingURL=build-openapi-document.d.mts.map

package/esm/openapi/build-openapi-document.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"build-openapi-document.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/build-openapi-document.ts"],"mappings":";;;;cA2Ba,2BAAA;AAAb;;;;AAAwC;AA8BxC;;;AA9BA,iBA8BgB,oBAAA,CACd,MAAA,WAAiB,iBAAA,IACjB,OAAA,EAAS,cAAA,GACR,kBAAA"}
+{"version":3,"file":"build-openapi-document.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/build-openapi-document.ts"],"mappings":";;;qBA6Ba;;;;;;;;;wBA8BG,qBACd,iBAAiB,qBACjB,SAAS,iBACR"}

package/esm/openapi/build-openapi-document.mjs

@@ -1,5 +1,6 @@
+import { resolveRouteValidation } from "../router/resolve-route-validation.mjs";
 import { buildDeclaredResponses } from "./response-schemas.mjs";
-import { buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse } from "./error-responses.mjs";
+import { buildCustomValidationFailedResponse, buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse } from "./error-responses.mjs";
 import { buildOperationId, expandMethods, firstSegmentTag, toOpenApiPath } from "./paths.mjs";
 import { buildRequestParts } from "./request-schemas.mjs";
 import { SchemaRegistry } from "./schema-registry.mjs";
@@ -46,7 +47,7 @@ function buildOpenApiDocument(routes, context) {
 			continue;
 		}
 		const handler = route.handler;
-		const validation = handler?.validation;
+		const validation = resolveRouteValidation(route);
 		const auth = readRouteAuth(route.middleware, warn);
 		const tag = firstSegmentTag(route.path);
 		const pathKey = toOpenApiPath(route.path);
@@ -72,14 +73,16 @@ function buildOpenApiDocument(routes, context) {
 				validation,
 				warn
 			});
-			const responses = route.isPage ? { "200": {
+			const declared = route.isPage ? { "200": {
 				description: "HTML page",
 				content: { "text/html": { schema: { type: "string" } } }
 			} } : buildDeclaredResponses(handler?.responseSchema, registry, warn);
+			const responses = { ...declared };
 			if (!Object.keys(responses).some((status) => status.startsWith("2"))) responses["200"] = { description: "Successful response" };
 			if (validation?.schema) {
-				const failed = buildValidationFailedResponse(validationShape, registry);
-				responses[failed.status] ??= failed.response;
+				const routeHook = typeof validation.onFailure === "function";
+				const failed = routeHook || validationShape.customBody ? buildCustomValidationFailedResponse(validationShape, declared, routeHook, warn) : buildValidationFailedResponse(validationShape, registry);
+				if (failed) responses[failed.status] ??= failed.response;
 			}
 			if (auth) responses["401"] ??= buildUnauthorizedResponse(registry);
 			if (tag) tags.add(tag);

package/esm/openapi/build-openapi-document.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"build-openapi-document.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/build-openapi-document.ts"],"sourcesContent":["import {\n  buildUnauthorizedResponse,\n  buildValidationFailedResponse,\n  resolveValidationResponse,\n} from \"./error-responses\";\nimport {\n  buildOperationId,\n  expandMethods,\n  firstSegmentTag,\n  toOpenApiPath,\n  type OpenApiMethod,\n} from \"./paths\";\nimport { buildRequestParts } from \"./request-schemas\";\nimport { buildDeclaredResponses } from \"./response-schemas\";\nimport { SchemaRegistry } from \"./schema-registry\";\nimport { readRouteAuth, SecuritySchemes } from \"./security\";\nimport type {\n  AuthDescriptor,\n  OpenApiBuildResult,\n  OpenApiContext,\n  OpenApiDocument,\n  OpenApiOperation,\n  OpenApiResponse,\n  OpenApiRouteInput,\n} from \"./types\";\n\n/** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */\nexport const OPENAPI_JSON_SCHEMA_DIALECT = \"https://json-schema.org/draft/2020-12/schema\";\n\nconst UNSAFE_METHODS: readonly OpenApiMethod[] = [\"post\", \"put\", \"patch\", \"delete\"];\n\nfunction describeAuth(auth: AuthDescriptor, method: OpenApiMethod): string[] {\n  const lines: string[] = [];\n\n  if (auth.userTypes.length > 0) {\n    lines.push(`Requires an authenticated user of type: ${auth.userTypes.join(\", \")}.`);\n  }\n\n  const usesCookie = auth.sources.some((source) => typeof source !== \"string\");\n\n  if (usesCookie && UNSAFE_METHODS.includes(method)) {\n    lines.push(\n      \"When authenticating with the cookie, the request must also carry a same-origin Origin or Referer header (CSRF guard).\",\n    );\n  }\n\n  return lines;\n}\n\n/**\n * Build an OpenAPI 3.1 document from registered routes.\n *\n * Pure: it reads the routes it is given (`router.list()` in the app), converts Seal schemas\n * with `toJsonSchema(\"draft-2020-12\")` and returns plain JSON plus the gaps it found as\n * `warnings`. It never throws for a single route it cannot document; that route is\n * documented as far as possible and a warning explains what was left out.\n */\nexport function buildOpenApiDocument(\n  routes: readonly OpenApiRouteInput[],\n  context: OpenApiContext,\n): OpenApiBuildResult {\n  const warnings: string[] = [];\n  const registry = new SchemaRegistry(context.resolveResourceName, (message) => warnings.push(message));\n  const security = new SecuritySchemes();\n  const validationShape = resolveValidationResponse(context.validationResponse);\n  const paths: OpenApiDocument[\"paths\"] = {};\n  const tags = new Set<string>();\n  const operationIds = new Set<string>();\n\n  for (const route of routes) {\n    if (route.isPage && !context.includePages) {\n      continue;\n    }\n\n    const methods = expandMethods(route.method);\n    const label = `${String(route.method).toUpperCase()} ${route.path}`;\n    const warn = (message: string) => warnings.push(`${label}: ${message}`);\n\n    if (methods.length === 0) {\n      warn(`unsupported method \"${String(route.method)}\", route skipped.`);\n\n      continue;\n    }\n\n    const handler = route.handler as OpenApiRouteInput[\"handler\"] | undefined;\n    const validation = handler?.validation;\n    const auth = readRouteAuth(route.middleware, warn);\n    const tag = firstSegmentTag(route.path);\n    const pathKey = toOpenApiPath(route.path);\n\n    if (validation?.validate) {\n      warn(\"validation.validate is custom middleware and is not documented.\");\n    }\n\n    for (const method of methods) {\n      paths[pathKey] ??= {};\n\n      if (paths[pathKey][method]) {\n        warn(`${method.toUpperCase()} ${pathKey} is already documented by an earlier route; this one is skipped.`);\n\n        continue;\n      }\n\n      let operationId = buildOperationId(route.name, method, route.path, methods.length > 1);\n\n      if (operationIds.has(operationId)) {\n        let suffix = 2;\n\n        while (operationIds.has(`${operationId}_${suffix}`)) {\n          suffix++;\n        }\n\n        warn(`operationId \"${operationId}\" is already used; renamed to \"${operationId}_${suffix}\".`);\n        operationId = `${operationId}_${suffix}`;\n      }\n\n      operationIds.add(operationId);\n\n      const description = [\n        route.description ?? handler?.description,\n        ...(auth ? describeAuth(auth, method) : []),\n      ].filter((line): line is string => typeof line === \"string\" && line.length > 0);\n\n      const request = buildRequestParts({ method, path: route.path, validation, warn });\n\n      const responses: Record<string, OpenApiResponse> = route.isPage\n        ? { \"200\": { description: \"HTML page\", content: { \"text/html\": { schema: { type: \"string\" } } } } }\n        : buildDeclaredResponses(handler?.responseSchema, registry, warn);\n\n      if (!Object.keys(responses).some((status) => status.startsWith(\"2\"))) {\n        responses[\"200\"] = { description: \"Successful response\" };\n      }\n\n      if (validation?.schema) {\n        const failed = buildValidationFailedResponse(validationShape, registry);\n\n        responses[failed.status] ??= failed.response;\n      }\n\n      if (auth) {\n        responses[\"401\"] ??= buildUnauthorizedResponse(registry);\n      }\n\n      if (tag) {\n        tags.add(tag);\n      }\n\n      // Built in reading order: identity, prose, inputs, outputs, security.\n      const operation: OpenApiOperation = {\n        operationId,\n        ...(route.label ? { summary: route.label } : {}),\n        ...(description.length > 0 ? { description: description.join(\"\\n\\n\") } : {}),\n        ...(tag ? { tags: [tag] } : {}),\n        ...(request.parameters.length > 0 ? { parameters: request.parameters } : {}),\n        ...(request.requestBody ? { requestBody: request.requestBody } : {}),\n        responses: sortResponses(responses),\n        ...(auth ? { security: security.requirementsFor(auth) } : {}),\n      };\n\n      paths[pathKey][method] = operation;\n    }\n  }\n\n  // Keys in reading order: header, servers, tags, paths, components.\n  const document: OpenApiDocument = {\n    openapi: \"3.1.0\",\n    jsonSchemaDialect: OPENAPI_JSON_SCHEMA_DIALECT,\n    info: { ...context.info },\n    ...(context.servers && context.servers.length > 0\n      ? { servers: context.servers.map((url) => ({ url })) }\n      : {}),\n    ...(tags.size > 0 ? { tags: [...tags].sort().map((name) => ({ name })) } : {}),\n    paths,\n  };\n\n  const hasSchemas = Object.keys(registry.schemas).length > 0;\n\n  if (hasSchemas || security.hasSchemes()) {\n    document.components = {};\n\n    if (hasSchemas) {\n      document.components.schemas = registry.schemas;\n    }\n\n    if (security.hasSchemes()) {\n      document.components.securitySchemes = security.schemes;\n    }\n  }\n\n  return { document, warnings: [...new Set(warnings)] };\n}\n\nfunction sortResponses(responses: Record<string, OpenApiResponse>): Record<string, OpenApiResponse> {\n  return Object.fromEntries(\n    Object.entries(responses).sort(([first], [second]) => first.localeCompare(second)),\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"build-openapi-document.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/build-openapi-document.ts"],"sourcesContent":["import { resolveRouteValidation } from \"../router/resolve-route-validation\";\nimport {\n  buildCustomValidationFailedResponse,\n  buildUnauthorizedResponse,\n  buildValidationFailedResponse,\n  resolveValidationResponse,\n} from \"./error-responses\";\nimport {\n  buildOperationId,\n  expandMethods,\n  firstSegmentTag,\n  toOpenApiPath,\n  type OpenApiMethod,\n} from \"./paths\";\nimport { buildRequestParts } from \"./request-schemas\";\nimport { buildDeclaredResponses } from \"./response-schemas\";\nimport { SchemaRegistry } from \"./schema-registry\";\nimport { readRouteAuth, SecuritySchemes } from \"./security\";\nimport type {\n  AuthDescriptor,\n  OpenApiBuildResult,\n  OpenApiContext,\n  OpenApiDocument,\n  OpenApiOperation,\n  OpenApiResponse,\n  OpenApiRouteInput,\n} from \"./types\";\n\n/** `jsonSchemaDialect` of every document: OpenAPI 3.1 schemas are JSON Schema 2020-12. */\nexport const OPENAPI_JSON_SCHEMA_DIALECT = \"https://json-schema.org/draft/2020-12/schema\";\n\nconst UNSAFE_METHODS: readonly OpenApiMethod[] = [\"post\", \"put\", \"patch\", \"delete\"];\n\nfunction describeAuth(auth: AuthDescriptor, method: OpenApiMethod): string[] {\n  const lines: string[] = [];\n\n  if (auth.userTypes.length > 0) {\n    lines.push(`Requires an authenticated user of type: ${auth.userTypes.join(\", \")}.`);\n  }\n\n  const usesCookie = auth.sources.some((source) => typeof source !== \"string\");\n\n  if (usesCookie && UNSAFE_METHODS.includes(method)) {\n    lines.push(\n      \"When authenticating with the cookie, the request must also carry a same-origin Origin or Referer header (CSRF guard).\",\n    );\n  }\n\n  return lines;\n}\n\n/**\n * Build an OpenAPI 3.1 document from registered routes.\n *\n * Pure: it reads the routes it is given (`router.list()` in the app), converts Seal schemas\n * with `toJsonSchema(\"draft-2020-12\")` and returns plain JSON plus the gaps it found as\n * `warnings`. It never throws for a single route it cannot document; that route is\n * documented as far as possible and a warning explains what was left out.\n */\nexport function buildOpenApiDocument(\n  routes: readonly OpenApiRouteInput[],\n  context: OpenApiContext,\n): OpenApiBuildResult {\n  const warnings: string[] = [];\n  const registry = new SchemaRegistry(context.resolveResourceName, (message) =>\n    warnings.push(message),\n  );\n  const security = new SecuritySchemes();\n  const validationShape = resolveValidationResponse(context.validationResponse);\n  const paths: OpenApiDocument[\"paths\"] = {};\n  const tags = new Set<string>();\n  const operationIds = new Set<string>();\n\n  for (const route of routes) {\n    if (route.isPage && !context.includePages) {\n      continue;\n    }\n\n    const methods = expandMethods(route.method);\n    const label = `${String(route.method).toUpperCase()} ${route.path}`;\n    const warn = (message: string) => warnings.push(`${label}: ${message}`);\n\n    if (methods.length === 0) {\n      warn(`unsupported method \"${String(route.method)}\", route skipped.`);\n\n      continue;\n    }\n\n    const handler = route.handler as OpenApiRouteInput[\"handler\"] | undefined;\n    const validation = resolveRouteValidation(route);\n    const auth = readRouteAuth(route.middleware, warn);\n    const tag = firstSegmentTag(route.path);\n    const pathKey = toOpenApiPath(route.path);\n\n    if (validation?.validate) {\n      warn(\"validation.validate is custom middleware and is not documented.\");\n    }\n\n    for (const method of methods) {\n      paths[pathKey] ??= {};\n\n      if (paths[pathKey][method]) {\n        warn(\n          `${method.toUpperCase()} ${pathKey} is already documented by an earlier route; this one is skipped.`,\n        );\n\n        continue;\n      }\n\n      let operationId = buildOperationId(route.name, method, route.path, methods.length > 1);\n\n      if (operationIds.has(operationId)) {\n        let suffix = 2;\n\n        while (operationIds.has(`${operationId}_${suffix}`)) {\n          suffix++;\n        }\n\n        warn(\n          `operationId \"${operationId}\" is already used; renamed to \"${operationId}_${suffix}\".`,\n        );\n        operationId = `${operationId}_${suffix}`;\n      }\n\n      operationIds.add(operationId);\n\n      const description = [\n        route.description ?? handler?.description,\n        ...(auth ? describeAuth(auth, method) : []),\n      ].filter((line): line is string => typeof line === \"string\" && line.length > 0);\n\n      const request = buildRequestParts({ method, path: route.path, validation, warn });\n\n      const declared: Record<string, OpenApiResponse> = route.isPage\n        ? {\n            \"200\": {\n              description: \"HTML page\",\n              content: { \"text/html\": { schema: { type: \"string\" } } },\n            },\n          }\n        : buildDeclaredResponses(handler?.responseSchema, registry, warn);\n      const responses: Record<string, OpenApiResponse> = { ...declared };\n\n      if (!Object.keys(responses).some((status) => status.startsWith(\"2\"))) {\n        responses[\"200\"] = { description: \"Successful response\" };\n      }\n\n      if (validation?.schema) {\n        const routeHook = typeof validation.onFailure === \"function\";\n        const failed =\n          routeHook || validationShape.customBody\n            ? buildCustomValidationFailedResponse(validationShape, declared, routeHook, warn)\n            : buildValidationFailedResponse(validationShape, registry);\n\n        if (failed) {\n          responses[failed.status] ??= failed.response;\n        }\n      }\n\n      if (auth) {\n        responses[\"401\"] ??= buildUnauthorizedResponse(registry);\n      }\n\n      if (tag) {\n        tags.add(tag);\n      }\n\n      // Built in reading order: identity, prose, inputs, outputs, security.\n      const operation: OpenApiOperation = {\n        operationId,\n        ...(route.label ? { summary: route.label } : {}),\n        ...(description.length > 0 ? { description: description.join(\"\\n\\n\") } : {}),\n        ...(tag ? { tags: [tag] } : {}),\n        ...(request.parameters.length > 0 ? { parameters: request.parameters } : {}),\n        ...(request.requestBody ? { requestBody: request.requestBody } : {}),\n        responses: sortResponses(responses),\n        ...(auth ? { security: security.requirementsFor(auth) } : {}),\n      };\n\n      paths[pathKey][method] = operation;\n    }\n  }\n\n  // Keys in reading order: header, servers, tags, paths, components.\n  const document: OpenApiDocument = {\n    openapi: \"3.1.0\",\n    jsonSchemaDialect: OPENAPI_JSON_SCHEMA_DIALECT,\n    info: { ...context.info },\n    ...(context.servers && context.servers.length > 0\n      ? { servers: context.servers.map((url) => ({ url })) }\n      : {}),\n    ...(tags.size > 0 ? { tags: [...tags].sort().map((name) => ({ name })) } : {}),\n    paths,\n  };\n\n  const hasSchemas = Object.keys(registry.schemas).length > 0;\n\n  if (hasSchemas || security.hasSchemes()) {\n    document.components = {};\n\n    if (hasSchemas) {\n      document.components.schemas = registry.schemas;\n    }\n\n    if (security.hasSchemes()) {\n      document.components.securitySchemes = security.schemes;\n    }\n  }\n\n  return { document, warnings: [...new Set(warnings)] };\n}\n\nfunction sortResponses(\n  responses: Record<string, OpenApiResponse>,\n): Record<string, OpenApiResponse> {\n  return Object.fromEntries(\n    Object.entries(responses).sort(([first], [second]) => first.localeCompare(second)),\n  );\n}\n"],"mappings":";;;;;;;;;;AA6BA,MAAa,8BAA8B;AAE3C,MAAM,iBAA2C;CAAC;CAAQ;CAAO;CAAS;AAAQ;AAElF,SAAS,aAAa,MAAsB,QAAiC;CAC3E,MAAM,QAAkB,CAAC;CAEzB,IAAI,KAAK,UAAU,SAAS,GAC1B,MAAM,KAAK,2CAA2C,KAAK,UAAU,KAAK,IAAI,EAAE,EAAE;CAKpF,IAFmB,KAAK,QAAQ,MAAM,WAAW,OAAO,WAAW,QAEtD,KAAK,eAAe,SAAS,MAAM,GAC9C,MAAM,KACJ,uHACF;CAGF,OAAO;AACT;;;;;;;;;AAUA,SAAgB,qBACd,QACA,SACoB;CACpB,MAAM,WAAqB,CAAC;CAC5B,MAAM,WAAW,IAAI,eAAe,QAAQ,sBAAsB,YAChE,SAAS,KAAK,OAAO,CACvB;CACA,MAAM,WAAW,IAAI,gBAAgB;CACrC,MAAM,kBAAkB,0BAA0B,QAAQ,kBAAkB;CAC5E,MAAM,QAAkC,CAAC;CACzC,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,+BAAe,IAAI,IAAY;CAErC,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,MAAM,UAAU,CAAC,QAAQ,cAC3B;EAGF,MAAM,UAAU,cAAc,MAAM,MAAM;EAC1C,MAAM,QAAQ,GAAG,OAAO,MAAM,MAAM,CAAC,CAAC,YAAY,EAAE,GAAG,MAAM;EAC7D,MAAM,QAAQ,YAAoB,SAAS,KAAK,GAAG,MAAM,IAAI,SAAS;EAEtE,IAAI,QAAQ,WAAW,GAAG;GACxB,KAAK,uBAAuB,OAAO,MAAM,MAAM,EAAE,kBAAkB;GAEnE;EACF;EAEA,MAAM,UAAU,MAAM;EACtB,MAAM,aAAa,uBAAuB,KAAK;EAC/C,MAAM,OAAO,cAAc,MAAM,YAAY,IAAI;EACjD,MAAM,MAAM,gBAAgB,MAAM,IAAI;EACtC,MAAM,UAAU,cAAc,MAAM,IAAI;EAExC,IAAI,YAAY,UACd,KAAK,iEAAiE;EAGxE,KAAK,MAAM,UAAU,SAAS;GAC5B,MAAM,aAAa,CAAC;GAEpB,IAAI,MAAM,QAAQ,CAAC,SAAS;IAC1B,KACE,GAAG,OAAO,YAAY,EAAE,GAAG,QAAQ,iEACrC;IAEA;GACF;GAEA,IAAI,cAAc,iBAAiB,MAAM,MAAM,QAAQ,MAAM,MAAM,QAAQ,SAAS,CAAC;GAErF,IAAI,aAAa,IAAI,WAAW,GAAG;IACjC,IAAI,SAAS;IAEb,OAAO,aAAa,IAAI,GAAG,YAAY,GAAG,QAAQ,GAChD;IAGF,KACE,gBAAgB,YAAY,iCAAiC,YAAY,GAAG,OAAO,GACrF;IACA,cAAc,GAAG,YAAY,GAAG;GAClC;GAEA,aAAa,IAAI,WAAW;GAE5B,MAAM,cAAc,CAClB,MAAM,eAAe,SAAS,aAC9B,GAAI,OAAO,aAAa,MAAM,MAAM,IAAI,CAAC,CAC3C,CAAC,CAAC,QAAQ,SAAyB,OAAO,SAAS,YAAY,KAAK,SAAS,CAAC;GAE9E,MAAM,UAAU,kBAAkB;IAAE;IAAQ,MAAM,MAAM;IAAM;IAAY;GAAK,CAAC;GAEhF,MAAM,WAA4C,MAAM,SACpD,EACE,OAAO;IACL,aAAa;IACb,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,SAAS,EAAE,EAAE;GACzD,EACF,IACA,uBAAuB,SAAS,gBAAgB,UAAU,IAAI;GAClE,MAAM,YAA6C,EAAE,GAAG,SAAS;GAEjE,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,WAAW,OAAO,WAAW,GAAG,CAAC,GACjE,UAAU,SAAS,EAAE,aAAa,sBAAsB;GAG1D,IAAI,YAAY,QAAQ;IACtB,MAAM,YAAY,OAAO,WAAW,cAAc;IAClD,MAAM,SACJ,aAAa,gBAAgB,aACzB,oCAAoC,iBAAiB,UAAU,WAAW,IAAI,IAC9E,8BAA8B,iBAAiB,QAAQ;IAE7D,IAAI,QACF,UAAU,OAAO,YAAY,OAAO;GAExC;GAEA,IAAI,MACF,UAAU,WAAW,0BAA0B,QAAQ;GAGzD,IAAI,KACF,KAAK,IAAI,GAAG;GAId,MAAM,YAA8B;IAClC;IACA,GAAI,MAAM,QAAQ,EAAE,SAAS,MAAM,MAAM,IAAI,CAAC;IAC9C,GAAI,YAAY,SAAS,IAAI,EAAE,aAAa,YAAY,KAAK,MAAM,EAAE,IAAI,CAAC;IAC1E,GAAI,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC;IAC7B,GAAI,QAAQ,WAAW,SAAS,IAAI,EAAE,YAAY,QAAQ,WAAW,IAAI,CAAC;IAC1E,GAAI,QAAQ,cAAc,EAAE,aAAa,QAAQ,YAAY,IAAI,CAAC;IAClE,WAAW,cAAc,SAAS;IAClC,GAAI,OAAO,EAAE,UAAU,SAAS,gBAAgB,IAAI,EAAE,IAAI,CAAC;GAC7D;GAEA,MAAM,QAAQ,CAAC,UAAU;EAC3B;CACF;CAGA,MAAM,WAA4B;EAChC,SAAS;EACT,mBAAmB;EACnB,MAAM,EAAE,GAAG,QAAQ,KAAK;EACxB,GAAI,QAAQ,WAAW,QAAQ,QAAQ,SAAS,IAC5C,EAAE,SAAS,QAAQ,QAAQ,KAAK,SAAS,EAAE,IAAI,EAAE,EAAE,IACnD,CAAC;EACL,GAAI,KAAK,OAAO,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;EAC5E;CACF;CAEA,MAAM,aAAa,OAAO,KAAK,SAAS,OAAO,CAAC,CAAC,SAAS;CAE1D,IAAI,cAAc,SAAS,WAAW,GAAG;EACvC,SAAS,aAAa,CAAC;EAEvB,IAAI,YACF,SAAS,WAAW,UAAU,SAAS;EAGzC,IAAI,SAAS,WAAW,GACtB,SAAS,WAAW,kBAAkB,SAAS;CAEnD;CAEA,OAAO;EAAE;EAAU,UAAU,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC;CAAE;AACtD;AAEA,SAAS,cACP,WACiC;CACjC,OAAO,OAAO,YACZ,OAAO,QAAQ,SAAS,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,MAAM,cAAc,MAAM,CAAC,CACnF;AACF"}

package/esm/openapi/cast-schema.mjs

@@ -85,5 +85,5 @@ function castToJsonSchema(cast) {
 }
 
 //#endregion
-export { castToJsonSchema };
+export { castToJsonSchema, makeNullable };
 //# sourceMappingURL=cast-schema.mjs.map

package/esm/openapi/development-openapi-provider.d.mts

@@ -1,9 +1,8 @@
 import { PostmanCollection, PostmanCollectionOptions } from "./postman/postman-types.mjs";
 import { OpenApiBuildResult } from "./types.mjs";
-
 //#region ../../packages/core/src/openapi/development-openapi-provider.d.ts
 type DevelopmentOpenApiProvider = () => Promise<OpenApiBuildResult>;
-type DevelopmentPostmanResult = {
+export type DevelopmentPostmanResult = {
   collection: PostmanCollection;
   warnings: string[];
 };
@@ -11,18 +10,18 @@ type DevelopmentPostmanResult = {
  * Called by the dev server at startup. The builder lives under `dev-server/`, so the
  * production entry never reaches it; this registry is the only thing the root exports.
  */
-declare function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void;
+export declare function registerDevelopmentOpenApiProvider(build: DevelopmentOpenApiProvider): void;
 /**
  * The OpenAPI document for the routes registered in this process, built by the dev
  * server's provider. Throws outside `warlock dev`, where no provider is registered.
  */
-declare function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult>;
+export declare function getDevelopmentOpenApiDocument(): Promise<OpenApiBuildResult>;
 /**
  * The Postman collection (v2.1.0) for the routes registered in this process: the development
  * OpenAPI document run through `openApiToPostmanCollection`, so both always agree. Throws
  * outside `warlock dev`, like `getDevelopmentOpenApiDocument`.
  */
-declare function getDevelopmentPostmanCollection(options?: PostmanCollectionOptions): Promise<DevelopmentPostmanResult>;
+export declare function getDevelopmentPostmanCollection(options?: PostmanCollectionOptions): Promise<DevelopmentPostmanResult>;
 //#endregion
-export { DevelopmentPostmanResult, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider };
+export {};
 //# sourceMappingURL=development-openapi-provider.d.mts.map

package/esm/openapi/development-openapi-provider.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"development-openapi-provider.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/development-openapi-provider.ts"],"mappings":";;;;KAIK,0BAAA,SAAmC,OAAO,CAAC,kBAAA;AAAA,KAEpC,wBAAA;EACV,UAAA,EAAY,iBAAiB;EAC7B,QAAA;AAAA;;AAJgE;AAElE;;iBAWgB,kCAAA,CAAmC,KAAiC,EAA1B,0BAA0B;;;;;iBAQ9D,6BAAA,IAAiC,OAAO,CAAC,kBAAA;AAjBrD;AASV;;;;AATU,iBAgCY,+BAAA,CACpB,OAAA,GAAS,wBAAA,GACR,OAAA,CAAQ,wBAAA"}
+{"version":3,"file":"development-openapi-provider.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/openapi/development-openapi-provider.ts"],"mappings":";;;KAIK,mCAAmC,QAAQ;YAEpC;EACV,YAAY;EACZ;;;;;;wBASc,mCAAmC,OAAO;;;;;wBAQpC,iCAAiC,QAAQ;;;;;;wBAezC,gCACpB,UAAS,2BACR,QAAQ"}

package/esm/openapi/error-responses.mjs

@@ -5,7 +5,9 @@ const DEFAULT_VALIDATION_RESPONSE = {
 	errors: "errors",
 	inputKey: "input",
 	inputError: "error",
-	status: 422
+	status: 422,
+	/** A global `validation.response.body` hook replaces the framework body. */
+	customBody: false
 };
 /**
 * The `validation.response` config over its documented defaults, as `Response.failedSchema`
@@ -17,6 +19,7 @@ function resolveValidationResponse(config) {
 	if (typeof config?.inputKey === "string" && config.inputKey) merged.inputKey = config.inputKey;
 	if (typeof config?.inputError === "string" && config.inputError) merged.inputError = config.inputError;
 	if (typeof config?.status === "number" && Number.isInteger(config.status)) merged.status = config.status;
+	merged.customBody = typeof config?.body === "function";
 	return merged;
 }
 /**
@@ -61,7 +64,30 @@ function buildUnauthorizedResponse(registry) {
 		content: { "application/json": { schema: ref } }
 	};
 }
+/**
+* The failed-validation response of a route whose failure body is customized, by its own
+* `validation.onFailure` or the global `validation.response.body` hook. The framework body
+* would be wrong here, so:
+*
+* - a status the handler's `responseSchema` declares documents the custom body as written;
+* - otherwise the configured failure status is documented without a body. A route hook may
+*   also change the status, so when the handler declares any 4xx entry of its own, those
+*   entries are trusted and nothing is added.
+*
+* Returns `undefined` when nothing should be added, and warns when a route hook's body is
+* left undocumented.
+*/
+function buildCustomValidationFailedResponse(shape, declared, routeHook, warn) {
+	const status = String(shape.status);
+	if (declared[status]) return;
+	if (routeHook && Object.keys(declared).some((code) => /^4\d\d$/.test(code))) return;
+	if (routeHook) warn("validation.onFailure customizes the failure response; declare its status and body in responseSchema to document it.");
+	return {
+		status,
+		response: { description: describeStatus(status) }
+	};
+}
 
 //#endregion
-export { buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse };
+export { buildCustomValidationFailedResponse, buildUnauthorizedResponse, buildValidationFailedResponse, resolveValidationResponse };
 //# sourceMappingURL=error-responses.mjs.map

package/esm/openapi/error-responses.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"error-responses.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/error-responses.ts"],"sourcesContent":["import { describeStatus } from \"./response-schemas\";\nimport type { SchemaRegistry } from \"./schema-registry\";\nimport type { OpenApiResponse, OpenApiValidationResponseConfig } from \"./types\";\n\nconst DEFAULT_VALIDATION_RESPONSE = {\n  errors: \"errors\",\n  inputKey: \"input\",\n  inputError: \"error\",\n  status: 422,\n};\n\nexport type ValidationResponseShape = typeof DEFAULT_VALIDATION_RESPONSE;\n\n/**\n * The `validation.response` config over its documented defaults, as `Response.failedSchema`\n * reads it.\n */\nexport function resolveValidationResponse(\n  config: OpenApiValidationResponseConfig | undefined,\n): ValidationResponseShape {\n  const merged = { ...DEFAULT_VALIDATION_RESPONSE };\n\n  if (typeof config?.errors === \"string\" && config.errors) {\n    merged.errors = config.errors;\n  }\n\n  if (typeof config?.inputKey === \"string\" && config.inputKey) {\n    merged.inputKey = config.inputKey;\n  }\n\n  if (typeof config?.inputError === \"string\" && config.inputError) {\n    merged.inputError = config.inputError;\n  }\n\n  if (typeof config?.status === \"number\" && Number.isInteger(config.status)) {\n    merged.status = config.status;\n  }\n\n  return merged;\n}\n\n/**\n * The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`\n * under the configured status. The body is a shared component, emitted once.\n */\nexport function buildValidationFailedResponse(\n  shape: ValidationResponseShape,\n  registry: SchemaRegistry,\n): { status: string; response: OpenApiResponse } {\n  const ref = registry.shared(\"ValidationFailed\", {\n    type: \"object\",\n    properties: {\n      [shape.errors]: {\n        type: \"array\",\n        items: {\n          type: \"object\",\n          properties: {\n            [shape.inputKey]: { type: \"string\" },\n            [shape.inputError]: { type: \"string\" },\n          },\n          required: [shape.inputKey, shape.inputError],\n        },\n      },\n    },\n    required: [shape.errors],\n  });\n\n  return {\n    status: String(shape.status),\n    response: {\n      description: describeStatus(\"422\"),\n      content: { \"application/json\": { schema: ref } },\n    },\n  };\n}\n\n/**\n * The 401 response of a guarded route: the conventional `{ error: string }` body.\n */\nexport function buildUnauthorizedResponse(registry: SchemaRegistry): OpenApiResponse {\n  const ref = registry.shared(\"Unauthorized\", {\n    type: \"object\",\n    properties: { error: { type: \"string\" } },\n    required: [\"error\"],\n  });\n\n  return {\n    description: describeStatus(\"401\"),\n    content: { \"application/json\": { schema: ref } },\n  };\n}\n"],"mappings":";;;AAIA,MAAM,8BAA8B;CAClC,QAAQ;CACR,UAAU;CACV,YAAY;CACZ,QAAQ;AACV;;;;;AAQA,SAAgB,0BACd,QACyB;CACzB,MAAM,SAAS,EAAE,GAAG,4BAA4B;CAEhD,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,QAC/C,OAAO,SAAS,OAAO;CAGzB,IAAI,OAAO,QAAQ,aAAa,YAAY,OAAO,UACjD,OAAO,WAAW,OAAO;CAG3B,IAAI,OAAO,QAAQ,eAAe,YAAY,OAAO,YACnD,OAAO,aAAa,OAAO;CAG7B,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,UAAU,OAAO,MAAM,GACtE,OAAO,SAAS,OAAO;CAGzB,OAAO;AACT;;;;;AAMA,SAAgB,8BACd,OACA,UAC+C;CAC/C,MAAM,MAAM,SAAS,OAAO,oBAAoB;EAC9C,MAAM;EACN,YAAY,GACT,MAAM,SAAS;GACd,MAAM;GACN,OAAO;IACL,MAAM;IACN,YAAY;MACT,MAAM,WAAW,EAAE,MAAM,SAAS;MAClC,MAAM,aAAa,EAAE,MAAM,SAAS;IACvC;IACA,UAAU,CAAC,MAAM,UAAU,MAAM,UAAU;GAC7C;EACF,EACF;EACA,UAAU,CAAC,MAAM,MAAM;CACzB,CAAC;CAED,OAAO;EACL,QAAQ,OAAO,MAAM,MAAM;EAC3B,UAAU;GACR,aAAa,eAAe,KAAK;GACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;EACjD;CACF;AACF;;;;AAKA,SAAgB,0BAA0B,UAA2C;CACnF,MAAM,MAAM,SAAS,OAAO,gBAAgB;EAC1C,MAAM;EACN,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,EAAE;EACxC,UAAU,CAAC,OAAO;CACpB,CAAC;CAED,OAAO;EACL,aAAa,eAAe,KAAK;EACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;CACjD;AACF"}
+{"version":3,"file":"error-responses.mjs","names":[],"sources":["../../../../../../../../packages/core/src/openapi/error-responses.ts"],"sourcesContent":["import { describeStatus } from \"./response-schemas\";\nimport type { SchemaRegistry } from \"./schema-registry\";\nimport type { OpenApiResponse, OpenApiValidationResponseConfig } from \"./types\";\n\nconst DEFAULT_VALIDATION_RESPONSE = {\n  errors: \"errors\",\n  inputKey: \"input\",\n  inputError: \"error\",\n  status: 422,\n  /** A global `validation.response.body` hook replaces the framework body. */\n  customBody: false,\n};\n\nexport type ValidationResponseShape = typeof DEFAULT_VALIDATION_RESPONSE;\n\n/**\n * The `validation.response` config over its documented defaults, as `Response.failedSchema`\n * reads it.\n */\nexport function resolveValidationResponse(\n  config: OpenApiValidationResponseConfig | undefined,\n): ValidationResponseShape {\n  const merged = { ...DEFAULT_VALIDATION_RESPONSE };\n\n  if (typeof config?.errors === \"string\" && config.errors) {\n    merged.errors = config.errors;\n  }\n\n  if (typeof config?.inputKey === \"string\" && config.inputKey) {\n    merged.inputKey = config.inputKey;\n  }\n\n  if (typeof config?.inputError === \"string\" && config.inputError) {\n    merged.inputError = config.inputError;\n  }\n\n  if (typeof config?.status === \"number\" && Number.isInteger(config.status)) {\n    merged.status = config.status;\n  }\n\n  merged.customBody = typeof config?.body === \"function\";\n\n  return merged;\n}\n\n/**\n * The failed-validation response: `{ [errors]: [{ [inputKey]: string, [inputError]: string }] }`\n * under the configured status. The body is a shared component, emitted once.\n */\nexport function buildValidationFailedResponse(\n  shape: ValidationResponseShape,\n  registry: SchemaRegistry,\n): { status: string; response: OpenApiResponse } {\n  const ref = registry.shared(\"ValidationFailed\", {\n    type: \"object\",\n    properties: {\n      [shape.errors]: {\n        type: \"array\",\n        items: {\n          type: \"object\",\n          properties: {\n            [shape.inputKey]: { type: \"string\" },\n            [shape.inputError]: { type: \"string\" },\n          },\n          required: [shape.inputKey, shape.inputError],\n        },\n      },\n    },\n    required: [shape.errors],\n  });\n\n  return {\n    status: String(shape.status),\n    response: {\n      description: describeStatus(\"422\"),\n      content: { \"application/json\": { schema: ref } },\n    },\n  };\n}\n\n/**\n * The 401 response of a guarded route: the conventional `{ error: string }` body.\n */\nexport function buildUnauthorizedResponse(registry: SchemaRegistry): OpenApiResponse {\n  const ref = registry.shared(\"Unauthorized\", {\n    type: \"object\",\n    properties: { error: { type: \"string\" } },\n    required: [\"error\"],\n  });\n\n  return {\n    description: describeStatus(\"401\"),\n    content: { \"application/json\": { schema: ref } },\n  };\n}\n\n/**\n * The failed-validation response of a route whose failure body is customized, by its own\n * `validation.onFailure` or the global `validation.response.body` hook. The framework body\n * would be wrong here, so:\n *\n * - a status the handler's `responseSchema` declares documents the custom body as written;\n * - otherwise the configured failure status is documented without a body. A route hook may\n *   also change the status, so when the handler declares any 4xx entry of its own, those\n *   entries are trusted and nothing is added.\n *\n * Returns `undefined` when nothing should be added, and warns when a route hook's body is\n * left undocumented.\n */\nexport function buildCustomValidationFailedResponse(\n  shape: ValidationResponseShape,\n  declared: Readonly<Record<string, OpenApiResponse>>,\n  routeHook: boolean,\n  warn: (message: string) => void,\n): { status: string; response: OpenApiResponse } | undefined {\n  const status = String(shape.status);\n\n  if (declared[status]) {\n    return undefined;\n  }\n\n  if (routeHook && Object.keys(declared).some((code) => /^4\\d\\d$/.test(code))) {\n    return undefined;\n  }\n\n  if (routeHook) {\n    warn(\n      \"validation.onFailure customizes the failure response; declare its status and body in responseSchema to document it.\",\n    );\n  }\n\n  return { status, response: { description: describeStatus(status) } };\n}\n"],"mappings":";;;AAIA,MAAM,8BAA8B;CAClC,QAAQ;CACR,UAAU;CACV,YAAY;CACZ,QAAQ;;CAER,YAAY;AACd;;;;;AAQA,SAAgB,0BACd,QACyB;CACzB,MAAM,SAAS,EAAE,GAAG,4BAA4B;CAEhD,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,QAC/C,OAAO,SAAS,OAAO;CAGzB,IAAI,OAAO,QAAQ,aAAa,YAAY,OAAO,UACjD,OAAO,WAAW,OAAO;CAG3B,IAAI,OAAO,QAAQ,eAAe,YAAY,OAAO,YACnD,OAAO,aAAa,OAAO;CAG7B,IAAI,OAAO,QAAQ,WAAW,YAAY,OAAO,UAAU,OAAO,MAAM,GACtE,OAAO,SAAS,OAAO;CAGzB,OAAO,aAAa,OAAO,QAAQ,SAAS;CAE5C,OAAO;AACT;;;;;AAMA,SAAgB,8BACd,OACA,UAC+C;CAC/C,MAAM,MAAM,SAAS,OAAO,oBAAoB;EAC9C,MAAM;EACN,YAAY,GACT,MAAM,SAAS;GACd,MAAM;GACN,OAAO;IACL,MAAM;IACN,YAAY;MACT,MAAM,WAAW,EAAE,MAAM,SAAS;MAClC,MAAM,aAAa,EAAE,MAAM,SAAS;IACvC;IACA,UAAU,CAAC,MAAM,UAAU,MAAM,UAAU;GAC7C;EACF,EACF;EACA,UAAU,CAAC,MAAM,MAAM;CACzB,CAAC;CAED,OAAO;EACL,QAAQ,OAAO,MAAM,MAAM;EAC3B,UAAU;GACR,aAAa,eAAe,KAAK;GACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;EACjD;CACF;AACF;;;;AAKA,SAAgB,0BAA0B,UAA2C;CACnF,MAAM,MAAM,SAAS,OAAO,gBAAgB;EAC1C,MAAM;EACN,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,EAAE;EACxC,UAAU,CAAC,OAAO;CACpB,CAAC;CAED,OAAO;EACL,aAAa,eAAe,KAAK;EACjC,SAAS,EAAE,oBAAoB,EAAE,QAAQ,IAAI,EAAE;CACjD;AACF;;;;;;;;;;;;;;AAeA,SAAgB,oCACd,OACA,UACA,WACA,MAC2D;CAC3D,MAAM,SAAS,OAAO,MAAM,MAAM;CAElC,IAAI,SAAS,SACX;CAGF,IAAI,aAAa,OAAO,KAAK,QAAQ,CAAC,CAAC,MAAM,SAAS,UAAU,KAAK,IAAI,CAAC,GACxE;CAGF,IAAI,WACF,KACE,qHACF;CAGF,OAAO;EAAE;EAAQ,UAAU,EAAE,aAAa,eAAe,MAAM,EAAE;CAAE;AACrE"}

package/esm/openapi/index.d.mts

@@ -3,4 +3,6 @@ import { AuthDescriptor, OpenApiBuildResult, OpenApiComponents, OpenApiContext,
 import { DevelopmentPostmanResult, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, registerDevelopmentOpenApiProvider } from "./development-openapi-provider.mjs";
 import { OPENAPI_JSON_SCHEMA_DIALECT, buildOpenApiDocument } from "./build-openapi-document.mjs";
 import { exampleFromSchema } from "./postman/example-from-schema.mjs";
-import { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection } from "./postman/openapi-to-postman-collection.mjs";
+import { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection } from "./postman/openapi-to-postman-collection.mjs";
+import "./postman/index.mjs";
+export { AuthDescriptor, DEFAULT_POSTMAN_BASE_URL, DevelopmentPostmanResult, OPENAPI_JSON_SCHEMA_DIALECT, OpenApiBuildResult, OpenApiComponents, OpenApiContext, OpenApiDocument, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, OpenApiRouteInput, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSecurityScheme, OpenApiValidationResponseConfig, POSTMAN_COLLECTION_SCHEMA, PostmanAuth, PostmanAuthEntry, PostmanBody, PostmanCollection, PostmanCollectionOptions, PostmanFolder, PostmanFormParam, PostmanHeader, PostmanItem, PostmanOriginalRequest, PostmanQueryParam, PostmanRequest, PostmanRequestItem, PostmanResponse, PostmanUrl, PostmanVariable, WarningSink, buildOpenApiDocument, exampleFromSchema, getDevelopmentOpenApiDocument, getDevelopmentPostmanCollection, openApiToPostmanCollection, registerDevelopmentOpenApiProvider };