refactor: code quality cleanup — DRY schemas, consolidate dispatch, remove dead code (#46)

- Add createResponseSchema() factory to eliminate ~26 repeated z.union() blocks
- Extract shared dispatchNotification() from duplicated protocol/client logic
- Remove orphaned aggregateMessages() and isPartialMessage() (knip-verified)
- Fix misleading @deprecated on LEGACY_FACTORY_API_VERSION (it's required by wire protocol)
- Remove ~70 name-restating JSDoc comments that add no information beyond type names
- Remove stale internal monorepo path references from enums.ts header
- Add 11 tests for createResponseSchema and dispatchNotification

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: varin-nair-factory

src/client.ts

@@ -2,10 +2,12 @@ import type { z } from 'zod';
 
 import { ConnectionError, SessionError } from './errors.js';
 import {
+  dispatchNotification,
   ProtocolEngine,
   type AskUserHandler,
   type NotificationCallback,
   type NotificationFilter,
+  type NotificationListener,
   type PermissionHandler,
 } from './protocol.js';
 import type {
@@ -93,7 +95,6 @@ import {
   SESSION_INIT_TIMEOUT,
 } from './schemas/constants.js';
 import { DroidServerMethod, ToolConfirmationOutcome } from './schemas/enums.js';
-import { SessionNotificationParamsSchema } from './schemas/server.js';
 import type {
   AskUserRequestParams,
   AskUserResult,
@@ -106,11 +107,6 @@ export type ClientPermissionHandler = PermissionHandler;
 
 export type ClientAskUserHandler = AskUserHandler;
 
-interface ClientNotificationListener {
-  readonly callback: NotificationCallback;
-  readonly filter?: NotificationFilter;
-}
-
 export interface DroidClientOptions {
   /** A connected DroidClientTransport implementation. */
   transport: DroidClientTransport;
@@ -124,11 +120,7 @@ export class DroidClient {
   private _sessionId: string | null = null;
   private _closed = false;
 
-  /**
-   * Client-level notification listeners.
-   * Each entry is [callback, optional notification filter].
-   */
-  private readonly _notificationListeners: ClientNotificationListener[] = [];
+  private readonly _notificationListeners: NotificationListener[] = [];
 
   /** Client-level permission handler. */
   private _permissionHandler: ClientPermissionHandler | null = null;
@@ -463,7 +455,7 @@ export class DroidClient {
     callback: NotificationCallback,
     filter?: NotificationFilter
   ): () => void {
-    const entry: ClientNotificationListener = { callback, filter };
+    const entry: NotificationListener = { callback, filter };
     this._notificationListeners.push(entry);
 
     let unsubscribed = false;
@@ -508,29 +500,7 @@ export class DroidClient {
   }
 
   private _dispatchNotification(notification: Record<string, unknown>): void {
-    let notificationType: string | undefined;
-    const parsed = SessionNotificationParamsSchema.safeParse(
-      notification['params']
-    );
-    if (parsed.success) {
-      notificationType = parsed.data.notification.type;
-    }
-
-    const listeners = [...this._notificationListeners];
-    for (const listener of listeners) {
-      if (
-        listener.filter?.type != null &&
-        listener.filter.type !== notificationType
-      ) {
-        continue;
-      }
-
-      try {
-        listener.callback(notification);
-      } catch {
-        // Notification listener raised — don't crash the client
-      }
-    }
+    dispatchNotification(notification, [...this._notificationListeners]);
   }
 
   private _dispatchPermissionRequest(

src/index.ts

@@ -7,11 +7,12 @@ export * from './errors.js';
 export * from './types.js';
 export { ProcessTransport } from './transport.js';
 
-export { ProtocolEngine } from './protocol.js';
+export { dispatchNotification, ProtocolEngine } from './protocol.js';
 export type {
   AskUserHandler,
   NotificationCallback,
   NotificationFilter,
+  NotificationListener,
   PermissionHandler,
 } from './protocol.js';
 

src/protocol.ts

@@ -60,11 +60,40 @@ interface PendingRequest {
   readonly timer: ReturnType<typeof setTimeout>;
 }
 
-interface NotificationListener {
+export interface NotificationListener {
   readonly callback: NotificationCallback;
   readonly filter?: NotificationFilter;
 }
 
+/** Dispatch a notification to matching listeners, swallowing listener errors. */
+export function dispatchNotification(
+  notification: Record<string, unknown>,
+  listeners: Iterable<NotificationListener>
+): void {
+  let notificationType: string | undefined;
+  const parsed = SessionNotificationParamsSchema.safeParse(
+    notification['params']
+  );
+  if (parsed.success) {
+    notificationType = parsed.data.notification.type;
+  }
+
+  for (const listener of listeners) {
+    if (
+      listener.filter?.type != null &&
+      listener.filter.type !== notificationType
+    ) {
+      continue;
+    }
+
+    try {
+      listener.callback(notification);
+    } catch {
+      // Notification listener raised — don't crash the dispatch loop
+    }
+  }
+}
+
 export class ProtocolEngine {
   private readonly _transport: DroidClientTransport;
   private readonly _defaultTimeout: number;
@@ -277,28 +306,7 @@ export class ProtocolEngine {
   }
 
   private _handleNotification(notification: Record<string, unknown>): void {
-    let notificationType: string | undefined;
-    const parsed = SessionNotificationParamsSchema.safeParse(
-      notification['params']
-    );
-    if (parsed.success) {
-      notificationType = parsed.data.notification.type;
-    }
-
-    for (const listener of this._notificationListeners) {
-      if (
-        listener.filter?.type != null &&
-        listener.filter.type !== notificationType
-      ) {
-        continue;
-      }
-
-      try {
-        listener.callback(notification);
-      } catch {
-        // Notification listener raised — don't crash the engine
-      }
-    }
+    dispatchNotification(notification, this._notificationListeners);
   }
 
   private async _handleServerRequest(