@kernhq/module-mail 0.1.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@kernhq/module-mail",
+  "version": "0.1.0",
+  "description": "Kern mail module: outbound providers (SMTP/Mailgun/SES/Postmark/Resend), MJML templates, delivery queue, bounces & suppressions",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KernAIO/modules",
+    "directory": "packages/mail"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "templates",
+    "src/client"
+  ],
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "svelte": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./migrations": "./migrations",
+    "./templates": "./templates",
+    "./client/*": {
+      "types": "./src/client/*",
+      "svelte": "./src/client/*",
+      "default": "./src/client/*"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.1116.0",
+    "@kernhq/contracts": "^0.1.0",
+    "@kernhq/kernel": "^0.1.0",
+    "@orpc/contract": "^1.15.0",
+    "@orpc/server": "^1.15.0",
+    "drizzle-orm": "^0.45.0",
+    "eta": "^4.6.0",
+    "mjml": "^5.4.0",
+    "nodemailer": "^9.0.5",
+    "zod": "^4.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@kernhq/tsconfig": "^0.1.0",
+    "@types/mjml": "^5.0.0",
+    "@types/node": "^24.0.0",
+    "@types/nodemailer": "^8.0.1",
+    "drizzle-kit": "^0.31.0",
+    "fastify": "^5.6.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "db:generate": "drizzle-kit generate"
+  }
+}

package/src/client/MailSettings.svelte

@@ -0,0 +1,214 @@
+<script lang="ts">
+import { SECRET_PLACEHOLDER } from '../contract.js'
+
+/**
+ * Workspace email settings.
+ *
+ * A workspace can send through its own provider; without one it falls back to the instance's SMTP
+ * configuration, so a fresh self-hosted install already delivers invitations and password resets.
+ *
+ * Stored secrets are never returned by the API — reads replace them with a placeholder, and sending
+ * the placeholder back leaves the stored value untouched. That is why the fields below start out
+ * showing the placeholder rather than empty when a provider is already configured.
+ */
+interface MailApi {
+  settings: {
+    get(input: { workspaceId: string }): Promise<{ config: Record<string, unknown> | null }>
+    set(input: { workspaceId: string; config: Record<string, unknown> | null }): Promise<{ ok: boolean }>
+    test(input: { workspaceId: string; to: string }): Promise<{ ok: boolean; error: string | null }>
+  }
+}
+
+interface Props {
+  workspaceId: string
+  /** the caller passes a client bound to /api/mail */
+  api: MailApi
+  /** address the test message goes to (defaults to the signed-in user) */
+  testAddress?: string
+}
+let { workspaceId, api, testAddress = '' }: Props = $props()
+
+type Provider = 'platform' | 'smtp' | 'mailgun' | 'ses' | 'postmark' | 'resend'
+
+const FIELDS: Record<Provider, Array<{ key: string; label: string; type?: string; hint?: string }>> = {
+  platform: [],
+  smtp: [
+    { key: 'host', label: 'Host' },
+    { key: 'port', label: 'Port', type: 'number' },
+    { key: 'user', label: 'Username' },
+    { key: 'pass', label: 'Password', type: 'password' },
+    { key: 'from', label: 'From address', hint: 'Kern <no-reply@example.com>' },
+  ],
+  mailgun: [
+    { key: 'apiKey', label: 'API key', type: 'password' },
+    { key: 'domain', label: 'Domain' },
+    { key: 'region', label: 'Region', hint: 'us or eu' },
+    { key: 'from', label: 'From address' },
+  ],
+  ses: [
+    { key: 'accessKeyId', label: 'Access key ID' },
+    { key: 'secretAccessKey', label: 'Secret access key', type: 'password' },
+    { key: 'region', label: 'Region' },
+    { key: 'from', label: 'From address' },
+  ],
+  postmark: [
+    { key: 'serverToken', label: 'Server token', type: 'password' },
+    { key: 'from', label: 'From address' },
+  ],
+  resend: [
+    { key: 'apiKey', label: 'API key', type: 'password' },
+    { key: 'from', label: 'From address' },
+  ],
+}
+
+const PROVIDER_LABELS: Record<Provider, string> = {
+  platform: 'Use the instance default',
+  smtp: 'SMTP',
+  mailgun: 'Mailgun',
+  ses: 'Amazon SES',
+  postmark: 'Postmark',
+  resend: 'Resend',
+}
+
+let provider = $state<Provider>('platform')
+let values = $state<Record<string, string>>({})
+let loading = $state(true)
+let saving = $state(false)
+let testing = $state(false)
+let message = $state<{ kind: 'ok' | 'error'; text: string } | null>(null)
+let recipient = $state(testAddress)
+
+$effect(() => {
+  void (async () => {
+    const { config } = await api.settings.get({ workspaceId })
+    if (config && typeof config.provider === 'string') {
+      provider = config.provider as Provider
+      values = Object.fromEntries(
+        Object.entries(config)
+          .filter(([k]) => k !== 'provider')
+          .map(([k, v]) => [k, String(v ?? '')]),
+      )
+    }
+    loading = false
+  })()
+})
+
+const fields = $derived(FIELDS[provider])
+
+async function save(event: SubmitEvent) {
+  event.preventDefault()
+  saving = true
+  message = null
+  try {
+    const config =
+      provider === 'platform'
+        ? null
+        : { provider, ...Object.fromEntries(fields.map((f) => [f.key, values[f.key] ?? ''])) }
+    await api.settings.set({ workspaceId, config })
+    message = { kind: 'ok', text: 'Email settings saved' }
+  } catch (err) {
+    message = { kind: 'error', text: err instanceof Error ? err.message : 'Could not save settings' }
+  } finally {
+    saving = false
+  }
+}
+
+async function sendTest() {
+  if (!recipient) return
+  testing = true
+  message = null
+  try {
+    const result = await api.settings.test({ workspaceId, to: recipient })
+    message = result.ok
+      ? { kind: 'ok', text: `Test message queued for ${recipient}` }
+      : { kind: 'error', text: result.error ?? 'The provider rejected the message' }
+  } catch (err) {
+    message = { kind: 'error', text: err instanceof Error ? err.message : 'Could not send the test' }
+  } finally {
+    testing = false
+  }
+}
+</script>
+
+<section class="grid gap-4">
+  <header>
+    <h2 class="text-[15px] font-semibold text-[var(--kern-ink-900)]">Email</h2>
+    <p class="mt-1 text-[12.5px] leading-relaxed text-[var(--kern-ink-500)]">
+      Choose how this workspace sends email. Without a provider it uses the instance default.
+    </p>
+  </header>
+
+  {#if loading}
+    <p class="text-[13px] text-[var(--kern-ink-400)]">Loading…</p>
+  {:else}
+    <form class="grid gap-4" onsubmit={save}>
+      <label class="grid gap-1.5">
+        <span class="text-[12.5px] font-medium text-[var(--kern-ink-700)]">Provider</span>
+        <select
+          bind:value={provider}
+          class="h-[34px] rounded-[9px] border border-[var(--kern-border)] bg-[var(--kern-surface-input)] px-2.5 text-[13px] text-[var(--kern-ink-900)]"
+        >
+          {#each Object.entries(PROVIDER_LABELS) as [value, label] (value)}
+            <option {value}>{label}</option>
+          {/each}
+        </select>
+      </label>
+
+      {#each fields as field (field.key)}
+        <label class="grid gap-1.5">
+          <span class="text-[12.5px] font-medium text-[var(--kern-ink-700)]">{field.label}</span>
+          <input
+            type={field.type ?? 'text'}
+            bind:value={values[field.key]}
+            placeholder={field.hint ?? ''}
+            autocomplete="off"
+            class="h-[34px] rounded-[9px] border border-[var(--kern-border)] bg-[var(--kern-surface-input)] px-2.5 text-[13px] text-[var(--kern-ink-900)]"
+          />
+          {#if values[field.key] === SECRET_PLACEHOLDER}
+            <span class="text-[11.5px] text-[var(--kern-ink-400)]">
+              Stored securely — leave as is to keep it
+            </span>
+          {/if}
+        </label>
+      {/each}
+
+      {#if message}
+        <p
+          role="status"
+          class="rounded-[9px] px-3 py-2 text-[12.5px] {message.kind === 'ok'
+            ? 'bg-[var(--kern-success-tint)] text-[var(--kern-success)]'
+            : 'bg-[var(--kern-danger-tint)] text-[var(--kern-danger)]'}"
+        >
+          {message.text}
+        </p>
+      {/if}
+
+      <div class="flex items-center gap-2">
+        <button
+          type="submit"
+          disabled={saving}
+          class="h-[34px] rounded-[9px] bg-[var(--kern-ink-900)] px-3.5 text-[13px] font-medium text-[var(--kern-ink-inverse)] disabled:opacity-50"
+        >
+          {saving ? 'Saving…' : 'Save'}
+        </button>
+
+        <span class="flex-1"></span>
+
+        <input
+          type="email"
+          bind:value={recipient}
+          placeholder="you@example.com"
+          class="h-[34px] w-[220px] rounded-[9px] border border-[var(--kern-border)] bg-[var(--kern-surface-input)] px-2.5 text-[13px]"
+        />
+        <button
+          type="button"
+          onclick={sendTest}
+          disabled={testing || !recipient}
+          class="h-[34px] rounded-[9px] border border-[var(--kern-border)] px-3 text-[13px] text-[var(--kern-ink-700)] disabled:opacity-50"
+        >
+          {testing ? 'Sending…' : 'Send test'}
+        </button>
+      </div>
+    </form>
+  {/if}
+</section>

package/src/client/index.ts

@@ -0,0 +1,29 @@
+import { defineClientModule } from '@kernhq/kernel/client'
+import { MODULE_ID } from '../contract.js'
+
+/**
+ * Mail's client surface. The module has no navigation of its own — outbound email is configuration,
+ * not a place people visit — so it contributes a workspace settings page where an admin chooses the
+ * provider and sends a test message.
+ *
+ * The settings component is still to be written; the entry is registered so the module appears in
+ * the settings navigation as soon as it lands.
+ */
+export const mailClient = defineClientModule({
+  id: MODULE_ID,
+  name: 'Mail',
+  icon: 'mail',
+  settingsPages: [
+    {
+      id: 'mail',
+      label: 'Email',
+      icon: 'mail',
+      scope: 'workspace',
+      permission: 'mail.settings.manage',
+      order: 40,
+      component: () => import('./MailSettings.svelte'),
+    },
+  ],
+})
+
+export default mailClient

package/templates/_layout.mjml

@@ -0,0 +1,34 @@
+<mjml>
+  <mj-head>
+    <mj-attributes>
+      <mj-all font-family="Instrument Sans, -apple-system, Segoe UI, Helvetica, Arial, sans-serif" />
+      <mj-text color="#1C1A17" font-size="14px" line-height="1.6" />
+      <mj-button background-color="#B4661C" color="#FBFAF7" border-radius="6px" font-size="14px" font-weight="600" inner-padding="10px 22px" />
+      <mj-section padding="0" />
+    </mj-attributes>
+    <mj-style>
+      a { color: #A85A18; }
+      .muted div { color: #615B4F !important; }
+      .card { border: 1px solid #E4E0D6; border-radius: 10px; overflow: hidden; }
+    </mj-style>
+  </mj-head>
+  <mj-body background-color="#E9E6DD" width="560px">
+    <mj-section padding="28px 0 16px">
+      <mj-column>
+        <mj-text align="center" font-size="15px" font-weight="700" letter-spacing="0.08em" color="#1C1A17">
+          <%= it.__instanceName %>
+        </mj-text>
+      </mj-column>
+    </mj-section>
+    <mj-wrapper css-class="card" background-color="#FBFAF7" padding="8px 0">
+      <%~ it.__body %>
+    </mj-wrapper>
+    <mj-section padding="16px 0 28px">
+      <mj-column>
+        <mj-text css-class="muted" align="center" font-size="12px" color="#615B4F">
+          <%~ it.__footer %>
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>

package/templates/invitation.mjml

@@ -0,0 +1,16 @@
+<mj-section padding="24px 32px 8px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">You're invited to <%= it.workspaceName %></mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      <%= it.inviterName %> invited you to join the <b><%= it.workspaceName %></b> workspace on <%= it.instanceName %>.
+    </mj-text>
+  </mj-column>
+</mj-section>
+<mj-section padding="8px 32px 24px">
+  <mj-column>
+    <mj-button href="<%= it.acceptUrl %>">Accept invitation</mj-button>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F" padding-top="12px">
+      Or paste this link into your browser: <a href="<%= it.acceptUrl %>"><%= it.acceptUrl %></a>
+    </mj-text>
+  </mj-column>
+</mj-section>

package/templates/invitation.subject.txt

@@ -0,0 +1 @@
+<%= it.inviterName %> invited you to <%= it.workspaceName %> on <%= it.instanceName %>

package/templates/invitation.txt

@@ -0,0 +1,8 @@
+You're invited to <%= it.workspaceName %>
+
+<%= it.inviterName %> invited you to join the <%= it.workspaceName %> workspace on <%= it.instanceName %>.
+
+Accept the invitation:
+<%= it.acceptUrl %>
+
+If you didn't expect this invitation you can ignore this email.

package/templates/magic-link.mjml

@@ -0,0 +1,16 @@
+<mj-section padding="24px 32px 8px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">Sign in to <%= it.instanceName %></mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      Click the button below to sign in. This link is valid for a short time and can be used once.
+    </mj-text>
+  </mj-column>
+</mj-section>
+<mj-section padding="8px 32px 24px">
+  <mj-column>
+    <mj-button href="<%= it.url %>">Sign in</mj-button>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F" padding-top="12px">
+      If you didn't request this email you can safely ignore it.
+    </mj-text>
+  </mj-column>
+</mj-section>

package/templates/magic-link.subject.txt

@@ -0,0 +1 @@
+Sign in to <%= it.instanceName %>

package/templates/magic-link.txt

@@ -0,0 +1,6 @@
+Sign in to <%= it.instanceName %>
+
+Use this link to sign in (valid for a short time, single use):
+<%= it.url %>
+
+If you didn't request this email you can safely ignore it.

package/templates/notification-digest.mjml

@@ -0,0 +1,24 @@
+<mj-section padding="24px 32px 8px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">Your <%= it.periodLabel %> digest</mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      Hi <%= it.name %>, here is what happened in <b><%= it.workspaceName %></b> while you were away
+      (<%= it.items.length %> notification<%= it.items.length === 1 ? '' : 's' %>).
+    </mj-text>
+  </mj-column>
+</mj-section>
+<% it.items.forEach(function (item) { %>
+<mj-section padding="4px 32px">
+  <mj-column border-left="3px solid #B4661C" padding-left="12px">
+    <mj-text font-weight="600" padding-bottom="0"><a href="<%= item.url %>" style="color:#1C1A17;text-decoration:none;"><%= item.title %></a></mj-text>
+    <% if (item.body) { %>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F" padding-top="2px"><%= item.body %></mj-text>
+    <% } %>
+  </mj-column>
+</mj-section>
+<% }) %>
+<mj-section padding="16px 32px 24px">
+  <mj-column>
+    <mj-button href="<%= it.inboxUrl %>">Open inbox</mj-button>
+  </mj-column>
+</mj-section>

package/templates/notification-digest.subject.txt

@@ -0,0 +1 @@
+<%= it.items.length %> new notification<%= it.items.length === 1 ? '' : 's' %> in <%= it.workspaceName %>

package/templates/notification-digest.txt

@@ -0,0 +1,8 @@
+Your <%= it.periodLabel %> digest
+
+Hi <%= it.name %>, here is what happened in <%= it.workspaceName %> while you were away:
+
+<% it.items.forEach(function (item) { %>* <%= item.title %>
+  <%= item.url %>
+<% }) %>
+Open your inbox: <%= it.inboxUrl %>

package/templates/reset-password.mjml

@@ -0,0 +1,16 @@
+<mj-section padding="24px 32px 8px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">Reset your password</mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      Hi <%= it.name %>, we received a request to reset the password for your <%= it.instanceName %> account.
+    </mj-text>
+  </mj-column>
+</mj-section>
+<mj-section padding="8px 32px 24px">
+  <mj-column>
+    <mj-button href="<%= it.url %>">Choose a new password</mj-button>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F" padding-top="12px">
+      The link expires soon. If you didn't request a reset, your password is unchanged and you can ignore this email.
+    </mj-text>
+  </mj-column>
+</mj-section>

package/templates/reset-password.subject.txt

@@ -0,0 +1 @@
+Reset your <%= it.instanceName %> password

package/templates/reset-password.txt

@@ -0,0 +1,7 @@
+Reset your password
+
+Hi <%= it.name %>, we received a request to reset the password for your <%= it.instanceName %> account. Choose a new password here:
+
+<%= it.url %>
+
+The link expires soon. If you didn't request a reset, your password is unchanged and you can ignore this email.

package/templates/test.mjml

@@ -0,0 +1,12 @@
+<mj-section padding="24px 32px 24px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">Mail is working</mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      This is a test message from <b><%= it.instanceName %></b><% if (it.workspaceName) { %> for the
+      workspace <b><%= it.workspaceName %></b><% } %>, sent via the <b><%= it.provider %></b> provider.
+    </mj-text>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F">
+      If you received this email, your outbound mail configuration is correct.
+    </mj-text>
+  </mj-column>
+</mj-section>

package/templates/test.subject.txt

@@ -0,0 +1 @@
+Test email from <%= it.instanceName %>

package/templates/test.txt

@@ -0,0 +1,5 @@
+Mail is working
+
+This is a test message from <%= it.instanceName %><% if (it.workspaceName) { %> for the workspace <%= it.workspaceName %><% } %>, sent via the <%= it.provider %> provider.
+
+If you received this email, your outbound mail configuration is correct.

package/templates/verify-email.mjml

@@ -0,0 +1,17 @@
+<mj-section padding="24px 32px 8px">
+  <mj-column>
+    <mj-text font-size="18px" font-weight="600">Verify your email</mj-text>
+    <mj-text css-class="muted" color="#615B4F">
+      Hi <%= it.name %>, confirm that <%= it.email %> is your address to finish setting up your
+      <%= it.instanceName %> account.
+    </mj-text>
+  </mj-column>
+</mj-section>
+<mj-section padding="8px 32px 24px">
+  <mj-column>
+    <mj-button href="<%= it.url %>">Verify email</mj-button>
+    <mj-text css-class="muted" font-size="12px" color="#615B4F" padding-top="12px">
+      If you didn't create an account you can safely ignore this email.
+    </mj-text>
+  </mj-column>
+</mj-section>

package/templates/verify-email.subject.txt

@@ -0,0 +1 @@
+Verify your email for <%= it.instanceName %>

package/templates/verify-email.txt

@@ -0,0 +1,7 @@
+Verify your email
+
+Hi <%= it.name %>, confirm that <%= it.email %> is your address to finish setting up your <%= it.instanceName %> account:
+
+<%= it.url %>
+
+If you didn't create an account you can safely ignore this email.