@company-semantics/contracts 0.118.0 → 0.119.0

package/package.json

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

package/src/api/generated.ts

@@ -56,13 +56,8 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Start passwordless auth flow
-         * @description Initiates passwordless authentication by generating and sending an OTP to the provided email.
-         *     Rate limited per email (3/15min) and per IP (20/hour).
-         *     If the user's org requires SSO, returns SSO_REQUIRED error with redirect info.
-         */
-        post: operations["startAuth"];
+        /** Start passwordless auth flow */
+        post: operations["authStart"];
         delete?: never;
         options?: never;
         head?: never;
@@ -78,12 +73,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Verify OTP and create session
-         * @description Verifies the OTP code and creates a session.
-         *     Sets an httpOnly session cookie on success.
-         *     Rate limited per email (5/10min) and per IP (20/hour).
-         */
+        /** Verify OTP and create session */
         post: operations["verifyAuth"];
         delete?: never;
         options?: never;
@@ -100,12 +90,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Revoke session and clear cookie
-         * @description Revokes the current session and clears the session cookie.
-         *     Safe to call without auth (clears cookie regardless).
-         *     Requires X-Requested-With header for CSRF protection.
-         */
+        /** Revoke session and clear cookie */
         post: operations["logout"];
         delete?: never;
         options?: never;
@@ -120,11 +105,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get current authenticated user
-         * @description Returns the current user's authentication info.
-         *     Requires valid session cookie.
-         */
+        /** Get current authenticated user */
         get: operations["getAuthMe"];
         put?: never;
         post?: never;
@@ -141,11 +122,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Initiate SSO flow for organization
-         * @description Initiates SSO flow for an organization.
-         *     Validates org exists and has SSO configured, generates state token, and redirects to IdP.
-         */
+        /** Initiate SSO flow for organization */
         get: operations["initiateSso"];
         put?: never;
         post?: never;
@@ -162,20 +139,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * OIDC callback endpoint
-         * @description Handles OIDC callback from identity providers.
-         *     Validates state, exchanges code for tokens, creates session.
-         *     Redirects to return URL or login page on error.
-         */
+        /** OIDC callback endpoint */
         get: operations["handleOidcCallback"];
         put?: never;
-        /**
-         * SAML callback endpoint
-         * @description Handles SAML callback from identity providers.
-         *     Validates RelayState, processes SAML assertion, creates session.
-         *     Redirects to return URL or login page on error.
-         */
+        /** SAML callback endpoint */
         post: operations["handleSamlCallback"];
         delete?: never;
         options?: never;
@@ -190,11 +157,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Get current user and org context
-         * @description Returns the current user's identity fields and organization context.
-         *     Identity is resolved via request context (DEV_ORG_ID in dev, session in production).
-         */
+        /** Get current user and org context */
         get: operations["getCurrentUser"];
         put?: never;
         post?: never;
@@ -217,12 +180,7 @@ export interface paths {
         delete?: never;
         options?: never;
         head?: never;
-        /**
-         * Update current user's profile
-         * @description Updates the current user's name fields.
-         *     At least one field must be provided.
-         *     displayName is computed at read time and cannot be set directly.
-         */
+        /** Update current user profile */
         patch: operations["updateUserProfile"];
         trace?: never;
     };
@@ -317,11 +275,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /**
-         * Resync user avatar from Slack
-         * @description Manually resync the current user's avatar from their Slack profile.
-         *     Requires user to have a linked Slack identity and the org to have an active Slack connection.
-         */
+        /** Resync Slack avatar */
         post: operations["resyncSlackAvatar"];
         delete?: never;
         options?: never;
@@ -336,11 +290,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * Initiate OAuth flow
-         * @description Creates a pending connection and redirects to the OAuth provider's consent screen.
-         *     Replaces raw OAuth URLs with first-party redirect for trust and tracking.
-         */
+        /** Initiate OAuth flow */
         get: operations["initiateOAuth"];
         put?: never;
         post?: never;
@@ -357,12 +307,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /**
-         * OAuth callback handler
-         * @description Handles the OAuth callback from providers.
-         *     Verifies state, exchanges code for tokens, stores encrypted tokens.
-         *     Returns HTML success or error page.
-         */
+        /** OAuth callback handler */
         get: operations["handleOAuthCallback"];
         put?: never;
         post?: never;
@@ -2352,46 +2297,45 @@ export interface components {
         MeResponse: {
             /** Format: uuid */
             userId: string;
-            /** Format: email */
             email: string;
             fullName: string;
-            preferredName?: string | null;
-            /** @description Computed at read time (preferredName ?? fullName) */
+            preferredName: string | null;
             displayName: string;
             /** @enum {string} */
             nameSource: "self" | "sso";
             nameEditable: boolean;
             primaryDepartmentId: string | null;
             slackUserId: string | null;
-            avatar: components["schemas"]["ResolvedAvatar"];
+            avatar: {
+                /** @enum {string} */
+                source: "slack" | "initials";
+                url?: string;
+                initials: string;
+            };
             /** Format: uuid */
             orgId: string;
             orgName: string | null;
             orgSlug: string;
-            /** @enum {string} */
-            plan: "free" | "pro" | "enterprise";
+            plan: string;
             hasMultipleOrgs: boolean;
             isInternalAdmin: boolean;
         };
-        /** @description At least one field must be provided */
         ProfileUpdateRequest: {
-            firstName?: string;
-            lastName?: string | null;
             fullName?: string;
-            /** @description Cannot contain control characters, newlines, or quotes */
             preferredName?: string | null;
+            primaryDepartmentId?: string | null;
         };
         ProfileUpdateResponse: {
             /** @constant */
             success: true;
             user: {
-                /** Format: uuid */
                 id: string;
-                firstName: string;
-                lastName?: string | null;
                 fullName: string;
-                preferredName?: string | null;
+                preferredName: string | null;
                 displayName: string;
+                /** @enum {string} */
+                nameSource: "self" | "sso";
+                primaryDepartmentId: string | null;
             };
         };
         ResyncSlackLogoResponse: {
@@ -2906,25 +2850,47 @@ export interface components {
             truncated: boolean;
         };
         AuthStartRequest: {
-            /**
-             * Format: email
-             * @description Email address for OTP delivery
-             */
+            /** Format: email */
             email: string;
         };
         AuthStartResponse: {
             /** @constant */
-            ok: true;
+            mode: "otp";
+            devOtp?: string;
+        } | {
+            /** @constant */
+            mode: "sso";
+            providers: string[];
+            redirectUrl: string;
+        } | {
+            /** @constant */
+            mode: "hybrid";
+            providers: string[];
+            redirectUrl: string;
+            /** @constant */
+            otpAllowed: true;
+            devOtp?: string;
         };
         AuthVerifyRequest: {
             /** Format: email */
             email: string;
-            /** @description 6-digit OTP code */
             code: string;
+            inviteToken?: string;
         };
         AuthVerifyResponse: {
+            /** @constant */
+            success: true;
             /** @constant */
             ok: true;
+        } | {
+            /** @constant */
+            success: true;
+            /** @constant */
+            ok: true;
+            /** @constant */
+            acceptedInvite: true;
+            orgId: string;
+            role: string;
         };
         OkResponse: {
             /** @constant */
@@ -2952,9 +2918,7 @@ export interface components {
             orgSlug: string;
         };
         SamlCallbackRequest: {
-            /** @description Base64-encoded SAML assertion */
             SAMLResponse: string;
-            /** @description State token for CSRF protection */
             RelayState: string;
         };
         InitiateTransferRequest: {
@@ -3409,6 +3373,12 @@ export interface components {
             /** @description Organization name (present when invite is valid) */
             orgName?: string;
         };
+        LogoutResponse: {
+            /** @constant */
+            success: true;
+            /** @constant */
+            ok: true;
+        };
     };
     responses: never;
     parameters: never;
@@ -3458,7 +3428,7 @@ export interface operations {
             };
         };
     };
-    startAuth: {
+    authStart: {
         parameters: {
             query?: never;
             header?: never;
@@ -3471,7 +3441,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description OTP sent successfully */
+            /** @description Auth mode resolved; OTP sent when applicable */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -3480,33 +3450,6 @@ export interface operations {
                     "application/json": components["schemas"]["AuthStartResponse"];
                 };
             };
-            /** @description Validation error (invalid email format) */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description SSO required for this user's organization */
-            409: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["SSORequiredErrorResponse"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     verifyAuth: {
@@ -3522,7 +3465,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Authentication successful, session cookie set */
+            /** @description Session created; cookie set */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -3531,24 +3474,6 @@ export interface operations {
                     "application/json": components["schemas"]["AuthVerifyResponse"];
                 };
             };
-            /** @description Validation error or invalid/expired OTP */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["OTPErrorResponse"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     logout: {
@@ -3560,22 +3485,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Session revoked successfully */
+            /** @description Session revoked; cookie cleared */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["OkResponse"];
-                };
-            };
-            /** @description Missing CSRF header */
-            403: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
+                    "application/json": components["schemas"]["LogoutResponse"];
                 };
             };
         };
@@ -3594,32 +3510,17 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["AuthMeResponse"];
-                };
-            };
-            /** @description Not authenticated */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };
     initiateSso: {
         parameters: {
             query?: {
-                /** @description URL to redirect after successful auth (validated against allowlist) */
                 return_to?: string;
             };
             header?: never;
-            path: {
-                /** @description Organization slug */
-                orgSlug: string;
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
@@ -3627,42 +3528,18 @@ export interface operations {
             /** @description Redirect to identity provider */
             302: {
                 headers: {
-                    /** @description Identity provider authorization URL */
-                    Location?: string;
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description SSO not configured for organization */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Organization not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     handleOidcCallback: {
         parameters: {
             query?: {
-                /** @description Authorization code from IdP */
                 code?: string;
-                /** @description State token for CSRF protection */
                 state?: string;
-                /** @description Error code if auth failed at IdP */
                 error?: string;
-                /** @description Human-readable error description */
                 error_description?: string;
             };
             header?: never;
@@ -3674,20 +3551,10 @@ export interface operations {
             /** @description Redirect to return URL or login page */
             302: {
                 headers: {
-                    Location?: string;
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Invalid callback parameters */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     handleSamlCallback: {
@@ -3706,20 +3573,10 @@ export interface operations {
             /** @description Redirect to return URL or login page */
             302: {
                 headers: {
-                    Location?: string;
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Invalid callback parameters */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     getCurrentUser: {
@@ -3740,24 +3597,6 @@ export interface operations {
                     "application/json": components["schemas"]["MeResponse"];
                 };
             };
-            /** @description User or organization not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Configuration error (e.g., missing DEV_ORG_ID) */
-            500: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     updateUserProfile: {
@@ -3782,24 +3621,6 @@ export interface operations {
                     "application/json": components["schemas"]["ProfileUpdateResponse"];
                 };
             };
-            /** @description Validation error */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ValidationErrorResponse"];
-                };
-            };
-            /** @description User not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     listUserOrgs: {
@@ -3969,124 +3790,55 @@ export interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "application/json": components["schemas"]["ResyncSlackAvatarResponse"];
-                };
-            };
-            /** @description Not authenticated */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description User not found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description Rate limit exceeded */
-            429: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
+                content?: never;
             };
         };
     };
     initiateOAuth: {
         parameters: {
-            query?: {
-                /**
-                 * @deprecated
-                 * @description DEPRECATED: Organization ID derived from session.
-                 *     Query parameter accepted only in dev mode for backwards compatibility.
-                 *     Production: orgId is always derived from authenticated session.
-                 */
-                orgId?: string;
-            };
+            query?: never;
             header?: never;
-            path: {
-                provider: components["schemas"]["OAuthProvider"];
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
         responses: {
-            /** @description Redirect to OAuth provider */
+            /** @description Redirect to OAuth provider consent screen */
             302: {
                 headers: {
-                    /** @description OAuth provider authorization URL */
-                    Location?: string;
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Invalid provider or missing/invalid orgId */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
-            /** @description OAuth initialization failed */
-            500: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ErrorResponse"];
-                };
-            };
         };
     };
     handleOAuthCallback: {
         parameters: {
             query?: {
-                /** @description Authorization code from provider */
                 code?: string;
-                /** @description State token for CSRF protection */
                 state?: string;
-                /** @description Error code from provider (if authorization denied) */
                 error?: string;
-                /** @description Human-readable error description from provider */
                 error_description?: string;
             };
             header?: never;
-            path: {
-                provider: components["schemas"]["OAuthProvider"];
-            };
+            path?: never;
             cookie?: never;
         };
         requestBody?: never;
         responses: {
-            /** @description Authorization successful (HTML page) */
+            /** @description HTML success or error page (for popup flows) */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "text/html": string;
-                };
+                content?: never;
             };
-            /** @description Authorization failed or invalid request (HTML page) */
-            400: {
+            /** @description Redirect to return URL on success */
+            302: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content: {
-                    "text/html": string;
-                };
+                content?: never;
             };
         };
     };

package/src/chat/index.ts

@@ -38,6 +38,14 @@ export type {
   ChatInvalidationEvent,
   // SSE event unions
   ChatSseEvent,
+  // HTTP response types
+  ChatSuccessResponse,
+  ChatByInteractionResponse,
+  ChatListResponse,
+  CreateChatResponse,
+  CreateShareResponse,
+  ListSharesResponse,
+  UpdateShareResponse,
 } from './types'
 
 // =============================================================================
@@ -65,6 +73,14 @@ export {
   ChatDomainEventSchema,
   ChatInvalidationEventSchema,
   ChatSseEventSchema,
+  // HTTP response schemas
+  ChatSuccessResponseSchema,
+  ChatByInteractionResponseSchema,
+  ChatListResponseSchema,
+  CreateChatResponseSchema,
+  CreateShareResponseSchema,
+  ListSharesResponseSchema,
+  UpdateShareResponseSchema,
 } from './schemas'
 
 // Runtime profile types and constants

package/src/chat/schemas.ts

@@ -152,3 +152,43 @@ export const ChatSseEventSchema = z.discriminatedUnion('type', [
   InvalidateChatEventSchema,
   InvalidateChatListEventSchema,
 ])
+
+// =============================================================================
+// HTTP Response Schemas
+// =============================================================================
+
+/** Generic success confirmation for mutations that return no entity data. */
+export const ChatSuccessResponseSchema = z.object({
+  success: z.literal(true),
+})
+
+/** Response for GET /api/chats/by-interaction/:interactionId */
+export const ChatByInteractionResponseSchema = z.object({
+  chatId: z.string(),
+})
+
+/** Response for GET /api/chats */
+export const ChatListResponseSchema = z.object({
+  chats: z.array(ChatSummaryExtendedSchema),
+})
+
+/** Response for POST /api/chats */
+export const CreateChatResponseSchema = z.object({
+  chat: ChatSummaryExtendedSchema,
+})
+
+/** Response for POST /api/chats/:chatId/shares */
+export const CreateShareResponseSchema = z.object({
+  share: ChatShareInfoSchema,
+  shareUrl: z.string(),
+})
+
+/** Response for GET /api/chats/:chatId/shares */
+export const ListSharesResponseSchema = z.object({
+  shares: z.array(ChatShareInfoSchema),
+})
+
+/** Response for PATCH /api/shares/:shareId */
+export const UpdateShareResponseSchema = z.object({
+  share: ChatShareInfoSchema,
+})

package/src/chat/types.ts

@@ -27,6 +27,13 @@ import {
   ChatDomainEventSchema,
   ChatInvalidationEventSchema,
   ChatSseEventSchema,
+  ChatSuccessResponseSchema,
+  ChatByInteractionResponseSchema,
+  ChatListResponseSchema,
+  CreateChatResponseSchema,
+  CreateShareResponseSchema,
+  ListSharesResponseSchema,
+  UpdateShareResponseSchema,
 } from './schemas'
 
 // =============================================================================
@@ -227,3 +234,28 @@ export type ChatInvalidationEvent = z.infer<typeof ChatInvalidationEventSchema>
  * Client receives these via SSE and handles accordingly.
  */
 export type ChatSseEvent = z.infer<typeof ChatSseEventSchema>
+
+// =============================================================================
+// HTTP Response Types (derived from response schemas)
+// =============================================================================
+
+/** Generic mutation success confirmation. */
+export type ChatSuccessResponse = z.infer<typeof ChatSuccessResponseSchema>
+
+/** Response for GET /api/chats/by-interaction/:interactionId */
+export type ChatByInteractionResponse = z.infer<typeof ChatByInteractionResponseSchema>
+
+/** Response for GET /api/chats */
+export type ChatListResponse = z.infer<typeof ChatListResponseSchema>
+
+/** Response for POST /api/chats */
+export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>
+
+/** Response for POST /api/chats/:chatId/shares */
+export type CreateShareResponse = z.infer<typeof CreateShareResponseSchema>
+
+/** Response for GET /api/chats/:chatId/shares */
+export type ListSharesResponse = z.infer<typeof ListSharesResponseSchema>
+
+/** Response for PATCH /api/shares/:shareId */
+export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>