@crombolo/server 0.0.0-stage → 0.10.0

package/src/domains.ts

@@ -0,0 +1,384 @@
+/**
+ * `domains.toml`: which hostnames reach which page, and in which culture.
+ *
+ * Hostnames are the one piece of site metadata that differs in every
+ * environment, so they are neither content nor schema. They are a file of their
+ * own at the site root — data, not code, so `crombolo domains set` can write it
+ * — with `${VAR}` read from the environment at sync time, which is how one
+ * committed file serves development, staging and production.
+ *
+ * The file is the truth. Boot converges the `domain` table onto it, so deleting
+ * an entry takes effect, exactly as `syncConfiguredRedirects` does for rules in
+ * the config. A site with no `domains.toml` is left alone entirely: nothing to
+ * converge onto means the backoffice stays the only way, as it was before.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ObjectTypes } from '@crombolo/core'
+import {
+  type Db,
+  DocumentRepository,
+  DomainRepository,
+  describeRefFailure,
+  LanguageRepository,
+  NodeRepository,
+  type NodeRow,
+  resolveNodeRef,
+} from '@crombolo/data'
+
+export const DOMAINS_FILE = 'domains.toml'
+
+/** One hostname bound to one node, as the file declares it. */
+export interface DomainDeclaration {
+  /** A content path (`/`, `/fr`) or a node uuid; resolved when the file is applied. */
+  node: string
+  /** A hostname, optionally with a port and a path, and optionally `${VAR}`. */
+  host: string
+  /** The culture this hostname serves; absent means the site's default. */
+  culture?: string
+  /** The culture the node itself falls back to, with or without a hostname. */
+  defaultCulture?: string
+}
+
+export interface DomainsFileResult {
+  declarations: DomainDeclaration[]
+  problems: string[]
+}
+
+const str = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+
+export function parseDomainsFile(source: string): DomainsFileResult {
+  const problems: string[] = []
+  let raw: Record<string, unknown>
+  try {
+    raw = Bun.TOML.parse(source) as Record<string, unknown>
+  } catch (error) {
+    return { declarations: [], problems: [`invalid TOML: ${(error as Error).message}`] }
+  }
+  const entries = Array.isArray(raw.domain) ? (raw.domain as Record<string, unknown>[]) : []
+  if (raw.domain !== undefined && entries.length === 0)
+    problems.push('`domain` must be a list of `[[domain]]` entries')
+
+  const declarations: DomainDeclaration[] = []
+  for (const [index, entry] of entries.entries()) {
+    const where = `domain[${index}]`
+    const node = str(entry.node)
+    const host = str(entry.host)
+    const culture = str(entry.culture)
+    const defaultCulture = str(entry['default-culture'])
+    if (!node) {
+      problems.push(`${where}: no \`node\``)
+      continue
+    }
+    // An entry may carry only a default culture: a node can vary by culture
+    // without a hostname of its own, which is what Umbraco's `*<id>` row means.
+    if (!host && !defaultCulture) {
+      problems.push(`${where}: needs a \`host\`, a \`default-culture\`, or both`)
+      continue
+    }
+    declarations.push({ node, host: host ?? '', culture, defaultCulture })
+  }
+  return { declarations, problems }
+}
+
+/** Model → canonical TOML, so a rewrite by the CLI reads as a hand-written file. */
+export function writeDomainsFile(declarations: readonly DomainDeclaration[]): string {
+  const quote = (value: string) => JSON.stringify(value)
+  const lines: string[] = [
+    '# Which hostnames reach which page, and in which culture.',
+    `# \`\${VAR}\` is read from the environment when this is applied, so one file`,
+    '# serves every environment. `crombolo domains` prints what is in force.',
+  ]
+  for (const declaration of declarations) {
+    lines.push('', '[[domain]]', `node = ${quote(declaration.node)}`)
+    if (declaration.host) lines.push(`host = ${quote(declaration.host)}`)
+    if (declaration.culture) lines.push(`culture = ${quote(declaration.culture)}`)
+    if (declaration.defaultCulture)
+      lines.push(`default-culture = ${quote(declaration.defaultCulture)}`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/** `${VAR}` from the environment; an unset one is reported rather than guessed. */
+export function resolvePlaceholders(
+  value: string,
+  env: Record<string, string | undefined> = Bun.env,
+): { value: string; missing: string[] } {
+  const missing: string[] = []
+  const resolved = value.replace(PLACEHOLDER, (_, name: string) => {
+    const found = env[name]
+    if (found === undefined || found === '') {
+      missing.push(name)
+      return ''
+    }
+    return found
+  })
+  return { value: resolved, missing }
+}
+
+export interface DomainsSyncReport {
+  /** No `domains.toml`: nothing was read and nothing was changed. */
+  action: 'absent' | 'applied'
+  /** Hostnames now bound, after interpolation. */
+  applied: Array<{ node: string; host: string; culture?: string }>
+  /** Bindings removed because the file no longer declares them. */
+  removed: number
+  /** Anything that stopped one entry being applied; the rest still are. */
+  problems: string[]
+}
+
+export function domainsFilePath(siteDir: string): string {
+  return join(siteDir, DOMAINS_FILE)
+}
+
+/** What `domains undo` restores: the file as it was before the last write. */
+export const DOMAINS_BACKUP_FILE = `${DOMAINS_FILE}.bak`
+
+/**
+ * Writes the file, keeping the one it replaces.
+ *
+ * A wrong hostname takes a site off the air — once a root page has one, that is
+ * the only name it answers on — so every write leaves the previous text beside
+ * it and `undoDomainsFile` puts it back. On a production node the backup is as
+ * ephemeral as the file itself, which is why the change is worth committing.
+ */
+export async function writeDomains(
+  siteDir: string,
+  declarations: readonly DomainDeclaration[],
+): Promise<{ file: string; backup: string | undefined }> {
+  const file = domainsFilePath(siteDir)
+  const backup = join(siteDir, DOMAINS_BACKUP_FILE)
+  const kept = existsSync(file) ? readFileSync(file, 'utf8') : undefined
+  if (kept !== undefined) await Bun.write(backup, kept)
+  await Bun.write(file, writeDomainsFile(declarations))
+  return { file, backup: kept === undefined ? undefined : backup }
+}
+
+/** Puts back what the last write replaced; the current file becomes the backup. */
+export async function undoDomainsFile(
+  siteDir: string,
+): Promise<{ ok: boolean; file: string; message?: string }> {
+  const file = domainsFilePath(siteDir)
+  const backup = join(siteDir, DOMAINS_BACKUP_FILE)
+  if (!existsSync(backup))
+    return { ok: false, file, message: `there is no ${DOMAINS_BACKUP_FILE} to go back to` }
+  const previous = readFileSync(backup, 'utf8')
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : undefined
+  await Bun.write(file, previous)
+  // So that undo is itself undoable, which is what somebody who has just undone
+  // the wrong thing needs.
+  await Bun.write(backup, current ?? '')
+  return { ok: true, file }
+}
+
+/**
+ * What to call a page in the file: whatever it is already called there, so a
+ * readable path written by a person stays a path, and its uuid when the file
+ * has not mentioned it before.
+ */
+export async function nodeReferenceFor(
+  db: Db,
+  declarations: readonly DomainDeclaration[],
+  node: NodeRow,
+): Promise<string> {
+  for (const name of new Set(declarations.map((declaration) => declaration.node))) {
+    const resolved = await resolveDomainNode(db, name)
+    if (resolved.ok && resolved.node.id === node.id) return name
+  }
+  return node.key
+}
+
+/**
+ * Every entry except the ones that belong to this page.
+ *
+ * Which they are is decided by resolving each entry, not by matching the text:
+ * `/` and `/Home` can be the same page, so clearing one by the name the file
+ * did not use would otherwise leave it bound.
+ */
+export async function withoutNode(
+  db: Db,
+  declarations: readonly DomainDeclaration[],
+  node: NodeRow,
+): Promise<DomainDeclaration[]> {
+  const kept: DomainDeclaration[] = []
+  for (const declaration of declarations) {
+    const owner = await resolveDomainNode(db, declaration.node)
+    if (owner.ok && owner.node.id === node.id) continue
+    kept.push(declaration)
+  }
+  return kept
+}
+
+/**
+ * Replaces one page's entries, leaving every other entry exactly as written.
+ *
+ * The file is rewritten from the model, not from the database: regenerating it
+ * wholesale would resolve `${VAR}` in other entries into whatever this machine
+ * happens to have, baking one environment's hostnames into a file that serves
+ * all of them.
+ */
+export function replaceNodeDeclarations(
+  existing: readonly DomainDeclaration[],
+  node: string,
+  hosts: ReadonlyArray<{ host: string; culture?: string }>,
+  defaultCulture?: string,
+): DomainDeclaration[] {
+  const others = existing.filter((declaration) => declaration.node !== node)
+  if (hosts.length === 0 && !defaultCulture) return others
+  if (hosts.length === 0) return [...others, { node, host: '', defaultCulture }]
+  return [
+    ...others,
+    ...hosts.map((entry, index) => ({
+      node,
+      host: entry.host,
+      culture: entry.culture,
+      defaultCulture: index === 0 ? defaultCulture : undefined,
+    })),
+  ]
+}
+
+/**
+ * The page a declaration names: a path, a uuid, or `/` for the root page.
+ *
+ * `/` is what a visitor types, and on a site with one root it is unambiguous —
+ * but a hostname binds to a *node*, so with several roots it is refused with
+ * their names rather than guessed at.
+ */
+export async function resolveDomainNode(
+  db: Db,
+  ref: string,
+): Promise<{ ok: true; node: NodeRow } | { ok: false; message: string }> {
+  if (ref.trim() === '/') {
+    const roots = (await new DocumentRepository(db).children(null, 0, 50)).items
+    const first = roots[0]
+    if (!first) return { ok: false, message: 'this site has no pages at the root' }
+    if (roots.length > 1)
+      return {
+        ok: false,
+        message: `"/" matches ${roots.length} root pages (${roots.map((r) => r.text).join(', ')}) — name one`,
+      }
+    return { ok: true, node: first }
+  }
+  const resolved = await resolveNodeRef(db, [ObjectTypes.Document], ref)
+  return resolved.ok
+    ? { ok: true, node: resolved.node }
+    : { ok: false, message: describeRefFailure(ref, resolved) }
+}
+
+export function readDomainsFile(siteDir: string): DomainsFileResult | undefined {
+  const file = domainsFilePath(siteDir)
+  return existsSync(file) ? parseDomainsFile(readFileSync(file, 'utf8')) : undefined
+}
+
+/**
+ * Converges the `domain` table onto the file.
+ *
+ * Entries are grouped by node because an assignment is replaced per node, as
+ * the backoffice's dialog replaces it: stating a node's hostnames says what
+ * they are. Nodes the file does not name keep nothing — the file is the truth,
+ * so a binding it dropped goes — but a site with no file at all is untouched.
+ */
+export async function syncDomainsFile(
+  db: Db,
+  siteDir: string,
+  env: Record<string, string | undefined> = Bun.env,
+): Promise<DomainsSyncReport> {
+  const read = readDomainsFile(siteDir)
+  if (!read) return { action: 'absent', applied: [], removed: 0, problems: [] }
+
+  const problems = [...read.problems]
+  const applied: DomainsSyncReport['applied'] = []
+  const domains = new DomainRepository(db)
+  const nodes = new NodeRepository(db)
+  // A hostname with no culture of its own serves the site's default one, which
+  // is what the dialog means by leaving the language unset — the repository
+  // wants an actual language, so it is resolved here rather than sent empty.
+  const languages = await new LanguageRepository(db).all()
+  const defaultCulture = languages.find((language) => language.isDefault)?.isoCode ?? ''
+
+  const byNode = new Map<string, DomainDeclaration[]>()
+  for (const declaration of read.declarations) {
+    const group = byNode.get(declaration.node)
+    if (group) group.push(declaration)
+    else byNode.set(declaration.node, [declaration])
+  }
+
+  const kept = new Set<number>()
+  const namedBy = new Map<number, string>()
+  for (const [node, declarations] of byNode) {
+    const resolved = await resolveDomainNode(db, node)
+    if (!resolved.ok) {
+      problems.push(resolved.message)
+      continue
+    }
+    // `/` and `/Home` can be the same page. Each group replaces that page's
+    // whole assignment, so without this the later one silently wins and the
+    // earlier one's hostnames are gone with nothing having said so.
+    const already = namedBy.get(resolved.node.id)
+    if (already !== undefined) {
+      problems.push(`${node}: the same page as "${already}" — name it once`)
+      continue
+    }
+    namedBy.set(resolved.node.id, node)
+    const hosts: Array<{ domainName: string; isoCode: string }> = []
+    const wanted: DomainsSyncReport['applied'] = []
+    let defaultIsoCode: string | null = null
+    for (const declaration of declarations) {
+      if (declaration.defaultCulture) defaultIsoCode = declaration.defaultCulture
+      if (!declaration.host) continue
+      const host = resolvePlaceholders(declaration.host, env)
+      if (host.missing.length > 0) {
+        // Skipped rather than bound to a half-interpolated name: a hostname
+        // built from an unset variable would answer for nobody and hide the
+        // mistake. The site still starts; the problem is reported.
+        problems.push(
+          `${node}: ${declaration.host} is not applied — ${host.missing.join(', ')} ${host.missing.length === 1 ? 'is' : 'are'} not set in this environment`,
+        )
+        continue
+      }
+      hosts.push({ domainName: host.value, isoCode: declaration.culture ?? defaultCulture })
+      wanted.push({ node, host: host.value, culture: declaration.culture })
+    }
+
+    const result = await domains.setForNode(resolved.node.id, { defaultIsoCode, domains: hosts })
+    if (result.status !== 'ok') {
+      problems.push(`${node}: ${describeSetFailure(result)}`)
+      continue
+    }
+    // Only once it is in the database: reporting a binding that was refused is
+    // how a hostname that is not serving anything looks like one that is.
+    applied.push(...wanted)
+    kept.add(resolved.node.id)
+  }
+
+  // Anything bound to a node the file no longer names. `setForNode` already
+  // replaced the assignments of the nodes it does name.
+  let removed = 0
+  const nodeIds = new Set((await domains.all()).map((row) => row.nodeId))
+  for (const nodeId of nodeIds) {
+    if (kept.has(nodeId)) continue
+    const node = await nodes.byId(nodeId)
+    if (!node) continue
+    const before = await domains.forNode(nodeId)
+    await domains.setForNode(nodeId, { defaultIsoCode: null, domains: [] })
+    removed += before.domains.length + (before.defaultIsoCode ? 1 : 0)
+  }
+
+  return { action: 'applied', applied, removed, problems }
+}
+
+function describeSetFailure(result: { status: string; domainName?: string; isoCode?: string }) {
+  switch (result.status) {
+    case 'invalidLanguage':
+      return `no language "${result.isoCode}" is configured here`
+    case 'invalidName':
+      return `"${result.domainName}" is not a valid hostname`
+    case 'conflict':
+      return `"${result.domainName}" is already bound to another page`
+    default:
+      return result.status
+  }
+}

package/src/editor-types.ts

@@ -0,0 +1,108 @@
+/**
+ * The declarations the backoffice's view editor loads into monaco, so a view is
+ * checked in the editor against the same types `tsc` checks it against on disk.
+ *
+ * Nothing here is generated from the types: `@crombolo/render` ships its own
+ * sources, and those sources are what `@crombolo/crombolo` re-exports to a view, so they
+ * are served as they are and cannot drift — with React's DOM types and the CSS
+ * types under them, which the sources import for each tag's attributes. The one
+ * generated file is the schema's `content-types.d.ts`, read fresh on every
+ * request so a content type added a minute ago is already in the editor.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { intendedTypes } from './models-builder.ts'
+
+/** A file in the editor's virtual file system. `path` is a URL, not a disk path. */
+export interface EditorTypeLib {
+  path: string
+  content: string
+}
+
+/**
+ * Where `import … from '@crombolo/crombolo'` lands, by TypeScript's own directory-index
+ * lookup: no import map and no `paths` entry, because the editor's compiler
+ * options have neither a base URL nor a working directory to resolve against.
+ */
+const MODULE_DIR = 'file:///node_modules/@crombolo/crombolo'
+
+/**
+ * The generated types, at the depth they sit on disk. A view is opened under
+ * `components/`, so `../schema/content-types.d.ts` resolves in the editor exactly as
+ * it does in the site.
+ */
+export const EDITOR_CONTENT_TYPES = 'file:///schema/content-types.d.ts'
+
+/** Where the render sources' `import type … from 'react'` lands, by TypeScript's `@types` lookup. */
+const REACT_TYPES_DIR = 'file:///node_modules/@types/react'
+/** Where React's own `import … from 'csstype'` lands. */
+const CSSTYPE_DIR = 'file:///node_modules/csstype'
+
+/** The JSX modes a site may choose, by the `jsxImportSource` that selects each. */
+export const JSX_IMPORT_SOURCES = ['@crombolo/crombolo', '@crombolo/crombolo/loose'] as const
+export type JsxImportSource = (typeof JSX_IMPORT_SOURCES)[number]
+
+let cached: Promise<EditorTypeLib[]> | undefined
+
+/** `@crombolo/render`'s sources, read from the installed package, and the type packages they import. */
+function moduleLibs(): Promise<EditorTypeLib[]> {
+  cached ??= (async () => {
+    const dir = dirname(fileURLToPath(import.meta.resolve('@crombolo/render')))
+    const sources = async (folder: string) =>
+      Promise.all(
+        (await readdir(join(dir, folder)))
+          .filter((name) => name.endsWith('.ts'))
+          .sort()
+          .map(async (name) => ({
+            path: `${MODULE_DIR}/${folder ? `${folder}/` : ''}${name}`,
+            content: await readFile(join(dir, folder, name), 'utf8'),
+          })),
+      )
+    // Resolved from the render package, as its own `import type` resolves them.
+    const reactDir = dirname(
+      createRequire(join(dir, 'index.ts')).resolve('@types/react/package.json'),
+    )
+    const cssDir = dirname(
+      createRequire(join(reactDir, 'index.d.ts')).resolve('csstype/package.json'),
+    )
+    const declaration = async (from: string, name: string, to: string) => ({
+      path: `${to}/${name}`,
+      content: await readFile(join(from, name), 'utf8'),
+    })
+    return [
+      ...(await sources('')),
+      ...(await sources('loose')),
+      await declaration(reactDir, 'index.d.ts', REACT_TYPES_DIR),
+      await declaration(reactDir, 'global.d.ts', REACT_TYPES_DIR),
+      await declaration(cssDir, 'index.d.ts', CSSTYPE_DIR),
+    ]
+  })()
+  return cached
+}
+
+/**
+ * The JSX mode the site's `tsconfig.json` chooses, so the editor checks a view
+ * as `tsc` would. Read leniently, since a tsconfig may carry comments; anything
+ * other than a mode this package serves is the default.
+ */
+export function siteJsxImportSource(siteDir: string): JsxImportSource {
+  const file = join(siteDir, 'tsconfig.json')
+  if (!existsSync(file)) return '@crombolo/crombolo'
+  const found = /"jsxImportSource"\s*:\s*"([^"]+)"/.exec(readFileSync(file, 'utf8'))?.[1]
+  return (JSX_IMPORT_SOURCES as readonly string[]).includes(found ?? '')
+    ? (found as JsxImportSource)
+    : '@crombolo/crombolo'
+}
+
+export async function editorTypeLibs(options: { schemaDir: string }): Promise<EditorTypeLib[]> {
+  const libs = [...(await moduleLibs())]
+  const intended = intendedTypes(options.schemaDir)
+  // Left out rather than stubbed when the schema does not generate: a view that
+  // imports it then says the file is missing, which is true, instead of being
+  // checked against types that silently have nothing in them.
+  if ('types' in intended) libs.push({ path: EDITOR_CONTENT_TYPES, content: intended.types })
+  return libs
+}

package/src/email-http.ts

@@ -0,0 +1,79 @@
+/**
+ * E-mail through an endpoint the site owns.
+ *
+ * The escape hatch, and the answer for providers whose API cannot be reached
+ * with a key alone — SES wants a SigV4 signature, and signing by hand is code
+ * that cannot be honestly verified without an AWS account. A small function in
+ * front of it, or any internal mail relay with an HTTP face, works here instead.
+ *
+ * The body is this CMS's own shape rather than any provider's, because the
+ * endpoint on the other end is being written for it:
+ *
+ *   { from, to: [{email, name}], cc, bcc, replyTo, subject, text, html,
+ *     attachments: [{filename, contentType, content}] }   // content is base64
+ *
+ * Any 2xx is a success. A JSON body with an `id` is recorded, and no body is
+ * fine.
+ */
+import {
+  assertSecureEndpoint,
+  base64,
+  type EmailAdapterOptions,
+  type EmailPort,
+  postToProvider,
+  validateMessage,
+} from './email.ts'
+
+export interface CustomEmailOptions extends EmailAdapterOptions {
+  url: string
+  /** Sent as `authorization: Bearer …` when set. */
+  apiKey?: string
+  /** Anything else the endpoint needs. */
+  headers?: Record<string, string>
+}
+
+export function customEmail(options: CustomEmailOptions): EmailPort {
+  if (!options.url) throw new Error('A custom e-mail adapter needs a URL.')
+  assertSecureEndpoint(options.url, 'custom')
+  const call = options.fetch ?? fetch
+
+  return {
+    description: `custom (${options.url})`,
+    provider: 'custom',
+
+    async send(message) {
+      const from = message.from ?? options.from
+      const invalid = validateMessage(message, from)
+      if (invalid) return { ok: false, error: invalid }
+
+      return postToProvider(
+        call,
+        options.url,
+        {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
+            ...options.headers,
+          },
+          body: JSON.stringify({
+            from,
+            to: message.to,
+            cc: message.cc,
+            bcc: message.bcc,
+            replyTo: message.replyTo,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            attachments: message.attachments?.map((attachment) => ({
+              filename: attachment.filename,
+              contentType: attachment.contentType,
+              content: base64(attachment.bytes),
+            })),
+          }),
+        },
+        (body) => (body as { id?: string }).id ?? null,
+      )
+    },
+  }
+}

package/src/email-notice.ts

@@ -0,0 +1,36 @@
+/**
+ * What a site cannot do because it has no e-mail, said once at boot.
+ *
+ * The alternative is an operator finding out when an invitation never arrives,
+ * which is the worst moment and the hardest to diagnose: nothing errored.
+ */
+import type { EmailAvailability } from './email.ts'
+
+export interface EmailNoticeLog {
+  info(message: string, properties?: Record<string, unknown>): void
+  warning(message: string, properties?: Record<string, unknown>): void
+}
+
+export function noticeAboutEmail(
+  availability: EmailAvailability,
+  log: EmailNoticeLog,
+  /** Whether anything would actually be blocked; a developer is told, not warned. */
+  options: { development?: boolean } = {},
+): void {
+  if (availability.available) {
+    log.info('E-mail is sent through {provider}.', { provider: availability.description })
+    return
+  }
+  // The console stand-in is development's expected state, and it prints every
+  // message it is given. Announcing it on each boot is noise in the one place
+  // the noise is loudest.
+  if (availability.provider === 'log') return
+  const message = 'No e-mail provider is configured, so {affected} unavailable. {hint}'
+  const properties = {
+    affected: `${availability.affects.join(', ')} ${availability.affects.length === 1 ? 'is' : 'are'}`,
+    hint: availability.reason,
+  }
+  // In development this is the expected state and not worth a warning.
+  if (options.development) log.info(message, properties)
+  else log.warning(message, properties)
+}

package/src/email-postmark.ts

@@ -0,0 +1,78 @@
+/**
+ * E-mail through Postmark's HTTPS API.
+ *
+ * Postmark separates transactional and broadcast traffic into message streams
+ * and rejects a send to the wrong one, so `messageStream` is configurable and
+ * defaults to the transactional stream every account has.
+ */
+import {
+  assertSecureEndpoint,
+  base64,
+  type EmailAdapterOptions,
+  type EmailPort,
+  formatAddress,
+  postToProvider,
+  validateMessage,
+} from './email.ts'
+
+const ENDPOINT = 'https://api.postmarkapp.com/email'
+
+export interface PostmarkOptions extends EmailAdapterOptions {
+  /** Postmark calls it a server token; it is per-server, not per-account. */
+  apiKey: string
+  messageStream?: string
+  endpoint?: string
+}
+
+export function postmarkEmail(options: PostmarkOptions): EmailPort {
+  if (!options.apiKey) throw new Error('A Postmark e-mail adapter needs a server token.')
+  const call = options.fetch ?? fetch
+  const endpoint = options.endpoint ?? ENDPOINT
+  assertSecureEndpoint(endpoint, 'Postmark')
+  const stream = options.messageStream || 'outbound'
+
+  return {
+    description: stream === 'outbound' ? 'postmark' : `postmark (${stream})`,
+    provider: 'postmark',
+
+    async send(message) {
+      const from = message.from ?? options.from
+      const invalid = validateMessage(message, from)
+      if (invalid) return { ok: false, error: invalid }
+
+      // Postmark takes recipients as one comma-separated header value, not a list.
+      const list = (addresses: typeof message.to | undefined) =>
+        addresses && addresses.length > 0 ? addresses.map(formatAddress).join(', ') : undefined
+
+      return postToProvider(
+        call,
+        endpoint,
+        {
+          method: 'POST',
+          headers: {
+            'x-postmark-server-token': options.apiKey,
+            'content-type': 'application/json',
+            accept: 'application/json',
+          },
+          body: JSON.stringify({
+            From: formatAddress(from),
+            To: list(message.to),
+            Cc: list(message.cc),
+            Bcc: list(message.bcc),
+            ReplyTo: message.replyTo ? formatAddress(message.replyTo) : undefined,
+            Subject: message.subject,
+            TextBody: message.text,
+            HtmlBody: message.html,
+            MessageStream: stream,
+            Attachments: message.attachments?.map((attachment) => ({
+              Name: attachment.filename,
+              Content: base64(attachment.bytes),
+              ContentType: attachment.contentType,
+            })),
+          }),
+        },
+        (body) => (body as { MessageID?: string }).MessageID ?? null,
+      )
+    },
+  }
+}