@company-semantics/contracts 0.116.0 → 0.118.0

package/package.json

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

package/src/api/generated.ts

@@ -1893,6 +1893,70 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/context-bank": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a new context bank doc and associate with parent
+         * @description Creates a new context doc (level=context) and associates it with the
+         *     given parent doc. Requires org.view_company_md capability.
+         */
+        post: operations["createCompanyMdContextDoc"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{slug}/context-bank/associate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Associate an existing context doc with a parent doc
+         * @description Associates an existing context doc with the given parent doc.
+         *     Returns 409 if the association already exists.
+         *     Requires org.view_company_md capability.
+         */
+        post: operations["associateCompanyMdContextDoc"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/docs/{slug}/context-bank/{contextDocSlug}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Remove a context bank association
+         * @description Removes the association between a context doc and its parent doc.
+         *     Requires org.view_company_md capability.
+         */
+        delete: operations["removeCompanyMdContextAssociation"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/docs/{slug}/sharing": {
         parameters: {
             query?: never;
@@ -2006,6 +2070,50 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/company-md/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get company.md settings for the authenticated org
+         * @description Returns CompanyMdSettings with merged defaults. The root label defaults
+         *     to the org name; department and team use system defaults if not customized.
+         *     Requires org.view_company_md capability.
+         */
+        get: operations["getCompanyMdSettings"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/company-md/settings/level-labels": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Update company.md level labels for the authenticated org
+         * @description Accepts a partial CompanyMdLevelLabels object. Only provided fields are updated;
+         *     unspecified fields retain their current values. Returns the full updated
+         *     CompanyMdSettings. Requires org.manage_company_md capability (org owner/admin).
+         */
+        put: operations["updateCompanyMdLevelLabels"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/teams": {
         parameters: {
             query?: never;
@@ -2387,6 +2495,25 @@ export interface components {
             /** @enum {string} */
             visibility: "standard" | "admin";
         };
+        CompanyMdLevelLabels: {
+            /** @description Label for the root level (defaults to org name) */
+            root: string;
+            /** @description Label for the department level */
+            department: string;
+            /** @description Label for the team level */
+            team: string;
+        };
+        CompanyMdSettings: {
+            levelLabels: components["schemas"]["CompanyMdLevelLabels"];
+        };
+        UpdateCompanyMdLevelLabelsRequest: {
+            /** @description Label for the root level */
+            root?: string;
+            /** @description Label for the department level */
+            department?: string;
+            /** @description Label for the team level */
+            team?: string;
+        };
         ChatRequest: {
             messages: Record<string, never>[];
         };
@@ -7473,6 +7600,155 @@ export interface operations {
             };
         };
     };
+    createCompanyMdContextDoc: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    title: string;
+                    parentDocSlug: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Created context doc */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** Format: uuid */
+                        id: string;
+                        slug: string;
+                        title: string;
+                    };
+                };
+            };
+            /** @description No org.view_company_md capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Parent doc not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    associateCompanyMdContextDoc: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Parent doc slug */
+                slug: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    contextDocSlug: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Association created */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        ok?: boolean;
+                    };
+                };
+            };
+            /** @description No org.view_company_md capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Doc not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Association already exists */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    removeCompanyMdContextAssociation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Parent doc slug */
+                slug: string;
+                /** @description Context doc slug */
+                contextDocSlug: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Association removed */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No org.view_company_md capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Doc not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     getCompanyMdDocSharing: {
         parameters: {
             query?: never;
@@ -7785,6 +8061,77 @@ export interface operations {
             };
         };
     };
+    getCompanyMdSettings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Company.md settings with merged defaults */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdSettings"];
+                };
+            };
+            /** @description No org.view_company_md capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    updateCompanyMdLevelLabels: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateCompanyMdLevelLabelsRequest"];
+            };
+        };
+        responses: {
+            /** @description Updated company.md settings */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CompanyMdSettings"];
+                };
+            };
+            /** @description Invalid label values (empty or exceeds 50 characters) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description No org.manage_company_md capability */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listTeams: {
         parameters: {
             query?: never;

package/src/identity/index.ts

@@ -28,3 +28,7 @@ export type { AvatarSource, ResolvedAvatar } from './avatar';
 
 // Functions - Avatar
 export { generateInitials, resolveAvatar } from './avatar';
+
+// Response Schemas (Zod) - canonical location per ADR-CONT-044
+export { MeResponseSchema, AuthStartResponseSchema, AuthVerifyResponseSchema, SsoConfigResponseSchema, ProfileResponseSchema } from './schemas';
+export type { MeResponse, AuthStartResponse, AuthVerifyResponse, SsoConfigResponse, ProfileResponse } from './schemas';

package/src/identity/schemas.ts

@@ -0,0 +1,139 @@
+/**
+ * Identity Response Schemas
+ *
+ * Zod response schemas for auth and identity endpoints.
+ * Canonical location for runtime validation of identity API responses.
+ *
+ * Deviation note (AuthStartResponseSchema): The PRD reference suggested
+ * z.object({ sent: boolean }), but the actual POST /auth/start route returns
+ * a discriminated union on `mode` (otp | sso | hybrid). Schema matches reality.
+ */
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Shared sub-schemas
+// ---------------------------------------------------------------------------
+
+const ResolvedAvatarSchema = z.object({
+  source: z.enum(['slack', 'initials']),
+  url: z.string().optional(),
+  initials: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// GET /api/me
+// ---------------------------------------------------------------------------
+
+/**
+ * Full identity context returned by GET /api/me.
+ * Canonical location: moved from backend contract-surfaces.ts per ADR-CONT-044.
+ */
+export const MeResponseSchema = z.object({
+  userId: z.string().uuid(),
+  email: z.string(),
+  fullName: z.string(),
+  preferredName: z.string().nullable(),
+  displayName: z.string(),
+  nameSource: z.enum(['self', 'sso']),
+  nameEditable: z.boolean(),
+  primaryDepartmentId: z.string().nullable(),
+  slackUserId: z.string().nullable(),
+  avatar: ResolvedAvatarSchema,
+  orgId: z.string().uuid(),
+  orgName: z.string().nullable(),
+  orgSlug: z.string(),
+  plan: z.string(),
+  hasMultipleOrgs: z.boolean(),
+  isInternalAdmin: z.boolean(),
+});
+
+export type MeResponse = z.infer<typeof MeResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /auth/start
+// Discriminated union on mode: otp | sso | hybrid
+// ---------------------------------------------------------------------------
+
+export const AuthStartResponseSchema = z.discriminatedUnion('mode', [
+  z.object({
+    mode: z.literal('otp'),
+    devOtp: z.string().optional(),
+  }),
+  z.object({
+    mode: z.literal('sso'),
+    providers: z.array(z.string()),
+    redirectUrl: z.string(),
+  }),
+  z.object({
+    mode: z.literal('hybrid'),
+    providers: z.array(z.string()),
+    redirectUrl: z.string(),
+    otpAllowed: z.literal(true),
+    devOtp: z.string().optional(),
+  }),
+]);
+
+export type AuthStartResponse = z.infer<typeof AuthStartResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /auth/verify
+// Sets session cookie on success; body is minimal.
+// ---------------------------------------------------------------------------
+
+export const AuthVerifyResponseSchema = z.union([
+  z.object({
+    success: z.literal(true),
+    ok: z.literal(true),
+  }),
+  z.object({
+    success: z.literal(true),
+    ok: z.literal(true),
+    acceptedInvite: z.literal(true),
+    orgId: z.string(),
+    role: z.string(),
+  }),
+]);
+
+export type AuthVerifyResponse = z.infer<typeof AuthVerifyResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/auth  (SSO configuration)
+// Matches WorkspaceAuthConfig from org/types.ts
+// ---------------------------------------------------------------------------
+
+const AuthMethodConfigSchema = z.object({
+  enabled: z.boolean(),
+  provider: z.string().optional(),
+});
+
+export const SsoConfigResponseSchema = z.object({
+  emailOtp: AuthMethodConfigSchema,
+  googleSso: AuthMethodConfigSchema,
+  microsoftSso: AuthMethodConfigSchema,
+  okta: AuthMethodConfigSchema,
+  policy: z.object({
+    requireSSO: z.boolean(),
+    allowedProviders: z.array(z.string()),
+  }),
+});
+
+export type SsoConfigResponse = z.infer<typeof SsoConfigResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /api/user/profile
+// Profile shape returned after a successful profile update.
+// ---------------------------------------------------------------------------
+
+export const ProfileResponseSchema = z.object({
+  success: z.literal(true),
+  user: z.object({
+    id: z.string(),
+    fullName: z.string(),
+    preferredName: z.string().nullable(),
+    displayName: z.string(),
+    nameSource: z.enum(['self', 'sso']),
+    primaryDepartmentId: z.string().nullable(),
+  }),
+});
+
+export type ProfileResponse = z.infer<typeof ProfileResponseSchema>;

package/src/index.ts

@@ -120,6 +120,21 @@ export { extractFirstWord, resolveDisplayName, deriveFullName } from './identity
 export type { AvatarSource, ResolvedAvatar } from './identity/index'
 export { generateInitials, resolveAvatar } from './identity/index'
 
+// Identity response schemas (Zod) - canonical location per ADR-CONT-044
+export {
+  MeResponseSchema,
+  AuthStartResponseSchema,
+  AuthVerifyResponseSchema,
+  SsoConfigResponseSchema,
+  ProfileResponseSchema,
+} from './identity/index'
+export type {
+  MeResponse,
+  AuthVerifyResponse,
+  SsoConfigResponse,
+  ProfileResponse,
+} from './identity/index'
+
 // Auth domain types
 export type { AuthStartMode, AuthStartResponse } from './auth/index'
 export { OTPErrorCode } from './auth/index'

package/src/org/company-md.ts

@@ -76,6 +76,25 @@ export interface CompanyMdDocRelations {
 
 export type CompanyMdDoc = CompanyMdDocCore & CompanyMdDocCollaborators & CompanyMdDocRelations;
 
+export interface CompanyMdLevelLabels {
+  /** L1 label — defaults to org name */
+  readonly root: string;
+  /** L2 label — defaults to 'Department' */
+  readonly department: string;
+  /** L3 label — defaults to 'Team' */
+  readonly team: string;
+}
+
+export interface CompanyMdSettings {
+  readonly levelLabels: CompanyMdLevelLabels;
+}
+
+/** System defaults for level labels. L1 (root) is set per-org at read time. */
+export const DEFAULT_LEVEL_LABELS: Omit<CompanyMdLevelLabels, 'root'> = {
+  department: 'Department',
+  team: 'Team',
+} as const;
+
 /**
  * A context bank item — a company.md doc associated with one or more parent nodes.
  * Context bank files can belong to company, department, or team levels.

package/src/org/index.ts

@@ -96,8 +96,13 @@ export type {
   CompanyMdContextBankItem,
   TeamDepartmentRole,
   TeamDepartmentMembership,
+  // Level labels settings types (PRD-00453)
+  CompanyMdLevelLabels,
+  CompanyMdSettings,
 } from './company-md';
 
+export { DEFAULT_LEVEL_LABELS } from './company-md';
+
 // Team types (PRD-00306)
 export type {
   TeamMembershipRole,