@company-semantics/contracts 0.21.0 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "private": false,
   "repository": {
     "type": "git",

package/src/identity/README.md

@@ -0,0 +1,31 @@
+# identity/
+
+## Purpose
+
+TypeScript types and functions for user identity and display name resolution.
+
+## Invariants
+
+- Types with minimal runtime code (pure functions only, no side effects)
+- No external dependencies (contracts policy)
+- `preferredName` is assistant-facing only, not user-edited label
+- `fullName` is user-editable override of derived firstName + lastName
+- `displayName` is NEVER stored — always derived at read time via `resolveDisplayName()`
+- `resolveDisplayName()` is the ONLY approved way to determine assistant addressing
+
+## Public API
+
+### Types
+
+- `ISODateString` — ISO 8601 date-time string alias
+- `UserIdentity` — User identity with name fields and timestamps
+
+### Functions
+
+- `deriveFullName(firstName, lastName?)` — Derive full name from components
+- `resolveDisplayName(identity)` — Get display name (preferredName or firstName)
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-backend, company-semantics-app

package/src/identity/display-name.ts

@@ -0,0 +1,60 @@
+/**
+ * Display Name Functions
+ *
+ * Canonical functions for deriving and resolving user display names.
+ * These are the ONLY approved ways to handle display name logic.
+ *
+ * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ */
+
+import type { UserIdentity } from './types.js';
+
+// =============================================================================
+// Full Name Derivation
+// =============================================================================
+
+/**
+ * Derive fullName from firstName and lastName.
+ *
+ * Invariant: fullName MUST be derived automatically unless explicitly provided.
+ *
+ * @param firstName - User's first name (required)
+ * @param lastName - User's last name (optional)
+ * @returns Combined full name
+ *
+ * @example
+ * deriveFullName("Ian", "Heidt")  // "Ian Heidt"
+ * deriveFullName("Ian")           // "Ian"
+ */
+export function deriveFullName(firstName: string, lastName?: string): string {
+  return lastName ? `${firstName} ${lastName}` : firstName;
+}
+
+// =============================================================================
+// Display Name Resolution
+// =============================================================================
+
+/**
+ * Resolve the display name for assistant addressing.
+ *
+ * This is the ONLY approved way to determine how the assistant
+ * or UI should address a user.
+ *
+ * Invariants:
+ * - preferredName overrides if present and non-empty
+ * - Falls back to firstName (never blank)
+ * - displayName is NEVER stored, always derived at read time
+ *
+ * @param identity - Object with preferredName and firstName fields
+ * @returns The resolved display name
+ *
+ * @example
+ * resolveDisplayName({ firstName: "Ian", preferredName: "Heidt" })  // "Heidt"
+ * resolveDisplayName({ firstName: "Ian", preferredName: "" })       // "Ian"
+ * resolveDisplayName({ firstName: "Ian" })                          // "Ian"
+ */
+export function resolveDisplayName(
+  identity: Pick<UserIdentity, 'preferredName' | 'firstName'>
+): string {
+  return identity.preferredName?.trim() || identity.firstName;
+}

package/src/identity/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Identity Types Barrel
+ *
+ * Re-exports user identity vocabulary types and functions.
+ * Import from '@company-semantics/contracts' (root).
+ */
+
+// Types
+export type { ISODateString, UserIdentity } from './types.js';
+
+// Functions
+export { deriveFullName, resolveDisplayName } from './display-name.js';

package/src/identity/types.ts

@@ -0,0 +1,62 @@
+/**
+ * User Identity Types
+ *
+ * Canonical vocabulary for user identity across Company Semantics.
+ *
+ * @see DECISIONS.md ADR-2026-01-020 for design rationale
+ */
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/**
+ * ISO 8601 date-time string.
+ * Example: "2025-12-25T14:30:00.000Z"
+ */
+export type ISODateString = string;
+
+// =============================================================================
+// User Identity
+// =============================================================================
+
+/**
+ * User identity information.
+ * Represents the canonical identity vocabulary for a user.
+ *
+ * Invariants:
+ * - firstName is required (always addressable)
+ * - lastName is optional (single-name users exist globally)
+ * - fullName is STORED (derived by default, user-editable)
+ * - preferredName is STORED (assistant-only addressing)
+ * - displayName is NEVER stored (derived at read time via resolveDisplayName)
+ */
+export type UserIdentity = {
+  /** Unique user identifier */
+  userId: string;
+
+  /** User's first name (required) */
+  firstName: string;
+
+  /** User's last name (optional) */
+  lastName?: string;
+
+  /**
+   * Full name for display in UI, exports, and audit logs.
+   * Derived by default from firstName + lastName, but user-editable.
+   */
+  fullName: string;
+
+  /**
+   * Preferred name for AI assistant to use.
+   * Assistant-only field; may differ from firstName.
+   * If not set, assistant falls back to firstName via resolveDisplayName().
+   */
+  preferredName?: string;
+
+  /** When the identity was created */
+  createdAt: ISODateString;
+
+  /** When the identity was last updated */
+  updatedAt: ISODateString;
+};