@kernhq/module-mail 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-mail",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -16,7 +16,8 @@
     "dist",
     "migrations",
     "templates",
-    "src/client"
+    "src/client",
+    "src/contract.ts"
   ],
   "exports": {
     "./contract": {
@@ -46,6 +47,7 @@
     "@aws-sdk/client-sesv2": "^3.1116.0",
     "@kernhq/contracts": "^0.1.0",
     "@kernhq/kernel": "^0.1.0",
+    "@kernhq/sdk": "^0.1.0",
     "@orpc/contract": "^1.15.0",
     "@orpc/server": "^1.15.0",
     "drizzle-orm": "^0.45.0",

package/src/client/api.ts

@@ -0,0 +1,16 @@
+import { createModuleClient, type KernClientOptions } from '@kernhq/sdk'
+import type { ContractRouterClient } from '@orpc/contract'
+import type { MailContract } from '../contract.js'
+
+/**
+ * Typed oRPC client for `/api/mail` (see `../contract`).
+ *
+ * Mail runs as its own service because it holds provider connections and a delivery queue, but its
+ * REST surface is reached like any other module's: same origin, same session cookie, the reverse
+ * proxy routes the prefix.
+ */
+export type MailApi = ContractRouterClient<MailContract>
+
+export function createMailClient(opts: KernClientOptions): MailApi {
+  return createModuleClient<MailApi>(opts, 'mail')
+}

package/src/client/index.ts

@@ -1,29 +1,11 @@
-import { defineClientModule } from '@kernhq/kernel/client'
-import { MODULE_ID } from '@kernhq/module-mail/contract'
+export { MODULE_ID, SECRET_PLACEHOLDER } from '../contract.js'
+export { createMailClient, type MailApi } from './api.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.
+ * Mail's client surface is a typed API client and nothing else.
  *
- * 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.
+ * There is no client module here: the app composes its own (`registry.ts` registers modules defined
+ * in `app/src/lib/modules/*/client.ts`), because navigation labels have to go through the app's
+ * message catalogue and its screens are app routes. A `defineClientModule` in this package would
+ * never be registered and its `component` never rendered.
  */
-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/src/contract.ts

@@ -0,0 +1,142 @@
+import {
+  baseContract,
+  defineEvent,
+  definePermissions,
+  Email,
+  PageInput,
+  page,
+  Timestamp,
+  WorkspaceId,
+} from '@kernhq/contracts'
+import { z } from 'zod'
+
+export const MODULE_ID = 'mail'
+
+/** Value returned in place of a secret field when reading settings; sending it back keeps the stored value. */
+export const SECRET_PLACEHOLDER = '__kern_secret__'
+
+export const MailProviderKind = z.enum(['platform', 'smtp', 'mailgun', 'ses', 'postmark', 'resend'])
+export type MailProviderKind = z.infer<typeof MailProviderKind>
+
+export const MailAttachment = z
+  .object({
+    filename: z.string().min(1).max(255),
+    contentType: z.string().default('application/octet-stream'),
+    /** id of a file stored in core files (fetched at send time) */
+    fileId: z.uuid().optional(),
+    /** inline content, base64-encoded (small attachments only) */
+    base64: z.string().optional(),
+  })
+  .refine((a) => Boolean(a.fileId) !== Boolean(a.base64), {
+    message: 'exactly one of fileId or base64 is required',
+  })
+export type MailAttachment = z.infer<typeof MailAttachment>
+
+export const SendMailInput = z.object({
+  /** omitted for instance-level mail (signup verification…): the platform provider is used */
+  workspaceId: WorkspaceId.optional(),
+  to: z.array(Email).min(1).max(50),
+  cc: z.array(Email).max(50).optional(),
+  bcc: z.array(Email).max(50).optional(),
+  subject: z.string().min(1).max(500),
+  text: z.string().optional(),
+  html: z.string().optional(),
+  /** render a named MJML template with `data` instead of passing text/html */
+  template: z.object({ name: z.string(), data: z.record(z.string(), z.unknown()).default({}) }).optional(),
+  replyTo: Email.optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  attachments: z.array(MailAttachment).max(20).optional(),
+  /** free-form tags stored on the delivery (e.g. `digest`, `invite`) */
+  tags: z.array(z.string().max(64)).max(10).optional(),
+})
+export type SendMailInput = z.infer<typeof SendMailInput>
+
+export const MailDeliveryStatus = z.enum(['queued', 'sent', 'failed', 'bounced'])
+export type MailDeliveryStatus = z.infer<typeof MailDeliveryStatus>
+
+export const MailDelivery = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId.nullable(),
+  to: z.array(z.string()),
+  subject: z.string(),
+  provider: MailProviderKind,
+  template: z.string().nullable(),
+  status: MailDeliveryStatus,
+  providerMessageId: z.string().nullable(),
+  error: z.string().nullable(),
+  tags: z.array(z.string()),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+})
+export type MailDelivery = z.infer<typeof MailDelivery>
+
+export const MailSuppression = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId.nullable(),
+  email: z.string(),
+  reason: z.enum(['bounce', 'complaint', 'manual']),
+  source: z.string().nullable(),
+  createdAt: Timestamp,
+})
+export type MailSuppression = z.infer<typeof MailSuppression>
+
+const ws = z.object({ workspaceId: WorkspaceId })
+
+/**
+ * Workspace mail settings as exposed over the API. Secret fields are replaced with
+ * SECRET_PLACEHOLDER on read; sending the placeholder back keeps the stored secret.
+ * The stored shape is `core.MailProviderConfig` (contracts).
+ */
+export const mailContract = {
+  settings: {
+    get: baseContract
+      .route({ method: 'GET', path: '/settings', tags: ['mail'] })
+      .input(ws)
+      .output(z.object({ config: z.record(z.string(), z.unknown()).nullable() })),
+    set: baseContract
+      .route({ method: 'PUT', path: '/settings', tags: ['mail'] })
+      .input(ws.extend({ config: z.record(z.string(), z.unknown()).nullable() }))
+      .output(z.object({ ok: z.boolean() })),
+    test: baseContract
+      .route({ method: 'POST', path: '/settings/test', tags: ['mail'] })
+      .input(ws.extend({ to: Email }))
+      .output(z.object({ ok: z.boolean(), error: z.string().nullable() })),
+  },
+  deliveries: {
+    list: baseContract
+      .route({ method: 'GET', path: '/deliveries', tags: ['mail'] })
+      .input(ws.extend(PageInput.shape).extend({ status: MailDeliveryStatus.optional() }))
+      .output(page(MailDelivery)),
+  },
+}
+export type MailContract = typeof mailContract
+
+const deliveryEvent = z.object({
+  deliveryId: z.uuid(),
+  workspaceId: WorkspaceId.nullable(),
+  to: z.array(z.string()),
+  providerMessageId: z.string().nullable(),
+  error: z.string().nullable(),
+})
+export const mailEvents = {
+  deliverySent: defineEvent('mail.delivery.sent', deliveryEvent),
+  deliveryFailed: defineEvent('mail.delivery.failed', deliveryEvent),
+  deliveryBounced: defineEvent('mail.delivery.bounced', deliveryEvent),
+}
+
+export const mailPermissions = definePermissions([
+  {
+    key: 'mail.settings.manage',
+    label: 'Manage mail settings',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: true,
+  },
+  {
+    key: 'mail.deliveries.view',
+    label: 'View mail deliveries',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
+])

package/src/client/MailSettings.svelte

@@ -1,214 +0,0 @@
-<script lang="ts">
-import { SECRET_PLACEHOLDER } from '@kernhq/module-mail/contract'
-
-/**
- * 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>