@cloudcli-ai/cloudcli 1.30.0 → 1.31.1

package/server/shared/types.ts

@@ -1,18 +1,77 @@
-// -------------- HTTP API response shapes for the server, shared across modules --------------
+import type { IncomingMessage } from 'node:http';
 
+//----------------- HTTP RESPONSE SHAPES ------------
+/**
+ * Canonical success envelope used by backend APIs that return a structured payload.
+ *
+ * Use this for route handlers that need a stable `success/data` shape so frontend
+ * consumers can parse responses consistently across endpoints.
+ */
 export type ApiSuccessShape<TData = unknown> = {
   success: true;
   data: TData;
 };
 
+/**
+ * Generic plain-object record used when parsing loosely typed JSON payloads.
+ *
+ * Use this only after runtime shape checks, not as a replacement for validated
+ * domain models.
+ */
 export type AnyRecord = Record<string, any>;
 
-// ---------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- WEBSOCKET TRANSPORT TYPES ------------
+/**
+ * Minimal websocket client contract used by backend broadcaster services.
+ *
+ * Any transport object added to `connectedClients` must implement these two
+ * members so shared services can safely send JSON strings and check whether the
+ * socket is still open before broadcasting.
+ */
+export type RealtimeClientConnection = {
+  readyState: number;
+  send(data: string): void;
+};
+
+/**
+ * Authenticated user payload attached to websocket upgrade requests.
+ *
+ * Platform and OSS auth flows currently use either `id` or `userId`; both are
+ * represented here so websocket handlers can resolve a stable writer user id.
+ */
+export type AuthenticatedWebSocketUser = {
+  id?: string | number;
+  userId?: string | number;
+  username?: string;
+  [key: string]: unknown;
+};
 
-export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor';
+/**
+ * HTTP upgrade request shape after websocket authentication succeeds.
+ *
+ * `verifyClient` populates `request.user` with the authenticated payload, and
+ * downstream websocket handlers rely on this extended request type.
+ */
+export type AuthenticatedWebSocketRequest = IncomingMessage & {
+  user?: AuthenticatedWebSocketUser;
+};
 
-// ---------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- PROVIDER MESSAGE MODEL ------------
+/**
+ * Providers supported by the unified server runtime.
+ *
+ * Use this as the source of truth whenever a function or payload needs to identify
+ * a specific LLM integration.
+ */
+export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor';
 
+/**
+ * Message/event variants emitted by provider adapters and normalized transports.
+ *
+ * Keep this union in sync with event kinds produced by provider session adapters.
+ */
 export type MessageKind =
   | 'text'
   | 'tool_use'
@@ -30,11 +89,10 @@ export type MessageKind =
   | 'task_notification';
 
 /**
- * Provider-neutral message event emitted over REST and realtime transports.
+ * Provider-neutral message envelope used in REST responses and realtime channels.
  *
- * Providers all produce their own native SDK/CLI event shapes, so this type keeps
- * the common envelope strict while allowing provider-specific details to ride
- * along as optional properties.
+ * Every provider-specific message must be converted into this shape before being
+ * emitted outside provider-specific modules.
  */
 export type NormalizedMessage = {
   id: string;
@@ -73,21 +131,21 @@ export type NormalizedMessage = {
 };
 
 /**
- * Pagination and provider lookup options for reading persisted session history.
+ * Shared options used to fetch historical provider messages.
+ *
+ * Consumers should pass provider-specific lookup hints (`projectPath`) only
+ * when the selected provider requires them.
  */
 export type FetchHistoryOptions = {
-  /** Claude project folder name. Required by Claude history lookup. */
-  projectName?: string;
-  /** Absolute workspace path. Required by Cursor to compute its chat hash. */
   projectPath?: string;
-  /** Page size. `null` means all messages. */
   limit?: number | null;
-  /** Pagination offset from the newest messages. */
   offset?: number;
 };
 
 /**
- * Provider-neutral history result returned by the unified messages endpoint.
+ * Standardized response payload returned from provider history readers.
+ *
+ * Use this as the contract for APIs that return paginated conversation history.
  */
 export type FetchHistoryResult = {
   messages: NormalizedMessage[];
@@ -98,21 +156,40 @@ export type FetchHistoryResult = {
   tokenUsage?: unknown;
 };
 
-// ---------------------------------------------------------------------------------------------
-
+// ---------------------------
+//----------------- SHARED ERROR TYPES ------------
+/**
+ * Optional metadata used when constructing application-level errors.
+ *
+ * `statusCode` should reflect the HTTP response status, while `code` identifies
+ * the stable machine-readable error category.
+ */
 export type AppErrorOptions = {
   code?: string;
   statusCode?: number;
   details?: unknown;
 };
 
-// -------------------- MCP related shared types --------------------
+// ---------------------------
+//----------------- MCP TYPES ------------
+/**
+ * Scope where an MCP server definition is stored and resolved.
+ *
+ * `user` is global for a user account, `local` is provider-local, and `project`
+ * is tied to a specific project path.
+ */
 export type McpScope = 'user' | 'local' | 'project';
 
+/**
+ * Transport protocol used by an MCP server definition.
+ */
 export type McpTransport = 'stdio' | 'http' | 'sse';
 
 /**
- * Provider MCP server descriptor normalized for frontend consumption.
+ * Normalized MCP server model exposed to frontend and route handlers.
+ *
+ * Provider adapters should map provider-native config to this structure before
+ * returning results.
  */
 export type ProviderMcpServer = {
   provider: LLMProvider;
@@ -131,7 +208,10 @@ export type ProviderMcpServer = {
 };
 
 /**
- * Shared payload shape for MCP server create/update operations.
+ * Payload for create/update MCP server operations.
+ *
+ * Routes and services should accept this type, validate it, and then persist it
+ * through provider-specific MCP repositories.
  */
 export type UpsertProviderMcpServerInput = {
   name: string;
@@ -149,18 +229,13 @@ export type UpsertProviderMcpServerInput = {
   envHttpHeaders?: Record<string, string>;
 };
 
-// ---------------------------------------------------------------------------------------------
-
-// -------------------- Provider auth status types --------------------
+// ---------------------------
+//----------------- PROVIDER AUTH TYPES ------------
 /**
- * Result of a provider status check (installation + authentication).
+ * Authentication status result returned by provider health checks.
  *
- * installed - Whether the provider's CLI/SDK is available
- * provider - Provider id the status belongs to
- * authenticated - Whether valid credentials exist
- * email - User email or auth method identifier
- * method - Auth method (e.g. 'api_key', 'credentials_file')
- * [error] - Error message if not installed or not authenticated
+ * This shape is consumed by settings/status endpoints to report installation and
+ * credential state for each provider.
  */
 export type ProviderAuthStatus = {
   installed: boolean;
@@ -170,3 +245,83 @@ export type ProviderAuthStatus = {
   method: string | null;
   error?: string;
 };
+
+// ---------------------------
+//----------------- SHARED DATABASE CREDENTIAL TYPES ------------
+/**
+ * Safe credential view returned by credential listing APIs.
+ *
+ * This intentionally excludes the raw credential secret while still exposing
+ * metadata needed for UI rendering and management operations.
+ */
+export type CredentialPublicRow = {
+  id: number;
+  credential_name: string;
+  credential_type: string;
+  description: string | null;
+  created_at: string;
+  is_active: number;
+};
+
+/**
+ * Result returned after creating a credential record.
+ *
+ * Use this return shape when callers need the created id and display metadata,
+ * but must never receive the stored secret value.
+ */
+export type CreateCredentialResult = {
+  id: number | bigint;
+  credentialName: string;
+  credentialType: string;
+};
+
+// ---------------------------
+//----------------- PROJECT PERSISTENCE TYPES ------------
+/**
+ * Canonical project row shape returned by the projects repository.
+ *
+ * Use this type whenever backend services need to pass around one database
+ * project record without leaking raw SQL row typing across modules.
+ */
+export type ProjectRepositoryRow = {
+  project_id: string;
+  project_path: string;
+  custom_project_name: string | null;
+  isStarred: number;
+  isArchived: number;
+};
+
+/**
+ * Result category returned by `projectsDb.createProjectPath`.
+ *
+ * `created` means a fresh row was inserted, `reactivated_archived` means an
+ * existing archived path was accepted and updated, and `active_conflict` means
+ * an already-active path blocked project creation.
+ */
+export type CreateProjectPathOutcome =
+  | 'created'
+  | 'reactivated_archived'
+  | 'active_conflict';
+
+/**
+ * Structured result returned by project-path upsert operations.
+ *
+ * Services should use this result to decide whether a request succeeded,
+ * should return a conflict, or needs follow-up retrieval of row metadata.
+ */
+export type CreateProjectPathResult = {
+  outcome: CreateProjectPathOutcome;
+  project: ProjectRepositoryRow | null;
+};
+
+/**
+ * Validation result for user-supplied workspace/project paths.
+ *
+ * `resolvedPath` is present only when validation succeeds. `error` is present
+ * only when validation fails and is suitable for user-facing diagnostics.
+ */
+export type WorkspacePathValidationResult = {
+  valid: boolean;
+  resolvedPath?: string;
+  error?: string;
+};