feat: enhance type exports and improve utility functions for better type safety

Author: AshishKumar4

sdk/src/index.ts

@@ -5,10 +5,12 @@ export { BuildSession } from './session';
 export { WorkspaceStore } from './workspace';
 export { SessionStateStore } from './state';
 
-export { isRecord, blueprintToMarkdown, BlueprintStreamParser } from './blueprint';
+export { blueprintToMarkdown, BlueprintStreamParser } from './blueprint';
 export type { Blueprint } from './blueprint';
 
-export { withTimeout, TimeoutError } from './utils';
+export { isRecord, withTimeout, TimeoutError } from './utils';
+
+export type { WebSocketFactory } from './ws';
 
 export type {
 	AgentConnection,
@@ -18,18 +20,23 @@ export type {
 	ApiResponse,
 	AppDetails,
 	AppListItem,
+	AppVisibility,
+	AppWithFavoriteStatus,
 	BehaviorType,
 	BuildOptions,
 	BuildStartEvent,
 	CodeGenArgs,
 	Credentials,
+	DeleteResult,
 	FileTreeNode,
 	PhaseEventType,
 	ProjectType,
 	PublicAppsQuery,
 	SessionDeployable,
 	SessionFiles,
+	ToggleResult,
 	VibeClientOptions,
+	VisibilityUpdateResult,
 	WaitForPhaseOptions,
 	WaitOptions,
 } from './types';

sdk/src/protocol.ts

@@ -23,3 +23,5 @@ export type {
 	CodeGenArgs as PlatformCodeGenArgs,
 	AgentPreviewResponse,
 } from '../../worker/api/controllers/agent/types';
+
+export type { ImageAttachment } from '../../worker/types/image-attachment';

sdk/src/session.ts

@@ -6,6 +6,7 @@ import type {
 	BuildStartEvent,
 	Credentials,
 	FileTreeNode,
+	ImageAttachment,
 	PhaseEventType,
 	ProjectType,
 	SessionDeployable,
@@ -183,7 +184,7 @@ export class BuildSession {
 		this.connection!.send({ type: 'stop_generation' });
 	}
 
-	followUp(message: string, options?: { images?: unknown[] }): void {
+	followUp(message: string, options?: { images?: ImageAttachment[] }): void {
 		this.assertConnected();
 		this.connection!.send({
 			type: 'user_suggestion',

sdk/src/types.ts

@@ -3,41 +3,36 @@ import type {
 	ProjectType as PlatformProjectType,
 	PlatformCodeGenArgs,
 	WebSocketMessage,
+	ImageAttachment as PlatformImageAttachment,
+	AgentState as PlatformAgentState,
 } from './protocol';
 import type { RetryConfig } from './retry';
 export type { RetryConfig } from './retry';
 
 export type BehaviorType = PlatformBehaviorType;
 export type ProjectType = PlatformProjectType;
+export type ImageAttachment = PlatformImageAttachment;
+export type AgentState = PlatformAgentState;
 
-// Ephemeral, optional credentials (not persisted by SDK).
 export type Credentials = NonNullable<PlatformCodeGenArgs['credentials']>;
-
 export type CodeGenArgs = PlatformCodeGenArgs;
 
 export type BuildOptions = Omit<CodeGenArgs, 'query'> & {
-	/**
-	 * If true (default), connect to the agent websocket immediately.
-	 */
 	autoConnect?: boolean;
-	/**
-	 * If true (default), send `{ type: 'generate_all' }` after websocket connection.
-	 */
 	autoGenerate?: boolean;
-	/**
-	 * Called for each blueprint chunk emitted by the create-agent stream.
-	 */
 	onBlueprintChunk?: (chunk: string) => void;
 };
 
+export type TemplateFiles = Record<string, string>;
+
 export type BuildStartEvent = {
 	message?: string;
 	agentId: string;
 	websocketUrl: string;
 	httpStatusUrl?: string;
 	behaviorType?: BehaviorType;
 	projectType?: string;
-	template?: { name: string; files?: unknown };
+	template?: { name: string; files?: TemplateFiles };
 };
 
 export type ApiResponse<T> =
@@ -65,10 +60,44 @@ export type AppListItem = {
 	previewUrl?: string;
 };
 
-export type AppDetails = Record<string, unknown> & {
+export type AppDetails = {
 	id: string;
 	previewUrl?: string;
 	cloudflareUrl?: string;
+	title?: string;
+	description?: string | null;
+	framework?: string | null;
+	visibility?: 'public' | 'private';
+	createdAt?: string | null;
+	updatedAt?: string | null;
+	[key: string]: string | null | undefined;
+};
+
+export type AppVisibility = 'public' | 'private';
+
+export type AppWithFavoriteStatus = AppListItem & {
+	isFavorite: boolean;
+	updatedAtFormatted?: string;
+};
+
+export type VisibilityUpdateResult = {
+	app: {
+		id: string;
+		title: string;
+		visibility: AppVisibility;
+		updatedAt: string | null;
+	};
+	message: string;
+};
+
+export type ToggleResult = {
+	isFavorite?: boolean;
+	isStarred?: boolean;
+};
+
+export type DeleteResult = {
+	success: boolean;
+	message: string;
 };
 
 export type AgentWsServerMessage = WebSocketMessage;
@@ -82,7 +111,7 @@ export type AgentWsClientMessage =
 	| { type: 'deploy' }
 	| { type: 'get_conversation_state' }
 	| { type: 'clear_conversation' }
-	| { type: 'user_suggestion'; message: string; images?: unknown[] };
+	| { type: 'user_suggestion'; message: string; images?: ImageAttachment[] };
 
 export type AgentWebSocketMessage = AgentWsServerMessage | AgentWsClientMessage;
 
@@ -94,11 +123,9 @@ export type WsMessageOf<TType extends AgentWsServerMessage['type']> = Extract<
 export type AgentEventMap = {
 	'ws:open': undefined;
 	'ws:close': { code: number; reason: string };
-	'ws:error': { error: unknown };
+	'ws:error': { error: Error | string };
 	'ws:reconnecting': { attempt: number; delayMs: number; reason: 'close' | 'error' };
-	/** Server payload that isn't a well-formed typed message. */
-	'ws:raw': { raw: unknown };
-	/** Raw server->client message (typed) */
+	'ws:raw': { raw: Record<string, unknown> };
 	'ws:message': AgentWsServerMessage;
 
 	// High-level sugar events (typed)
@@ -130,14 +157,26 @@ export type AgentEventMap = {
 	error: { error: string };
 };
 
+export type WsOpenEvent = Event;
+export type WsCloseEvent = CloseEvent | { code?: number; reason?: string };
+export type WsErrorEvent = Event | Error;
+export type WsMessageEvent = MessageEvent | { data: string };
+
+export type WebSocketEventMap = {
+	open: WsOpenEvent;
+	close: WsCloseEvent;
+	error: WsErrorEvent;
+	message: WsMessageEvent;
+};
+
+export type WebSocketEventType = keyof WebSocketEventMap;
+export type WebSocketEventListener<K extends WebSocketEventType> = (event: WebSocketEventMap[K]) => void;
+
 export type WebSocketLike = {
 	send: (data: string) => void;
 	close: () => void;
-	addEventListener?: (
-		type: 'open' | 'close' | 'error' | 'message',
-		listener: (event: unknown) => void
-	) => void;
-	on?: (type: string, listener: (...args: unknown[]) => void) => void;
+	addEventListener?<K extends WebSocketEventType>(type: K, listener: WebSocketEventListener<K>): void;
+	on?<K extends WebSocketEventType>(type: K, listener: WebSocketEventListener<K>): void;
 };
 
 export type AgentConnectionOptions = {
@@ -208,18 +247,16 @@ export type SessionDeployable = {
 
 export type VibeClientOptions = {
 	baseUrl: string;
-	/**
-	 * Current platform requirement: JWT access token. In future this will be minted from `apiKey`.
-	 */
+	/** JWT access token (or will be minted from apiKey). */
 	token?: string;
-	/** Future: VibeSDK API key. */
+	/** VibeSDK API key. */
 	apiKey?: string;
 	defaultHeaders?: Record<string, string>;
-	/** Used as Origin header for WS (optional but often required). */
+	/** Origin header for WebSocket connections. */
 	websocketOrigin?: string;
-	/** Optional WebSocket factory for Node/Bun runtimes. */
+	/** WebSocket factory - use runtime-specific factories from /browser, /worker, or /node. */
 	webSocketFactory?: AgentConnectionOptions['webSocketFactory'];
 	fetchFn?: typeof fetch;
-	/** HTTP retry configuration for transient failures (5xx, network errors). */
+	/** HTTP retry config for transient failures. */
 	retry?: RetryConfig;
 };

sdk/src/utils.ts

@@ -1,3 +1,10 @@
+/**
+ * Checks if a value is a plain object (not null, not an array).
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * Error thrown when an operation times out.
  */

sdk/src/workspace.ts

@@ -1,4 +1,5 @@
 import { TypedEmitter } from './emitter';
+import { isRecord } from './utils';
 import type { AgentState, FileOutputType } from './protocol';
 import type { AgentWsServerMessage } from './types';
 
@@ -16,10 +17,6 @@ type WorkspaceEvents = {
 	change: WorkspaceChange;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null;
-}
-
 function isFileOutputType(value: unknown): value is FileOutputType {
 	if (!isRecord(value)) return false;
 	return typeof value.filePath === 'string' && typeof value.fileContents === 'string';