@company-semantics/contracts 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -112,18 +112,18 @@
     "node": "22.x"
   },
   "dependencies": {
-    "zod": "^4.2.1"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
-    "markdownlint-cli2": "^0.22.0",
+    "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.21.0",
     "typescript": "^5",
-    "vitest": "^4.1.4",
-    "yaml": "^2.8.3"
+    "vitest": "^4.1.5",
+    "yaml": "^2.8.4"
   },
   "pnpm": {
     "overrides": {

package/src/impersonation/index.ts

@@ -29,9 +29,14 @@ export {
   ImpersonationSessionResponseSchema,
   ImpersonationSessionNullableResponseSchema,
   EndImpersonationResponseSchema,
+  ImpersonationSessionWireDtoSchema,
 } from './schemas'
 
 export type {
   ImpersonationSessionResponse,
   EndImpersonationResponse,
+  ImpersonationSessionWireDtoParsed,
 } from './schemas'
+
+// Wire DTO for SSE projection (PRD-00557 F5)
+export type { ImpersonationSessionWireDto } from '../impersonation-events'

package/src/impersonation/schemas.ts

@@ -36,5 +36,24 @@ export const EndImpersonationResponseSchema = z.object({
   ok: z.literal(true),
 })
 
+/**
+ * Wire-only DTO for SSE snapshot/started events (PRD-00557 F5).
+ *
+ * .strict() rejects extraneous keys so a backend regression that leaks
+ * reason / reasonHash / ipAddress / userAgent is caught at the contract
+ * boundary, not at the network. This complements the type-level
+ * narrowing in src/impersonation-events.ts.
+ */
+export const ImpersonationSessionWireDtoSchema = z
+  .object({
+    id: z.string(),
+    targetUserId: z.string(),
+    startedAt: z.string().datetime({ offset: true }),
+    expiresAt: z.string().datetime({ offset: true }),
+    endedAt: z.string().datetime({ offset: true }).nullable(),
+  })
+  .strict()
+
 export type ImpersonationSessionResponse = z.infer<typeof ImpersonationSessionResponseSchema>
 export type EndImpersonationResponse = z.infer<typeof EndImpersonationResponseSchema>
+export type ImpersonationSessionWireDtoParsed = z.infer<typeof ImpersonationSessionWireDtoSchema>

package/src/impersonation-events.ts

@@ -7,7 +7,19 @@
  */
 
 import type { BaseEvent } from './chat/types'
-import type { ImpersonationSession } from './impersonation'
+
+/**
+ * Minimal projection of an impersonation session for over-the-wire delivery.
+ * Excludes reason, reasonHash, ipAddress, userAgent — those stay server-side
+ * (PRD-00557 F5: type-impossible wire exposure of admin-private fields).
+ */
+export interface ImpersonationSessionWireDto {
+  readonly id: string
+  readonly targetUserId: string
+  readonly startedAt: string
+  readonly expiresAt: string
+  readonly endedAt: string | null
+}
 
 /**
  * Sent as the first frame on SSE connection.
@@ -17,7 +29,7 @@ import type { ImpersonationSession } from './impersonation'
 export interface ImpersonationSessionSnapshotEvent extends BaseEvent {
   type: 'impersonation.session.snapshot'
   data: {
-    session: ImpersonationSession | null
+    session: ImpersonationSessionWireDto | null
   }
 }
 
@@ -25,7 +37,7 @@ export interface ImpersonationSessionSnapshotEvent extends BaseEvent {
 export interface ImpersonationSessionStartedEvent extends BaseEvent {
   type: 'impersonation.session.started'
   data: {
-    session: ImpersonationSession
+    session: ImpersonationSessionWireDto
   }
 }
 

package/src/org/__tests__/org-units.test.ts

@@ -78,7 +78,13 @@ describe('OrgUnitSchema', () => {
 
 describe('OrgUnitTreeNodeSchema', () => {
   it('requires depth 1..5', () => {
-    const base = { ...makeUnit(), depth: 3, hasChildren: true, memberCount: 5 };
+    const base = {
+      ...makeUnit(),
+      depth: 3,
+      hasChildren: true,
+      memberCount: 5,
+      missingAtNextLevel: null,
+    };
     expect(() => OrgUnitTreeNodeSchema.parse(base)).not.toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 0 })).toThrow();
     expect(() => OrgUnitTreeNodeSchema.parse({ ...base, depth: 6 })).toThrow();
@@ -154,7 +160,10 @@ describe('OrgLevelConfigSchema', () => {
 describe('Response schemas', () => {
   it('OrgUnitTreeResponseSchema accepts empty tree', () => {
     expect(() =>
-      OrgUnitTreeResponseSchema.parse({ nodes: [], levelConfig: [] })
+      OrgUnitTreeResponseSchema.parse({
+        nodes: [],
+        levelConfig: [],
+      })
     ).not.toThrow();
   });
 

package/src/org/index.ts

@@ -234,6 +234,7 @@ export {
   OrgLevelIconSchema,
   OrgUnitResponseSchema,
   OrgUnitTreeResponseSchema,
+  MissingAtNextLevelSchema,
   OrgUnitChildrenResponseSchema,
   OrgUnitAncestorsResponseSchema,
   OrgUnitDescendantsResponseSchema,
@@ -255,6 +256,7 @@ export type {
   OrgLevelIcon,
   OrgUnitResponse,
   OrgUnitTreeResponse,
+  MissingAtNextLevel,
   OrgUnitChildrenResponse,
   OrgUnitAncestorsResponse,
   OrgUnitDescendantsResponse,

package/src/org/schemas.ts

@@ -32,6 +32,7 @@ const WorkspaceMemberSchema = z.object({
   roleNames: z.array(z.string()),
   joinedAt: z.string(),
   lastActiveAt: z.string().nullable(),
+  primaryUnitId: z.string().uuid().nullable(),
   unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
   unitMembershipsTruncated: z.boolean(),
   inviteStatus: z.enum(['active', 'pending', 'expired']).nullable(),
@@ -712,10 +713,23 @@ export const OrgUnitSchema = z.object({
   updatedAt: z.string(),
 });
 
+/**
+ * Active users home directly at this unit who have no level-(depth+1) home
+ * assignment within its subtree. The settings UI surfaces this as a
+ * synthetic "[child level label] assignment missing" row above the
+ * children list at every level. `null` for leaf-level units (no children
+ * configured below them) where the concept is meaningless.
+ */
+export const MissingAtNextLevelSchema = z.object({
+  count: z.number().int().min(0),
+  userIds: z.array(z.string().uuid()),
+});
+
 export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   depth: z.number().int().min(1).max(5),
   hasChildren: z.boolean(),
   memberCount: z.number().int().min(0),
+  missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
 });
 
 export const OrgUnitMembershipSchema = z.object({
@@ -852,6 +866,7 @@ export type OrgLevelConfig = z.infer<typeof OrgLevelConfigSchema>;
 export type OrgLevelIcon = z.infer<typeof OrgLevelIconSchema>;
 export type OrgUnitResponse = z.infer<typeof OrgUnitResponseSchema>;
 export type OrgUnitTreeResponse = z.infer<typeof OrgUnitTreeResponseSchema>;
+export type MissingAtNextLevel = z.infer<typeof MissingAtNextLevelSchema>;
 export type OrgUnitChildrenResponse = z.infer<typeof OrgUnitChildrenResponseSchema>;
 export type OrgUnitAncestorsResponse = z.infer<typeof OrgUnitAncestorsResponseSchema>;
 export type OrgUnitDescendantsResponse = z.infer<typeof OrgUnitDescendantsResponseSchema>;

package/src/org/types.ts

@@ -125,6 +125,12 @@ export interface WorkspaceMember {
   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. */