@company-semantics/contracts 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.8.0",
+  "version": "1.10.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 = '6dcd4788f96e' as const;
-export const SPEC_HASH_FULL = '6dcd4788f96e0955ff7b5fcc0fa336cbaa88d3e8fced75e9f1cce650f8f8c0d7' as const;
+export const SPEC_HASH = '6984169ab437' as const;
+export const SPEC_HASH_FULL = '6984169ab4377753eff4a502240d80cc7504b083f7971a424943ae628dbb1fea' as const;

package/src/api/generated.ts

@@ -1553,6 +1553,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/tree": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get the org tree (path-ordered snapshot) with level labels */
+        get: operations["getOrgUnitsTree"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/orgs/{orgId}/tree": {
         parameters: {
             query?: never;
@@ -5728,6 +5745,26 @@ export interface operations {
             };
         };
     };
+    getOrgUnitsTree: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Org tree snapshot */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgUnitTreeResponse"];
+                };
+            };
+        };
+    };
     getOrgTree: {
         parameters: {
             query?: never;

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

@@ -128,17 +128,24 @@ describe('OrgUnitRelationshipSchema', () => {
 });
 
 describe('OrgLevelConfigSchema', () => {
-  it('enforces depth 1..5 and non-empty label', () => {
+  it('enforces depth 1..5, non-empty-when-present label, and icon enum', () => {
     const entry = {
       orgId: UUID_B,
       depth: 2,
       label: 'Department',
+      icon: 'users-four' as const,
       createdAt: '2026-04-17T00:00:00Z',
       updatedAt: '2026-04-17T00:00:00Z',
     };
     expect(() => OrgLevelConfigSchema.parse(entry)).not.toThrow();
+    expect(() =>
+      OrgLevelConfigSchema.parse({ ...entry, label: null, icon: null })
+    ).not.toThrow();
     expect(() => OrgLevelConfigSchema.parse({ ...entry, depth: 6 })).toThrow();
     expect(() => OrgLevelConfigSchema.parse({ ...entry, label: '' })).toThrow();
+    expect(() =>
+      OrgLevelConfigSchema.parse({ ...entry, icon: 'not-an-icon' })
+    ).toThrow();
   });
 });
 

package/src/org/index.ts

@@ -204,7 +204,9 @@ export type {
   OrgUnitMembershipStatus,
   OrgUnitMembershipSource,
   OrgUnitErrorCode,
+  OrgTreeResponse,
 } from './org-units';
+export { ORG_UNITS_ROUTES } from './org-units';
 export {
   OrgUnitClassificationSchema,
   OrgUnitSyncModeSchema,
@@ -220,6 +222,7 @@ export {
   OrgUnitMembershipSchema,
   OrgUnitRelationshipSchema,
   OrgLevelConfigSchema,
+  OrgLevelIconSchema,
   OrgUnitResponseSchema,
   OrgUnitTreeResponseSchema,
   OrgUnitChildrenResponseSchema,
@@ -238,6 +241,7 @@ export type {
   OrgUnitMembership,
   OrgUnitRelationship,
   OrgLevelConfig,
+  OrgLevelIcon,
   OrgUnitResponse,
   OrgUnitTreeResponse,
   OrgUnitChildrenResponse,

package/src/org/org-units.ts

@@ -45,6 +45,48 @@ export type OrgUnitMembershipStatus = 'active' | 'pending' | 'removed';
 /** External directory origin of a membership row. */
 export type OrgUnitMembershipSource = 'manual' | 'google_groups' | 'scim' | 'hris';
 
+/**
+ * Canonical route path constants for the `/api/org-units` surface.
+ *
+ * Consumers (backend route handlers, app hooks, typed clients) MUST import
+ * these rather than inlining path literals so a single rename stays
+ * consistent across the system. Parameterised paths are exposed as
+ * functions so callers cannot forget to interpolate the id.
+ *
+ * `tree` returns an `OrgTreeResponse` (alias for `OrgUnitTreeResponse`,
+ * shape `{ nodes, levelConfig }` — see `./schemas`).
+ *
+ * Used by PRD-00511 to consolidate the legacy `/api/org-tree` handler
+ * into `/api/org-units/tree` without changing the response shape.
+ */
+export const ORG_UNITS_ROUTES = {
+  list: '/api/org-units',
+  tree: '/api/org-units/tree',
+  byId: (unitId: string) => `/api/org-units/${unitId}`,
+  children: (unitId: string) => `/api/org-units/${unitId}/children`,
+  ancestors: (unitId: string) => `/api/org-units/${unitId}/ancestors`,
+  descendants: (unitId: string) => `/api/org-units/${unitId}/descendants`,
+  archive: (unitId: string) => `/api/org-units/${unitId}/archive`,
+  reparent: (unitId: string) => `/api/org-units/${unitId}/reparent`,
+  reorder: (unitId: string) => `/api/org-units/${unitId}/reorder`,
+  relationships: (unitId: string) => `/api/org-units/${unitId}/relationships`,
+  memberships: (unitId: string) => `/api/org-units/${unitId}/memberships`,
+  membershipByUser: (unitId: string, userId: string) =>
+    `/api/org-units/${unitId}/memberships/${userId}`,
+  membershipRole: (unitId: string, userId: string) =>
+    `/api/org-units/${unitId}/memberships/${userId}/role`,
+  permissions: (unitId: string) => `/api/org-units/${unitId}/permissions`,
+} as const;
+
+/**
+ * Domain-level alias for the tree endpoint response type.
+ *
+ * The canonical schema lives in `./schemas` as `OrgUnitTreeResponseSchema`
+ * / `OrgUnitTreeResponse`. This alias gives consumers the shorter
+ * `OrgTreeResponse` name used by `GET /api/org-units/tree`.
+ */
+export type { OrgUnitTreeResponse as OrgTreeResponse } from './schemas';
+
 /**
  * Error codes returned by `POST /api/org-units/:id/reparent` and related
  * mutation endpoints. Clients must handle these explicitly.

package/src/org/schemas.ts

@@ -707,10 +707,19 @@ export const OrgUnitRelationshipSchema = z.object({
   createdAt: z.string(),
 });
 
+export const OrgLevelIconSchema = z.enum([
+  'city',
+  'buildings',
+  'users-four',
+  'users-three',
+  'users',
+]);
+
 export const OrgLevelConfigSchema = z.object({
   orgId: z.string().uuid(),
   depth: z.number().int().min(1).max(5),
-  label: z.string().min(1),
+  label: z.string().min(1).nullable(),
+  icon: OrgLevelIconSchema.nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -785,6 +794,7 @@ export type OrgUnitTreeNode = z.infer<typeof OrgUnitTreeNodeSchema>;
 export type OrgUnitMembership = z.infer<typeof OrgUnitMembershipSchema>;
 export type OrgUnitRelationship = z.infer<typeof OrgUnitRelationshipSchema>;
 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 OrgUnitChildrenResponse = z.infer<typeof OrgUnitChildrenResponseSchema>;