@company-semantics/contracts 0.40.0 → 0.41.0

package/package.json

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

package/src/identity/avatar.ts

@@ -0,0 +1,120 @@
+/**
+ * Avatar Resolution Functions
+ *
+ * Canonical functions for resolving user avatars.
+ * Determines whether to use Slack profile photo or initials fallback.
+ *
+ * @see ADR-BE-063 for design rationale
+ */
+
+import type { UserIdentity } from './types';
+import { extractFirstWord } from './display-name';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Source of the resolved avatar.
+ * - 'slack': Using Slack profile photo
+ * - 'initials': Using generated initials (fallback)
+ */
+export type AvatarSource = 'slack' | 'initials';
+
+/**
+ * Resolved avatar for UI rendering.
+ *
+ * INVARIANT: initials is ALWAYS populated, regardless of source.
+ * This prevents UI regressions if Slack avatar fails to load.
+ */
+export interface ResolvedAvatar {
+  /** Source of the avatar (slack or initials) */
+  source: AvatarSource;
+
+  /** Slack profile image URL (present only if source === 'slack') */
+  url?: string;
+
+  /**
+   * User initials for fallback display.
+   * REQUIRED - always populated to ensure graceful degradation.
+   */
+  initials: string;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Generate initials from a full name.
+ *
+ * Takes the first letter of the first word and optionally the last word.
+ * Always returns uppercase initials (1-2 characters).
+ *
+ * @param fullName - The user's full name
+ * @returns Uppercase initials (e.g., "IH" for "Ian Heidt", "M" for "Madonna")
+ *
+ * @example
+ * generateInitials("Ian Heidt")      // "IH"
+ * generateInitials("Madonna")        // "M"
+ * generateInitials("Mary Jane Doe")  // "MD"
+ * generateInitials("")               // ""
+ */
+export function generateInitials(fullName: string): string {
+  const trimmed = fullName.trim();
+  if (!trimmed) return '';
+
+  const words = trimmed.split(/\s+/);
+  const firstInitial = words[0]?.[0]?.toUpperCase() ?? '';
+
+  if (words.length === 1) {
+    return firstInitial;
+  }
+
+  const lastInitial = words[words.length - 1]?.[0]?.toUpperCase() ?? '';
+  return `${firstInitial}${lastInitial}`;
+}
+
+// =============================================================================
+// Avatar Resolution
+// =============================================================================
+
+/**
+ * Resolve avatar from user identity.
+ *
+ * This is the ONLY approved way to determine which avatar to display.
+ * Returns a ResolvedAvatar with source, optional URL, and required initials.
+ *
+ * INVARIANT: initials is ALWAYS populated, regardless of source.
+ * This ensures the UI always has a fallback if the Slack image fails to load.
+ *
+ * @param identity - Object with slackAvatarUrl and fullName fields
+ * @returns ResolvedAvatar with source, url (if slack), and initials
+ *
+ * @example
+ * // Slack avatar available
+ * resolveAvatar({ slackAvatarUrl: "https://...", fullName: "Ian Heidt" })
+ * // { source: 'slack', url: 'https://...', initials: 'IH' }
+ *
+ * // No Slack avatar (initials fallback)
+ * resolveAvatar({ fullName: "Ian Heidt" })
+ * // { source: 'initials', initials: 'IH' }
+ */
+export function resolveAvatar(
+  identity: Pick<UserIdentity, 'slackAvatarUrl' | 'fullName'>
+): ResolvedAvatar {
+  const initials = generateInitials(identity.fullName);
+
+  if (identity.slackAvatarUrl) {
+    return {
+      source: 'slack',
+      url: identity.slackAvatarUrl,
+      initials,
+    };
+  }
+
+  return {
+    source: 'initials',
+    initials,
+  };
+}

package/src/identity/index.ts

@@ -8,10 +8,16 @@
 // Types
 export type { ISODateString, NameSource, UserIdentity } from './types';
 
-// Functions
+// Functions - Display Name
 export {
   extractFirstWord,
   resolveDisplayName,
   /** @deprecated Use fullName directly */
   deriveFullName,
 } from './display-name';
+
+// Types - Avatar
+export type { AvatarSource, ResolvedAvatar } from './avatar';
+
+// Functions - Avatar
+export { generateInitials, resolveAvatar } from './avatar';

package/src/identity/types.ts

@@ -71,4 +71,26 @@ export type UserIdentity = {
 
   /** When the identity was last updated */
   updatedAt: ISODateString;
+
+  // ==========================================================================
+  // Slack Avatar Fields (ADR-BE-063)
+  // ==========================================================================
+
+  /**
+   * Slack user ID (set when Slack is connected and email matches).
+   * Used for efficient lookups in user_change event handling.
+   */
+  slackUserId?: string;
+
+  /**
+   * Slack profile image URL (synced from Slack events).
+   * May be undefined if Slack not connected or email mismatch.
+   */
+  slackAvatarUrl?: string;
+
+  /**
+   * When the Slack avatar was last synced.
+   * Used for debugging and audit purposes.
+   */
+  slackAvatarLastSyncedAt?: ISODateString;
 };