@company-semantics/contracts 7.0.0 → 7.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "7.0.0",
+  "version": "7.1.1",
   "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 = 'e20bec799e8f' as const;
-export const SPEC_HASH_FULL = 'e20bec799e8f8bd1a51fccbafa626fad0f4e001789ff8b13cda65847c32972f2' 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;
             };
@@ -3108,6 +3132,12 @@ export interface components {
                     /** @enum {string} */
                     role: "owner" | "manager" | "member";
                 }[];
+                manages: {
+                    unitId: string;
+                    unitName: string;
+                    /** @enum {string} */
+                    designation: "whole_org" | "admin" | "leader" | "delegate" | "member";
+                }[];
                 unitMembershipsTruncated: boolean;
                 inviteStatus: ("active" | "pending" | "expired") | null;
             }[];
@@ -3296,6 +3326,12 @@ export interface components {
                 /** @enum {string} */
                 role: "owner" | "manager" | "member";
             }[];
+            manages: {
+                unitId: string;
+                unitName: string;
+                /** @enum {string} */
+                designation: "whole_org" | "admin" | "leader" | "delegate" | "member";
+            }[];
             unitMembershipsTruncated: boolean;
             inviteStatus: ("active" | "pending" | "expired") | null;
             effectiveScopes: string[];
@@ -4067,7 +4103,7 @@ export interface components {
                 userId: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 authorities: {
                     /** @enum {string} */
                     mechanism: "structural" | "delegated" | "rbac";
@@ -4094,7 +4130,7 @@ export interface components {
                 userId: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 authorities: {
                     /** @enum {string} */
                     mechanism: "structural" | "delegated" | "rbac";
@@ -4228,7 +4264,7 @@ export interface components {
                 id: string;
                 fullName: string;
                 jobTitle: string | null;
-                slackAvatarUrl: string | null;
+                avatarUrl: string | null;
                 primaryUnitId: string | null;
             }[];
             edges: {
@@ -7923,6 +7959,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/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,18 +25,74 @@ 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(),
   email: z.string(),
+  /**
+   * Resolved avatar photo URL for the member, or `null`/absent when none is
+   * stored. SOURCE-AGNOSTIC: today the backend resolves this from the Slack
+   * profile photo cached on the user record, but the field name deliberately
+   * does not encode the origin so future sources (in-app upload, etc.) slot in
+   * behind the backend avatar resolver without a contract change. UI MUST fall
+   * back to initials when this is absent. Optional because it is an additive
+   * display-only enrichment (see ADR-CONTRACTS-055).
+   */
+  avatarUrl: z.string().nullable().optional(),
+  /** Free-text job title (`users.job_title`). Null when unset. */
   jobTitle: z.string().nullable(),
+  /**
+   * Display role — the member's highest org-chart standing, or `null` for a
+   * plain member with no org-chart authority. Render via `orgChartRoleLabel`.
+   */
   role: OrgChartRoleSchema.nullable(),
+  /** Raw RBAC role names (e.g. 'ceo', 'admin', 'delegate'). Superset of `role`. */
   roleNames: z.array(z.string()),
   joinedAt: z.string(),
+  /** ISO timestamp of last activity; null if never recorded. */
   lastActiveAt: z.string().nullable(),
+  /**
+   * Home org-unit (`users.primary_unit_id`). Null for org-scoped users
+   * (no level-2 home assignment). Used by the unit-detail Members table to
+   * roll up "people in this org-unit" across the subtree.
+   */
   primaryUnitId: z.string().uuid().nullable(),
+  /** OrgUnit memberships for this member, capped at a small number server-side. */
   unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
+  /**
+   * Per-unit org-chart designations the member holds where they manage
+   * (ADR-CTRL-112). Display-only summary of management reach; never an
+   * authorization input. Empty array when the member manages nothing.
+   */
+  manages: z.array(WorkspaceMemberManagesEntrySchema),
+  /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
   unitMembershipsTruncated: z.boolean(),
+  /** Invite lifecycle status. `null` for members without an invite record. */
   inviteStatus: z.enum(['active', 'pending', 'expired']).nullable(),
 });
 
@@ -52,6 +108,19 @@ export const WorkspaceMemberDetailSchema = WorkspaceMemberSchema.extend({
   recentActions: z.array(MemberRecentActionSchema),
 });
 
+/**
+ * Workspace member for the members list. Human users only (no agent actors).
+ * Canonical type — inferred from {@link WorkspaceMemberSchema} so the runtime
+ * schema is the single source of truth (no parallel hand-written interface).
+ */
+export type WorkspaceMember = z.infer<typeof WorkspaceMemberSchema>;
+
+/**
+ * Full member detail (GET /api/workspace/members/:userId and /api/me self-view).
+ * Inferred from {@link WorkspaceMemberDetailSchema}.
+ */
+export type WorkspaceMemberDetail = z.infer<typeof WorkspaceMemberDetailSchema>;
+
 export const RoleCatalogEntrySchema = z.object({
   name: z.string(),
   type: z.enum(['system', 'custom']),

package/src/org/types.ts

@@ -97,48 +97,13 @@ export interface WorkspaceMemberUnitSummary {
 export type WorkspaceMemberInviteStatus = 'active' | 'pending' | 'expired';
 
 /**
- * Workspace member for the members list.
- * Human users only (no agent actors).
+ * Workspace member types. Inferred from their Zod schemas in `./schemas`
+ * (the single source of truth) and re-exported here so existing import paths
+ * (`from '@company-semantics/contracts/org'`) stay stable. The schema carries
+ * the field-level documentation; do not reintroduce a parallel interface (it
+ * was the cause of the `manages`/`avatarUrl` drift — see ADR-CTRL-112).
  */
-export interface WorkspaceMember {
-  id: string;
-  name: string;
-  email: string;
-  /**
-   * Resolved avatar photo URL for the member, or `null`/absent when none is
-   * stored. SOURCE-AGNOSTIC: today the backend resolves this from the Slack
-   * profile photo cached on the user record, but the field name deliberately
-   * does not encode the origin so future sources (in-app upload, etc.) slot in
-   * behind the backend avatar resolver without a contract change. UI MUST fall
-   * back to initials when this is absent. Optional because it is an additive
-   * display-only enrichment (see ADR-CONTRACTS-055).
-   */
-  avatarUrl?: string | null;
-  /** Free-text job title (`users.job_title`). Null when unset. */
-  jobTitle: string | null;
-  /**
-   * Display role — the member's highest org-chart standing, or `null` for a
-   * plain member with no org-chart authority. Render via `orgChartRoleLabel`.
-   */
-  role: OrgChartRole | null;
-  /** Raw RBAC role names (e.g. 'ceo', 'admin', 'delegate'). Superset of `role`. */
-  roleNames: string[];
-  joinedAt: string;
-  /** ISO timestamp of last activity; null if never recorded. */
-  lastActiveAt: string | null;
-  /**
-   * Home org-unit (`users.primary_unit_id`). Null for org-scoped users
-   * (no level-2 home assignment). Used by the unit-detail Members table to
-   * roll up "people in this org-unit" across the subtree.
-   */
-  primaryUnitId: string | null;
-  /** OrgUnit memberships for this member, capped at a small number server-side. */
-  unitMemberships: WorkspaceMemberUnitSummary[];
-  /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
-  unitMembershipsTruncated: boolean;
-  /** Invite lifecycle status. `null` for members without an invite record. */
-  inviteStatus: WorkspaceMemberInviteStatus | null;
-}
+export type { WorkspaceMember, WorkspaceMemberDetail } from './schemas';
 
 /**
  * Recent audit action attached to a member-detail response.
@@ -151,16 +116,6 @@ export interface MemberRecentAction {
   summary: string;
 }
 
-/**
- * Full member detail, returned by GET /api/workspace/members/:userId and also
- * the shape projected from /api/me for self-view.
- */
-export interface WorkspaceMemberDetail extends WorkspaceMember {
-  /** Full resolved scope patterns — union of grants from all assigned roles. */
-  effectiveScopes: string[];
-  /** Up to N most recent audit actions attributed to this member. */
-  recentActions: MemberRecentAction[];
-}
 
 /**
  * Entry in the RBAC roles catalog (GET /api/rbac/roles).