@company-semantics/contracts 6.6.0 → 7.1.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'c8a21126db6c' as const;
-export const SPEC_HASH_FULL = 'c8a21126db6c84f641327e778c710c41e539cd5f0a1272d077ec54f1a6e382b2' as const;
+export const SPEC_HASH = '937aecbfe6e6' as const;
+export const SPEC_HASH_FULL = '937aecbfe6e6533edabb1b83d66be83f63100e519ecf9e4531af3e8a627e122a' as const;

package/src/api/generated.ts

@@ -1972,6 +1972,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/users/{userId}/avatar": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Upload (replace) a user's avatar photo from an image file
+         * @description Accepts a multipart image upload (PNG/JPEG/WebP/HEIC) up to 5 MB. The caller must be the target user or hold org.manage_users. HEIC/HEIF is converted to JPEG and the bytes are re-hosted via the blob store. Returns the resolved avatar.
+         */
+        put: operations["uploadUserAvatar"];
+        post?: never;
+        /**
+         * Clear a user's uploaded avatar (reverts to Slack photo or initials)
+         * @description Clears an in-app uploaded avatar only (source=upload); Slack-sourced avatars are left intact. The caller must be the target user or hold org.manage_users. Returns the resolved avatar after reverting.
+         */
+        delete: operations["deleteUserAvatar"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/drive/files": {
         parameters: {
             query?: never;
@@ -2782,7 +2806,7 @@ export interface components {
             slackUserId: string | null;
             avatar: {
                 /** @enum {string} */
-                source: "slack" | "initials";
+                source: "photo" | "initials";
                 url?: string;
                 initials: string;
             };
@@ -4067,7 +4091,7 @@ export interface components {
                 userId: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 authorities: {
                     /** @enum {string} */
                     mechanism: "structural" | "delegated" | "rbac";
@@ -4078,6 +4102,7 @@ export interface components {
                     /** Format: uuid */
                     derivedFromUnitId: string;
                     derivedFromUnitName?: string;
+                    derivedFromRoot?: boolean;
                     derivedFromUserId?: string | null;
                     explanation: string;
                     derivationMetadata?: {
@@ -4093,7 +4118,7 @@ export interface components {
                 userId: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 authorities: {
                     /** @enum {string} */
                     mechanism: "structural" | "delegated" | "rbac";
@@ -4104,6 +4129,7 @@ export interface components {
                     /** Format: uuid */
                     derivedFromUnitId: string;
                     derivedFromUnitName?: string;
+                    derivedFromRoot?: boolean;
                     derivedFromUserId?: string | null;
                     explanation: string;
                     derivationMetadata?: {
@@ -4226,7 +4252,7 @@ export interface components {
                 id: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 primaryUnitId: string | null;
             }[];
             edges: {
@@ -7921,6 +7947,101 @@ export interface operations {
             };
         };
     };
+    uploadUserAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                userId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    [key: string]: unknown;
+                };
+            };
+        };
+        responses: {
+            /** @description Avatar uploaded; resolved avatar returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing or malformed multipart upload */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Caller may not change this avatar */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Target user is not a member of the caller org */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Upload exceeds the 5 MB size limit */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Unsupported image type or bytes are not a valid image */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    deleteUserAvatar: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                userId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Uploaded avatar cleared; resolved avatar returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Caller may not change this avatar */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Target user is not a member of the caller org */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listDriveFiles: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -117,6 +117,7 @@ export const openApiRoutes = {
   '/api/users/org-chart': ['GET'],
   '/api/users/org-chart/import': ['POST'],
   '/api/users/org-chart/import/{operationId}/retry': ['POST'],
+  '/api/users/{userId}/avatar': ['DELETE', 'PUT'],
   '/api/work-items/{id}': ['GET'],
   '/api/work-items/{id}/content': ['PUT'],
   '/api/work-items/{id}/title': ['PUT'],

package/src/identity/__tests__/avatar.test.ts

@@ -36,39 +36,39 @@ describe('generateInitials', () => {
 })
 
 describe('resolveAvatar', () => {
-  it('initials is always populated when source is slack (critical invariant)', () => {
-    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
-    expect(result.source).toBe('slack')
+  it('initials is always populated when source is photo (critical invariant)', () => {
+    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: 'Ian Heidt' })
+    expect(result.source).toBe('photo')
     expect(result.url).toBe('https://example.com/img.jpg')
     // INVARIANT: initials is ALWAYS populated, regardless of source.
-    // This prevents UI regressions when Slack avatars fail to load.
+    // This prevents UI regressions when the photo fails to load.
     expect(typeof result.initials).toBe('string')
     expect(result.initials).toBe('IH')
   })
 
-  it('returns initials source when no slackAvatarUrl', () => {
+  it('returns initials source when no avatarUrl', () => {
     const result = resolveAvatar({ fullName: 'Ian Heidt' } as any)
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
     expect(result.url).toBeUndefined()
   })
 
-  it('returns slack source with empty initials when fullName is empty', () => {
-    const result = resolveAvatar({ slackAvatarUrl: 'https://example.com/img.jpg', fullName: '' })
-    expect(result.source).toBe('slack')
+  it('returns photo source with empty initials when fullName is empty', () => {
+    const result = resolveAvatar({ avatarUrl: 'https://example.com/img.jpg', fullName: '' })
+    expect(result.source).toBe('photo')
     expect(result.url).toBe('https://example.com/img.jpg')
     // Empty is valid — just not undefined
     expect(result.initials).toBe('')
   })
 
-  it('returns initials source when slackAvatarUrl is explicitly undefined', () => {
-    const result = resolveAvatar({ slackAvatarUrl: undefined, fullName: 'Ian Heidt' })
+  it('returns initials source when avatarUrl is explicitly undefined', () => {
+    const result = resolveAvatar({ avatarUrl: undefined, fullName: 'Ian Heidt' })
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
   })
 
-  it('returns initials source when slackAvatarUrl is empty string (falsy)', () => {
-    const result = resolveAvatar({ slackAvatarUrl: '', fullName: 'Ian Heidt' })
+  it('returns initials source when avatarUrl is empty string (falsy)', () => {
+    const result = resolveAvatar({ avatarUrl: '', fullName: 'Ian Heidt' })
     expect(result.source).toBe('initials')
     expect(result.initials).toBe('IH')
   })

package/src/identity/avatar.ts

@@ -2,7 +2,7 @@
  * Avatar Resolution Functions
  *
  * Canonical functions for resolving user avatars.
- * Determines whether to use Slack profile photo or initials fallback.
+ * Determines whether to use a resolved profile photo or initials fallback.
  *
  * @see ADR-BE-063 for design rationale
  */
@@ -15,22 +15,22 @@ import type { UserIdentity } from './types';
 
 /**
  * Source of the resolved avatar.
- * - 'slack': Using Slack profile photo
+ * - 'photo': Using a resolved profile photo
  * - 'initials': Using generated initials (fallback)
  */
-export type AvatarSource = 'slack' | 'initials';
+export type AvatarSource = 'photo' | 'initials';
 
 /**
  * Resolved avatar for UI rendering.
  *
  * INVARIANT: initials is ALWAYS populated, regardless of source.
- * This prevents UI regressions if Slack avatar fails to load.
+ * This prevents UI regressions if the photo fails to load.
  */
 export interface ResolvedAvatar {
-  /** Source of the avatar (slack or initials) */
+  /** Source of the avatar (photo or initials) */
   source: AvatarSource;
 
-  /** Slack profile image URL (present only if source === 'slack') */
+  /** resolved photo URL (present only if source === photo) */
   url?: string;
 
   /**
@@ -85,29 +85,29 @@ export function generateInitials(fullName: string): string {
  * 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.
+ * This ensures the UI always has a fallback if the photo fails to load.
  *
- * @param identity - Object with slackAvatarUrl and fullName fields
- * @returns ResolvedAvatar with source, url (if slack), and initials
+ * @param identity - Object with avatarUrl and fullName fields
+ * @returns ResolvedAvatar with source, url (if photo), and initials
  *
  * @example
- * // Slack avatar available
- * resolveAvatar({ slackAvatarUrl: "https://...", fullName: "Ian Heidt" })
- * // { source: 'slack', url: 'https://...', initials: 'IH' }
+ * // Photo avatar available
+ * resolveAvatar({ avatarUrl: "https://...", fullName: "Ian Heidt" })
+ * // { source: 'photo', url: 'https://...', initials: 'IH' }
  *
- * // No Slack avatar (initials fallback)
+ * // No photo avatar (initials fallback)
  * resolveAvatar({ fullName: "Ian Heidt" })
  * // { source: 'initials', initials: 'IH' }
  */
 export function resolveAvatar(
-  identity: Pick<UserIdentity, 'slackAvatarUrl' | 'fullName'>
+  identity: Pick<UserIdentity, 'avatarUrl' | 'fullName'>
 ): ResolvedAvatar {
   const initials = generateInitials(identity.fullName);
 
-  if (identity.slackAvatarUrl) {
+  if (identity.avatarUrl) {
     return {
-      source: 'slack',
-      url: identity.slackAvatarUrl,
+      source: 'photo',
+      url: identity.avatarUrl,
       initials,
     };
   }

package/src/identity/people-org-chart.ts

@@ -28,7 +28,7 @@ export const PeopleOrgChartNodeSchema = z.object({
   id: z.string().uuid(),
   fullName: z.string(),
   jobTitle: z.string().nullable(),
-  slackAvatarUrl: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
   primaryUnitId: z.string().uuid().nullable(),
 });
 

package/src/identity/schemas.ts

@@ -15,7 +15,7 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 const ResolvedAvatarSchema = z.object({
-  source: z.enum(['slack', 'initials']),
+  source: z.enum(['photo', 'initials']),
   url: z.string().optional(),
   initials: z.string(),
 });

package/src/identity/types.ts

@@ -79,26 +79,46 @@ export type UserIdentity = {
   updatedAt: ISODateString;
 
   // ==========================================================================
-  // Slack Avatar Fields (ADR-BE-063)
+  // Avatar Fields (source-agnostic; see ADR-BE-063 for original Slack origin)
   // ==========================================================================
+  //
+  // The avatar model is source-agnostic: avatarUrl is the resolved profile
+  // image regardless of where it came from, avatarSource records the stored
+  // origin (if any), and avatarUpdatedAt records when it last changed. Avatar
+  // rendering depends only on avatarUrl (falling back to generated initials);
+  // avatarSource/avatarUpdatedAt are metadata for sync and audit.
 
   /**
-   * Slack user ID (set when Slack is connected and email matches).
-   * Used for efficient lookups in user_change event handling.
+   * Source-agnostic resolved profile image URL.
+   * When present, avatar resolution uses this photo (source === 'photo');
+   * otherwise it falls back to generated initials.
    */
-  slackUserId?: string;
+  avatarUrl?: string;
 
   /**
-   * Slack profile image URL (synced from Slack events).
-   * May be undefined if Slack not connected or email mismatch.
+   * Stored origin of the avatar image.
+   * Absent when there is no stored avatar (resolution falls back to initials).
+   * - 'slack': synced from a connected Slack workspace
+   * - 'upload': uploaded directly by the user
    */
-  slackAvatarUrl?: string;
+  avatarSource?: 'slack' | 'upload';
 
   /**
-   * When the Slack avatar was last synced.
+   * When the avatar was last updated (synced or uploaded).
    * Used for debugging and audit purposes.
    */
-  slackAvatarLastSyncedAt?: ISODateString;
+  avatarUpdatedAt?: ISODateString;
+
+  // ==========================================================================
+  // Slack Identity Fields (ADR-BE-063)
+  // ==========================================================================
+
+  /**
+   * Slack user ID (set when Slack is connected and email matches).
+   * Used for efficient lookups in user_change event handling.
+   * This is Slack identity, not avatar data — retained independently of avatar source.
+   */
+  slackUserId?: string;
 };
 
 // =============================================================================

package/src/org/index.ts

@@ -125,6 +125,8 @@ export {
   WorkspaceOverviewSchema,
   WorkspaceMembersResponseSchema,
   WorkspaceMemberDetailSchema,
+  WorkspaceMemberManagesEntrySchema,
+  OrgUnitDesignationSchema,
   RoleCatalogEntrySchema,
   RoleCatalogResponseSchema,
   WorkspaceAuthConfigSchema,
@@ -148,6 +150,8 @@ export type {
   WorkspaceAccessResponse,
   WorkspaceOverview as WorkspaceOverviewDto,
   WorkspaceMembersResponse,
+  WorkspaceMemberManagesEntry,
+  OrgUnitDesignation,
   WorkspaceAuthConfig as WorkspaceAuthConfigDto,
   WorkspaceAuditEvent as WorkspaceAuditEventDto,
   WorkspaceResolvePathResponse,

package/src/org/schemas.ts

@@ -25,6 +25,31 @@ const WorkspaceMemberUnitSummarySchema = z.object({
   role: z.enum(['owner', 'manager', 'member']),
 });
 
+/**
+ * Designation a member holds over a unit they manage (ADR-CTRL-112).
+ *
+ * Precedence, highest-first: whole_org > admin > leader > delegate > member.
+ * The org-wide designations (`whole_org`, `admin`) anchor to the org root
+ * unit. This vocabulary is DISPLAY-ONLY — it summarizes management reach for
+ * UI surfaces and is NEVER an authorization input (authority resolution uses
+ * the orthogonal membership/delegation axes, not this enum).
+ */
+export const OrgUnitDesignationSchema = z.enum([
+  'whole_org',
+  'admin',
+  'leader',
+  'delegate',
+  'member',
+]);
+export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
+
+export const WorkspaceMemberManagesEntrySchema = z.object({
+  unitId: z.string(),
+  unitName: z.string(),
+  designation: OrgUnitDesignationSchema,
+});
+export type WorkspaceMemberManagesEntry = z.infer<typeof WorkspaceMemberManagesEntrySchema>;
+
 const WorkspaceMemberSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -36,6 +61,7 @@ const WorkspaceMemberSchema = z.object({
   lastActiveAt: z.string().nullable(),
   primaryUnitId: z.string().uuid().nullable(),
   unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
+  manages: z.array(WorkspaceMemberManagesEntrySchema),
   unitMembershipsTruncated: z.boolean(),
   inviteStatus: z.enum(['active', 'pending', 'expired']).nullable(),
 });
@@ -867,7 +893,7 @@ export const OrgUnitOwnerSchema = z.object({
   userId: z.string().uuid(),
   fullName: z.string().min(1),
   jobTitle: z.string().nullable(),
-  slackAvatarUrl: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
   /** All authority grants this user holds for the unit. At least one entry. */
   authorities: z.array(OwnerAuthoritySchema).min(1),
 });