@company-semantics/contracts 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -32,6 +32,10 @@
       "types": "./src/execution/index.ts",
       "default": "./src/execution/index.ts"
     },
+    "./email": {
+      "types": "./src/email/index.ts",
+      "default": "./src/email/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/email/README.md

@@ -0,0 +1,35 @@
+# email/
+
+## Purpose
+
+TypeScript types and registry for transactional email kinds and their metadata.
+
+## Invariants
+
+- Types only; minimal runtime code (pure functions for registry lookup)
+- No external dependencies (contracts policy)
+- `EmailKind` union MUST match keys in `EMAIL_KINDS` registry
+- `EMAIL_KINDS` is the single source of truth for subjects and rendering rules
+- OTP values MUST NEVER appear in contracts (security: logged if leaked)
+- Subjects are owned by the registry, never duplicated in templates
+- Unknown email kinds MUST be rejected at API boundaries via `isValidEmailKind()`
+
+## Public API
+
+### Types
+
+- `EmailKind` — Union of valid email kind identifiers
+- `EmailPayloads` — Type-safe payload mapping for each kind
+- `SendEmailInput<K>` — Type-safe input for sending emails
+- `EmailKindDefinition` — Full definition schema for a kind
+
+### Registry & Functions
+
+- `EMAIL_KINDS` — Registry of all email kinds
+- `getEmailKindDefinition(kind)` — Type-safe registry lookup
+- `isValidEmailKind(kind)` — Validate string is EmailKind
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-backend (email service, templates)

package/src/email/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Email Domain Barrel
+ *
+ * Re-exports email kind vocabulary types and registry.
+ * Import from '@company-semantics/contracts/email'.
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+// =============================================================================
+// Kind Types
+// =============================================================================
+
+export type { EmailKind, EmailPayloads, SendEmailInput } from './types'
+
+// =============================================================================
+// Definition Types
+// =============================================================================
+
+export type { EmailKindDefinition } from './registry'
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+export {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from './registry'

package/src/email/registry.ts

@@ -0,0 +1,105 @@
+/**
+ * Email Kind Registry
+ *
+ * Central registry of all email kinds and their definitions.
+ * This is the single source of truth for email metadata.
+ *
+ * Invariants:
+ * - Every EmailKind MUST have an entry in EMAIL_KINDS
+ * - Registry keys MUST match definition.kind
+ * - Registry is exhaustive (satisfies Record<EmailKind, ...>)
+ * - Subjects are owned here, not duplicated in templates
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+import type { EmailKind } from './types'
+
+// =============================================================================
+// Email Kind Definition
+// =============================================================================
+
+/**
+ * Complete definition for an email kind.
+ *
+ * This interface is the schema for entries in EMAIL_KINDS registry.
+ * It captures subject, rendering requirements, and domain metadata.
+ *
+ * Invariants:
+ * - kind field MUST match the registry key
+ * - subject is the authoritative source (templates import from here)
+ */
+export interface EmailKindDefinition {
+  /** The email kind this definition describes */
+  kind: EmailKind
+  /** Email subject line (single source of truth) */
+  subject: string
+  /** Whether plain text body is required */
+  plainTextRequired: boolean
+  /** Whether HTML body is supported */
+  htmlSupported: boolean
+}
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+/**
+ * EMAIL_KINDS is the authoritative registry.
+ *
+ * All subjects, rendering rules, and domain metadata are derived from here.
+ * Backend email templates MUST use this registry for subjects
+ * rather than hardcoding values.
+ *
+ * To add a new kind:
+ * 1. Add to EmailKind union in types.ts
+ * 2. Add entry to this registry
+ * 3. Add payload to EmailPayloads if needed
+ * 4. Implement template in backend
+ */
+export const EMAIL_KINDS = {
+  'auth.otp': {
+    kind: 'auth.otp',
+    subject: 'Your login code',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+  'auth.magic_link': {
+    kind: 'auth.magic_link',
+    subject: 'Your login link',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+  'org.invite': {
+    kind: 'org.invite',
+    subject: 'You have been invited to join a workspace',
+    plainTextRequired: true,
+    htmlSupported: true,
+  },
+  'security.alert': {
+    kind: 'security.alert',
+    subject: 'Security alert for your account',
+    plainTextRequired: true,
+    htmlSupported: false,
+  },
+} as const satisfies Record<EmailKind, EmailKindDefinition>
+
+// =============================================================================
+// Registry Helpers
+// =============================================================================
+
+/**
+ * Type-safe registry lookup.
+ * Returns the definition for a given email kind.
+ */
+export function getEmailKindDefinition(kind: EmailKind): EmailKindDefinition {
+  return EMAIL_KINDS[kind]
+}
+
+/**
+ * Check if a string is a valid EmailKind.
+ * Use at API boundaries to reject unknown kinds.
+ */
+export function isValidEmailKind(kind: string): kind is EmailKind {
+  return kind in EMAIL_KINDS
+}

package/src/email/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Email Domain Types
+ *
+ * Shared types for transactional email across Company Semantics codebases.
+ * Types only - no runtime code, no business logic.
+ *
+ * @see ADR-CONT-034 for design rationale
+ */
+
+// =============================================================================
+// EmailKind Union
+// =============================================================================
+
+/**
+ * EmailKind identifies the type of transactional email.
+ *
+ * Naming convention: `{domain}.{type}`
+ * - domain: auth, org, security
+ * - type: specific email variant
+ *
+ * New kinds MUST be added to:
+ * 1. This union type
+ * 2. EMAIL_KINDS registry in registry.ts
+ * 3. EmailPayloads interface (if kind has payload)
+ */
+export type EmailKind =
+  | 'auth.otp'
+  | 'auth.magic_link' // future
+  | 'org.invite' // future
+  | 'security.alert' // future
+
+// =============================================================================
+// Email Payloads
+// =============================================================================
+
+/**
+ * Type-safe payload mapping for each email kind.
+ *
+ * Each key is an EmailKind, and the value is the required payload shape.
+ * Kinds without entries here have empty payloads.
+ */
+export interface EmailPayloads {
+  'auth.otp': {
+    /** The 6-digit OTP code */
+    otp: string
+    /** How long until the code expires */
+    expiresInMinutes: number
+    /** IP address of the request (for security context) */
+    requestIp?: string
+    /** User agent of the request (for security context) */
+    userAgent?: string
+  }
+}
+
+// =============================================================================
+// Send Email Input
+// =============================================================================
+
+/**
+ * Type-safe input for sending emails.
+ *
+ * The payload type is inferred from the kind.
+ * If the kind is in EmailPayloads, that payload is required.
+ */
+export interface SendEmailInput<K extends EmailKind> {
+  /** The type of email to send */
+  kind: K
+  /** Recipient email address (will be normalized) */
+  to: string
+  /** Type-safe payload for this email kind */
+  payload: K extends keyof EmailPayloads ? EmailPayloads[K] : never
+  /** Idempotency key to prevent duplicate sends */
+  idempotencyKey: string
+}

package/src/index.ts

@@ -112,6 +112,21 @@ export { extractFirstWord, resolveDisplayName, deriveFullName } from './identity
 // Auth domain types
 export { OTPErrorCode } from './auth/index'
 
+// Email domain types
+// @see ADR-CONT-034 for design rationale
+export type {
+  EmailKind,
+  EmailPayloads,
+  SendEmailInput,
+  EmailKindDefinition,
+} from './email/index'
+
+export {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from './email/index'
+
 // Organization domain types
 // @see ADR-BE-XXX for design rationale (Personal vs Shared Organization Model)
 export type {