@company-semantics/contracts 9.0.0 → 9.2.0

package/src/email/__tests__/registry.test.ts

@@ -1,121 +1,125 @@
-import { describe, it, expect } from 'vitest'
-import { EMAIL_KINDS, getEmailKindDefinition, isValidEmailKind } from '../registry.js'
+import { describe, it, expect } from "vitest";
+import {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from "../registry.js";
 
-describe('EMAIL_KINDS golden snapshot', () => {
-  it('exact values are frozen', () => {
+describe("EMAIL_KINDS golden snapshot", () => {
+  it("exact values are frozen", () => {
     expect(EMAIL_KINDS).toStrictEqual({
-      'auth.otp': {
-        kind: 'auth.otp',
-        subject: 'Your login code',
+      "auth.otp": {
+        kind: "auth.otp",
+        subject: "Your login code",
         plainTextRequired: true,
         htmlSupported: false,
       },
-      'auth.magic_link': {
-        kind: 'auth.magic_link',
-        subject: 'Your login link',
+      "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',
+      "org.invite": {
+        kind: "org.invite",
+        subject: "You have been invited to join a workspace",
         plainTextRequired: true,
         htmlSupported: true,
       },
-      'org.leadership_granted': {
-        kind: 'org.leadership_granted',
+      "org.leadership_granted": {
+        kind: "org.leadership_granted",
         subject: "You've been added to a team",
         plainTextRequired: true,
         htmlSupported: true,
       },
-      'security.alert': {
-        kind: 'security.alert',
-        subject: 'Security alert for your account',
+      "security.alert": {
+        kind: "security.alert",
+        subject: "Security alert for your account",
         plainTextRequired: true,
         htmlSupported: false,
       },
-      'chat.shared': {
-        kind: 'chat.shared',
-        subject: 'A chat has been shared with you',
+      "chat.shared": {
+        kind: "chat.shared",
+        subject: "A chat has been shared with you",
         plainTextRequired: true,
         htmlSupported: true,
       },
-    })
-  })
-})
+    });
+  });
+});
 
-describe('EMAIL_KINDS registry invariants', () => {
-  it('every registry key matches its definition.kind field', () => {
+describe("EMAIL_KINDS registry invariants", () => {
+  it("every registry key matches its definition.kind field", () => {
     for (const [key, def] of Object.entries(EMAIL_KINDS)) {
-      expect(def.kind).toBe(key)
+      expect(def.kind).toBe(key);
     }
-  })
+  });
 
-  it('all subjects are non-empty strings', () => {
+  it("all subjects are non-empty strings", () => {
     for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.subject).toBe('string')
-      expect(def.subject.length).toBeGreaterThan(0)
+      expect(typeof def.subject).toBe("string");
+      expect(def.subject.length).toBeGreaterThan(0);
     }
-  })
+  });
 
-  it('all entries have required boolean fields plainTextRequired and htmlSupported', () => {
+  it("all entries have required boolean fields plainTextRequired and htmlSupported", () => {
     for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.plainTextRequired).toBe('boolean')
-      expect(typeof def.htmlSupported).toBe('boolean')
+      expect(typeof def.plainTextRequired).toBe("boolean");
+      expect(typeof def.htmlSupported).toBe("boolean");
     }
-  })
-})
+  });
+});
 
-describe('getEmailKindDefinition', () => {
-  it('returns correct definition for auth.otp', () => {
-    const def = getEmailKindDefinition('auth.otp')
-    expect(def).toStrictEqual(EMAIL_KINDS['auth.otp'])
-  })
+describe("getEmailKindDefinition", () => {
+  it("returns correct definition for auth.otp", () => {
+    const def = getEmailKindDefinition("auth.otp");
+    expect(def).toStrictEqual(EMAIL_KINDS["auth.otp"]);
+  });
 
-  it('returns correct definition for auth.magic_link', () => {
-    const def = getEmailKindDefinition('auth.magic_link')
-    expect(def).toStrictEqual(EMAIL_KINDS['auth.magic_link'])
-  })
+  it("returns correct definition for auth.magic_link", () => {
+    const def = getEmailKindDefinition("auth.magic_link");
+    expect(def).toStrictEqual(EMAIL_KINDS["auth.magic_link"]);
+  });
 
-  it('returns correct definition for org.invite', () => {
-    const def = getEmailKindDefinition('org.invite')
-    expect(def).toStrictEqual(EMAIL_KINDS['org.invite'])
-  })
+  it("returns correct definition for org.invite", () => {
+    const def = getEmailKindDefinition("org.invite");
+    expect(def).toStrictEqual(EMAIL_KINDS["org.invite"]);
+  });
 
-  it('returns correct definition for security.alert', () => {
-    const def = getEmailKindDefinition('security.alert')
-    expect(def).toStrictEqual(EMAIL_KINDS['security.alert'])
-  })
+  it("returns correct definition for security.alert", () => {
+    const def = getEmailKindDefinition("security.alert");
+    expect(def).toStrictEqual(EMAIL_KINDS["security.alert"]);
+  });
 
-  it('returns correct definition for chat.shared', () => {
-    const def = getEmailKindDefinition('chat.shared')
-    expect(def).toStrictEqual(EMAIL_KINDS['chat.shared'])
-  })
+  it("returns correct definition for chat.shared", () => {
+    const def = getEmailKindDefinition("chat.shared");
+    expect(def).toStrictEqual(EMAIL_KINDS["chat.shared"]);
+  });
 
-  it('return value matches registry entry exactly', () => {
+  it("return value matches registry entry exactly", () => {
     for (const [key, expected] of Object.entries(EMAIL_KINDS)) {
-      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS)
-      expect(def).toBe(expected)
+      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS);
+      expect(def).toBe(expected);
     }
-  })
-})
+  });
+});
 
-describe('isValidEmailKind', () => {
-  it('returns true for all valid email kinds', () => {
+describe("isValidEmailKind", () => {
+  it("returns true for all valid email kinds", () => {
     for (const kind of Object.keys(EMAIL_KINDS)) {
-      expect(isValidEmailKind(kind)).toBe(true)
+      expect(isValidEmailKind(kind)).toBe(true);
     }
-  })
+  });
 
-  it('returns false for unknown string', () => {
-    expect(isValidEmailKind('unknown.kind')).toBe(false)
-  })
+  it("returns false for unknown string", () => {
+    expect(isValidEmailKind("unknown.kind")).toBe(false);
+  });
 
-  it('returns false for empty string', () => {
-    expect(isValidEmailKind('')).toBe(false)
-  })
+  it("returns false for empty string", () => {
+    expect(isValidEmailKind("")).toBe(false);
+  });
 
-  it('returns false for partial match', () => {
-    expect(isValidEmailKind('auth')).toBe(false)
-  })
-})
+  it("returns false for partial match", () => {
+    expect(isValidEmailKind("auth")).toBe(false);
+  });
+});

package/src/email/index.ts

@@ -11,13 +11,13 @@
 // Kind Types
 // =============================================================================
 
-export type { EmailKind, EmailPayloads, SendEmailInput } from './types'
+export type { EmailKind, EmailPayloads, SendEmailInput } from "./types";
 
 // =============================================================================
 // Definition Types
 // =============================================================================
 
-export type { EmailKindDefinition } from './registry'
+export type { EmailKindDefinition } from "./registry";
 
 // =============================================================================
 // Registry
@@ -27,4 +27,4 @@ export {
   EMAIL_KINDS,
   getEmailKindDefinition,
   isValidEmailKind,
-} from './registry'
+} from "./registry";

package/src/email/registry.ts

@@ -13,7 +13,7 @@
  * @see ADR-CONT-034 for design rationale
  */
 
-import type { EmailKind } from './types'
+import type { EmailKind } from "./types";
 
 // =============================================================================
 // Email Kind Definition
@@ -31,13 +31,13 @@ import type { EmailKind } from './types'
  */
 export interface EmailKindDefinition {
   /** The email kind this definition describes */
-  kind: EmailKind
+  kind: EmailKind;
   /** Email subject line (single source of truth) */
-  subject: string
+  subject: string;
   /** Whether plain text body is required */
-  plainTextRequired: boolean
+  plainTextRequired: boolean;
   /** Whether HTML body is supported */
-  htmlSupported: boolean
+  htmlSupported: boolean;
 }
 
 // =============================================================================
@@ -58,43 +58,43 @@ export interface EmailKindDefinition {
  * 4. Implement template in backend
  */
 export const EMAIL_KINDS = {
-  'auth.otp': {
-    kind: 'auth.otp',
-    subject: 'Your login code',
+  "auth.otp": {
+    kind: "auth.otp",
+    subject: "Your login code",
     plainTextRequired: true,
     htmlSupported: false,
   },
-  'auth.magic_link': {
-    kind: 'auth.magic_link',
-    subject: 'Your login link',
+  "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',
+  "org.invite": {
+    kind: "org.invite",
+    subject: "You have been invited to join a workspace",
     plainTextRequired: true,
     htmlSupported: true,
   },
-  'org.leadership_granted': {
-    kind: 'org.leadership_granted',
+  "org.leadership_granted": {
+    kind: "org.leadership_granted",
     subject: "You've been added to a team",
     plainTextRequired: true,
     htmlSupported: true,
   },
-  'security.alert': {
-    kind: 'security.alert',
-    subject: 'Security alert for your account',
+  "security.alert": {
+    kind: "security.alert",
+    subject: "Security alert for your account",
     plainTextRequired: true,
     htmlSupported: false,
   },
-  'chat.shared': {
-    kind: 'chat.shared',
-    subject: 'A chat has been shared with you',
+  "chat.shared": {
+    kind: "chat.shared",
+    subject: "A chat has been shared with you",
     plainTextRequired: true,
     htmlSupported: true,
   },
-} as const satisfies Record<EmailKind, EmailKindDefinition>
+} as const satisfies Record<EmailKind, EmailKindDefinition>;
 
 // =============================================================================
 // Registry Helpers
@@ -105,7 +105,7 @@ export const EMAIL_KINDS = {
  * Returns the definition for a given email kind.
  */
 export function getEmailKindDefinition(kind: EmailKind): EmailKindDefinition {
-  return EMAIL_KINDS[kind]
+  return EMAIL_KINDS[kind];
 }
 
 /**
@@ -113,5 +113,5 @@ export function getEmailKindDefinition(kind: EmailKind): EmailKindDefinition {
  * Use at API boundaries to reject unknown kinds.
  */
 export function isValidEmailKind(kind: string): kind is EmailKind {
-  return kind in EMAIL_KINDS
+  return kind in EMAIL_KINDS;
 }

package/src/email/types.ts

@@ -24,12 +24,12 @@
  * 3. EmailPayloads interface (if kind has payload)
  */
 export type EmailKind =
-  | 'auth.otp'
-  | 'auth.magic_link' // future
-  | 'org.invite' // future
-  | 'org.leadership_granted'
-  | 'security.alert' // future
-  | 'chat.shared'
+  | "auth.otp"
+  | "auth.magic_link" // future
+  | "org.invite" // future
+  | "org.leadership_granted"
+  | "security.alert" // future
+  | "chat.shared";
 
 // =============================================================================
 // Email Payloads
@@ -42,57 +42,57 @@ export type EmailKind =
  * Kinds without entries here have empty payloads.
  */
 export interface EmailPayloads {
-  'auth.otp': {
+  "auth.otp": {
     /** The 6-digit OTP code */
-    otp: string
+    otp: string;
     /** How long until the code expires */
-    expiresInMinutes: number
+    expiresInMinutes: number;
     /** IP address of the request (for security context) */
-    requestIp?: string
+    requestIp?: string;
     /** User agent of the request (for security context) */
-    userAgent?: string
-  }
-  'org.invite': {
-    inviterName: string
-    orgName: string
-    role: 'admin' | 'member'
-    acceptUrl: string
-    expiresInDays: number
-  }
-  'org.leadership_granted': {
+    userAgent?: string;
+  };
+  "org.invite": {
+    inviterName: string;
+    orgName: string;
+    role: "admin" | "member";
+    acceptUrl: string;
+    expiresInDays: number;
+  };
+  "org.leadership_granted": {
     /** Display name of the person who granted access */
-    granterName: string
+    granterName: string;
     /** Display name of the recipient (optional; falls back to a neutral greeting) */
-    recipientName?: string
+    recipientName?: string;
     /** Name of the org unit / team the access applies to */
-    unitName: string
+    unitName: string;
     /** Human-readable role label the recipient was given */
-    roleLabel: 'Leader' | 'Delegate'
+    roleLabel: "Leader" | "Delegate";
     /** Full URL to view the org unit in the app */
-    ctaUrl: string
+    ctaUrl: string;
     /** Optional message from the granter, shown in the email and recorded with the grant */
-    message?: string
-  }
-  'security.alert': {
+    message?: string;
+  };
+  "security.alert": {
     /** Type of security alert */
-    alertType: 'excessive_otp_requests' | 'unusual_login_location'
+    alertType: "excessive_otp_requests" | "unusual_login_location";
     /** Human-readable details about the alert */
-    details: string
+    details: string;
     /** ISO timestamp of when the alert was triggered */
-    timestamp: string
-  }
-  'chat.shared': {
+    timestamp: string;
+  };
+  "chat.shared": {
     /** Display name of the person who shared */
-    sharedByName: string
+    sharedByName: string;
     /** Title of the chat being shared */
-    chatTitle: string
+    chatTitle: string;
     /** Full URL to view the shared chat */
-    shareUrl: string
+    shareUrl: string;
     /** Share visibility mode */
-    visibility: 'private' | 'public'
+    visibility: "private" | "public";
     /** First ~200 chars of chat content for email preview. Generated server-side from snapshot. */
-    previewText?: string
-  }
+    previewText?: string;
+  };
 }
 
 // =============================================================================
@@ -107,11 +107,11 @@ export interface EmailPayloads {
  */
 export interface SendEmailInput<K extends EmailKind> {
   /** The type of email to send */
-  kind: K
+  kind: K;
   /** Recipient email address (will be normalized) */
-  to: string
+  to: string;
   /** Type-safe payload for this email kind */
-  payload: K extends keyof EmailPayloads ? EmailPayloads[K] : never
+  payload: K extends keyof EmailPayloads ? EmailPayloads[K] : never;
   /** Idempotency key to prevent duplicate sends */
-  idempotencyKey: string
+  idempotencyKey: string;
 }

package/src/errors/index.ts

@@ -10,28 +10,28 @@
 /** Field-level validation detail for VALIDATION_ERROR responses. */
 export interface ValidationDetail {
   /** Field path (e.g. 'email', 'settings.name'). */
-  field: string
+  field: string;
   /** Human-readable error message for this field. */
-  message: string
+  message: string;
   /** Machine-readable sub-code (e.g. 'too_short', 'invalid_format') for frontend logic. */
-  code?: string
+  code?: string;
 }
 
 /** Canonical error response shape returned by all API surfaces. */
 export interface ErrorResponse {
   /** Domain-specific error code (e.g. INVITE_EXPIRED, SSO_REQUIRED). */
-  error: string
+  error: string;
   /** HTTP status code — lives in payload for transport portability across HTTP, streaming, agents, execution system. */
-  status: number
+  status: number;
   /** Optional human-readable message — safe default applied by handler when absent. */
-  message?: string
+  message?: string;
   /** Validation field-level details — only present for VALIDATION_ERROR. */
-  details?: ValidationDetail[]
+  details?: ValidationDetail[];
   /**
    * Structured extension fields (e.g. ssoUrl, orgId).
    *
    * Conventions: camelCase keys, domain-scoped, shallow values,
    * serializable, stable keys, no duplication of top-level fields.
    */
-  meta?: Record<string, unknown>
+  meta?: Record<string, unknown>;
 }

package/src/execution/__tests__/events.test.ts

@@ -1,55 +1,55 @@
-import { describe, it, expect } from 'vitest'
-import { EXECUTION_EVENT_TYPES, isExecutionEventType } from '../events.js'
+import { describe, it, expect } from "vitest";
+import { EXECUTION_EVENT_TYPES, isExecutionEventType } from "../events.js";
 
-describe('EXECUTION_EVENT_TYPES', () => {
-  it('contains exactly 10 entries', () => {
-    expect(EXECUTION_EVENT_TYPES).toHaveLength(10)
-  })
+describe("EXECUTION_EVENT_TYPES", () => {
+  it("contains exactly 10 entries", () => {
+    expect(EXECUTION_EVENT_TYPES).toHaveLength(10);
+  });
 
-  it('contains all expected event types', () => {
+  it("contains all expected event types", () => {
     const expected = [
-      'execution_created',
-      'execution_started',
-      'confirmation_approved',
-      'confirmation_rejected',
-      'confirmation_expired',
-      'approval_requested',
-      'execution_completed',
-      'execution_failed',
-      'undo_completed',
-      'cancelled',
-    ]
+      "execution_created",
+      "execution_started",
+      "confirmation_approved",
+      "confirmation_rejected",
+      "confirmation_expired",
+      "approval_requested",
+      "execution_completed",
+      "execution_failed",
+      "undo_completed",
+      "cancelled",
+    ];
     for (const evt of expected) {
-      expect(EXECUTION_EVENT_TYPES).toContain(evt)
+      expect(EXECUTION_EVENT_TYPES).toContain(evt);
     }
-  })
+  });
 
-  it('has no duplicates', () => {
-    const unique = new Set(EXECUTION_EVENT_TYPES)
-    expect(unique.size).toBe(EXECUTION_EVENT_TYPES.length)
-  })
-})
+  it("has no duplicates", () => {
+    const unique = new Set(EXECUTION_EVENT_TYPES);
+    expect(unique.size).toBe(EXECUTION_EVENT_TYPES.length);
+  });
+});
 
-describe('isExecutionEventType', () => {
-  it('returns true for every member of EXECUTION_EVENT_TYPES', () => {
+describe("isExecutionEventType", () => {
+  it("returns true for every member of EXECUTION_EVENT_TYPES", () => {
     for (const evt of EXECUTION_EVENT_TYPES) {
-      expect(isExecutionEventType(evt)).toBe(true)
+      expect(isExecutionEventType(evt)).toBe(true);
     }
-  })
+  });
 
-  it('returns false for empty string', () => {
-    expect(isExecutionEventType('')).toBe(false)
-  })
+  it("returns false for empty string", () => {
+    expect(isExecutionEventType("")).toBe(false);
+  });
 
-  it('returns false for unknown string', () => {
-    expect(isExecutionEventType('not_an_event')).toBe(false)
-  })
+  it("returns false for unknown string", () => {
+    expect(isExecutionEventType("not_an_event")).toBe(false);
+  });
 
-  it('returns false for partial match', () => {
-    expect(isExecutionEventType('execution')).toBe(false)
-  })
+  it("returns false for partial match", () => {
+    expect(isExecutionEventType("execution")).toBe(false);
+  });
 
-  it('returns false for similar but wrong string', () => {
-    expect(isExecutionEventType('execution_create')).toBe(false)
-  })
-})
+  it("returns false for similar but wrong string", () => {
+    expect(isExecutionEventType("execution_create")).toBe(false);
+  });
+});