@syncular/console 0.0.6-159 → 0.0.6-168

package/src/hooks/useConsoleApi.ts

@@ -2,9 +2,10 @@
  * React Query hooks for Console API
  */
 
-import { unwrap } from '@syncular/transport-http';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { ConnectionConfig } from '../lib/api';
 import type {
+  ApiKeyType,
   ConsoleApiKey,
   ConsoleApiKeyBulkRevokeResponse,
   ConsoleBlobListResponse,
@@ -25,57 +26,89 @@ import type {
   TimeseriesRange,
   TimeseriesStatsResponse,
 } from '../lib/types';
-import { useApiClient, useConnection } from './ConnectionContext';
+import { useConnection } from './ConnectionContext';
 import { useInstanceContext } from './useInstanceContext';
 
+type StatsParams = {
+  partitionId?: string;
+  instanceId?: string;
+};
+type TimeseriesParams = {
+  interval?: TimeseriesInterval;
+  range?: TimeseriesRange;
+  partitionId?: string;
+  instanceId?: string;
+};
+type LatencyParams = {
+  range?: TimeseriesRange;
+  partitionId?: string;
+  instanceId?: string;
+};
+type ListParams = {
+  limit?: number;
+  offset?: number;
+  partitionId?: string;
+  instanceId?: string;
+};
+type TimelineParams = ListParams & {
+  view?: 'all' | 'commits' | 'events';
+  eventType?: 'push' | 'pull';
+  actorId?: string;
+  clientId?: string;
+  requestId?: string;
+  traceId?: string;
+  table?: string;
+  outcome?: string;
+  search?: string;
+  from?: string;
+  to?: string;
+};
+type EntityLookupOptions = {
+  enabled?: boolean;
+  partitionId?: string;
+  instanceId?: string;
+};
+type RefetchableQueryOptions = {
+  refetchIntervalMs?: number;
+  enabled?: boolean;
+};
+type PrunePreviewOptions = {
+  enabled?: boolean;
+  instanceId?: string;
+};
+type OperationEventsParams = ListParams & {
+  operationType?: ConsoleOperationType;
+};
+type ApiKeysParams = {
+  limit?: number;
+  offset?: number;
+  type?: 'relay' | 'proxy' | 'admin';
+  status?: 'active' | 'revoked' | 'expiring';
+  expiresWithinDays?: number;
+  instanceId?: string;
+};
+type BlobsOptions = {
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+  refetchIntervalMs?: number;
+};
+
 const queryKeys = {
-  stats: (params?: { partitionId?: string; instanceId?: string }) =>
-    ['console', 'stats', params] as const,
-  timeseries: (params?: {
-    interval?: TimeseriesInterval;
-    range?: TimeseriesRange;
-    partitionId?: string;
-    instanceId?: string;
-  }) => ['console', 'stats', 'timeseries', params] as const,
-  latency: (params?: {
-    range?: TimeseriesRange;
-    partitionId?: string;
-    instanceId?: string;
-  }) => ['console', 'stats', 'latency', params] as const,
-  commits: (params?: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-  }) => ['console', 'commits', params] as const,
+  stats: (params?: StatsParams) => ['console', 'stats', params] as const,
+  timeseries: (params?: TimeseriesParams) =>
+    ['console', 'stats', 'timeseries', params] as const,
+  latency: (params?: LatencyParams) =>
+    ['console', 'stats', 'latency', params] as const,
+  commits: (params?: ListParams) => ['console', 'commits', params] as const,
   commitDetail: (
     seq?: string | number,
     partitionId?: string,
     instanceId?: string
   ) => ['console', 'commit-detail', seq, partitionId, instanceId] as const,
-  timeline: (params?: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-    view?: 'all' | 'commits' | 'events';
-    eventType?: 'push' | 'pull';
-    actorId?: string;
-    clientId?: string;
-    requestId?: string;
-    traceId?: string;
-    table?: string;
-    outcome?: string;
-    search?: string;
-    from?: string;
-    to?: string;
-  }) => ['console', 'timeline', params] as const,
-  clients: (params?: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-  }) => ['console', 'clients', params] as const,
+  timeline: (params?: TimelineParams) =>
+    ['console', 'timeline', params] as const,
+  clients: (params?: ListParams) => ['console', 'clients', params] as const,
   eventDetail: (
     id?: string | number,
     partitionId?: string,
@@ -90,21 +123,9 @@ const queryKeys = {
     ['console', 'handlers', instanceId] as const,
   prunePreview: (instanceId?: string) =>
     ['console', 'prune', 'preview', instanceId] as const,
-  operations: (params?: {
-    limit?: number;
-    offset?: number;
-    operationType?: ConsoleOperationType;
-    partitionId?: string;
-    instanceId?: string;
-  }) => ['console', 'operations', params] as const,
-  apiKeys: (params?: {
-    limit?: number;
-    offset?: number;
-    type?: 'relay' | 'proxy' | 'admin';
-    status?: 'active' | 'revoked' | 'expiring';
-    expiresWithinDays?: number;
-    instanceId?: string;
-  }) => ['console', 'api-keys', params] as const,
+  operations: (params?: OperationEventsParams) =>
+    ['console', 'operations', params] as const,
+  apiKeys: (params?: ApiKeysParams) => ['console', 'api-keys', params] as const,
   storage: (params?: Record<string, unknown>) =>
     ['console', 'storage', params] as const,
 };
@@ -117,220 +138,305 @@ function resolveRefetchInterval(
   return refreshIntervalMs ?? defaultValueMs;
 }
 
-interface InstanceQueryFilter {
+type ConsoleQueryValue = string | number | boolean | null | undefined;
+type QueryKey = readonly unknown[];
+type EvictClientRequest = {
+  clientId: string;
+  partitionId?: string;
   instanceId?: string;
-}
-
-function withInstanceQuery<T extends Record<string, unknown>>(
-  query: T,
-  instanceId: string | undefined
-): T & InstanceQueryFilter {
-  if (!instanceId) return query;
-  return { ...query, instanceId };
-}
-
-function serializePathSegment(value: string | number): string {
-  return encodeURIComponent(String(value));
+};
+type NotifyDataChangeRequest = {
+  tables: string[];
+  partitionId?: string;
+  instanceId?: string;
+};
+type CreateApiKeyRequest = {
+  name: string;
+  keyType: ApiKeyType;
+  scopeKeys?: string[];
+  actorId?: string;
+  expiresInDays?: number;
+};
+type ApiKeySecretResponse = { key: ConsoleApiKey; secretKey: string };
+
+function buildQueryString(
+  query: Record<string, ConsoleQueryValue> | undefined
+): URLSearchParams {
+  const params = new URLSearchParams();
+  if (!query) return params;
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    params.set(key, String(value));
+  }
+  return params;
 }
 
 function buildConsoleUrl(
   serverUrl: string,
   path: string,
-  queryString?: URLSearchParams
+  query?: Record<string, ConsoleQueryValue>
 ): string {
   const baseUrl = serverUrl.endsWith('/') ? serverUrl.slice(0, -1) : serverUrl;
+  const queryString = buildQueryString(query);
   const suffix = queryString?.toString();
   return `${baseUrl}${path}${suffix ? `?${suffix}` : ''}`;
 }
 
-export function useStats(
-  options: {
-    refetchIntervalMs?: number;
-    partitionId?: string;
-    instanceId?: string;
-  } = {}
-) {
-  const client = useApiClient();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
-  const query = withInstanceQuery(
-    options.partitionId ? { partitionId: options.partitionId } : {},
-    instanceId
+function requireConnection(
+  connectionConfig: ConnectionConfig | null,
+  isConnected: boolean
+): ConnectionConfig {
+  if (!isConnected || !connectionConfig) throw new Error('Not connected');
+  return connectionConfig;
+}
+
+async function fetchConsoleJson<T>(args: {
+  connectionConfig: ConnectionConfig;
+  path: string;
+  query?: Record<string, ConsoleQueryValue>;
+  method?: 'GET' | 'POST' | 'DELETE';
+  body?: unknown;
+  errorMessage: string;
+}): Promise<T> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${args.connectionConfig.token}`,
+  };
+  if (args.body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+  }
+  const response = await fetch(
+    buildConsoleUrl(args.connectionConfig.serverUrl, args.path, args.query),
+    {
+      method: args.method ?? 'GET',
+      headers,
+      body: args.body === undefined ? undefined : JSON.stringify(args.body),
+    }
+  );
+  if (!response.ok) throw new Error(args.errorMessage);
+  return response.json();
+}
+
+async function fetchConsoleBlob(args: {
+  connectionConfig: ConnectionConfig;
+  path: string;
+  query?: Record<string, ConsoleQueryValue>;
+  errorMessage: string;
+}): Promise<Blob> {
+  const response = await fetch(
+    buildConsoleUrl(args.connectionConfig.serverUrl, args.path, args.query),
+    {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${args.connectionConfig.token}` },
+    }
   );
+  if (!response.ok) throw new Error(args.errorMessage);
+  return response.blob();
+}
+
+function useConsoleJsonQuery<T>(options: {
+  queryKey: QueryKey;
+  path: string;
+  query?: Record<string, ConsoleQueryValue>;
+  method?: 'GET' | 'POST' | 'DELETE';
+  errorMessage: string;
+  enabled?: boolean;
+  refetchInterval?: number | false;
+}) {
+  const { config: connectionConfig, isConnected } = useConnection();
+
+  return useQuery<T>({
+    queryKey: options.queryKey,
+    queryFn: () =>
+      fetchConsoleJson<T>({
+        connectionConfig: requireConnection(connectionConfig, isConnected),
+        path: options.path,
+        query: options.query,
+        method: options.method,
+        errorMessage: options.errorMessage,
+      }),
+    enabled: (options.enabled ?? true) && isConnected && !!connectionConfig,
+    refetchInterval: options.refetchInterval,
+  });
+}
+
+function useConsoleEntityQuery<T>(options: {
+  queryKey: QueryKey;
+  id: string | number | undefined;
+  requiredMessage: string;
+  path: (id: string | number) => string;
+  query?: Record<string, ConsoleQueryValue>;
+  errorMessage: string;
+  enabled?: boolean;
+}) {
+  const { config: connectionConfig, isConnected } = useConnection();
+
+  return useQuery<T>({
+    queryKey: options.queryKey,
+    queryFn: () => {
+      if (options.id === undefined) throw new Error(options.requiredMessage);
+      return fetchConsoleJson<T>({
+        connectionConfig: requireConnection(connectionConfig, isConnected),
+        path: options.path(options.id),
+        query: options.query,
+        errorMessage: options.errorMessage,
+      });
+    },
+    enabled:
+      (options.enabled ?? true) &&
+      options.id !== undefined &&
+      isConnected &&
+      !!connectionConfig,
+  });
+}
+
+function invalidateConsoleQueries(
+  queryClient: ReturnType<typeof useQueryClient>,
+  queryKeysToInvalidate: ReadonlyArray<QueryKey>
+): void {
+  for (const queryKey of queryKeysToInvalidate) {
+    queryClient.invalidateQueries({ queryKey });
+  }
+}
 
-  return useQuery<SyncStats>({
-    queryKey: queryKeys.stats({
+function useEffectiveInstanceId(instanceId?: string): string | undefined {
+  const { instanceId: selectedInstanceId } = useInstanceContext();
+  return instanceId ?? selectedInstanceId;
+}
+
+function useConsoleJsonMutation<TResult, TVariables>(options: {
+  mutationFn: (args: {
+    connectionConfig: ConnectionConfig;
+    variables: TVariables;
+    selectedInstanceId?: string;
+  }) => Promise<TResult>;
+  invalidateQueryKeys?: ReadonlyArray<QueryKey>;
+}) {
+  const { config: connectionConfig, isConnected } = useConnection();
+  const { instanceId: selectedInstanceId } = useInstanceContext();
+  const queryClient = useQueryClient();
+
+  return useMutation<TResult, Error, TVariables>({
+    mutationFn: (variables) =>
+      options.mutationFn({
+        connectionConfig: requireConnection(connectionConfig, isConnected),
+        variables,
+        selectedInstanceId,
+      }),
+    onSuccess: () => {
+      if (!options.invalidateQueryKeys) return;
+      invalidateConsoleQueries(queryClient, options.invalidateQueryKeys);
+    },
+  });
+}
+
+export function useStats(
+  options: StatsParams & { refetchIntervalMs?: number } = {}
+) {
+  const instanceId = useEffectiveInstanceId(options.instanceId);
+  return useConsoleJsonQuery<SyncStats>({
+    queryKey: queryKeys.stats({ partitionId: options.partitionId, instanceId }),
+    path: '/console/stats',
+    query: {
       partitionId: options.partitionId,
       instanceId,
-    }),
-    queryFn: () => {
-      if (!client) throw new Error('Not connected');
-      return unwrap(client.GET('/console/stats', { params: { query } }));
     },
-    enabled: !!client,
+    errorMessage: 'Failed to fetch stats',
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 5000),
   });
 }
 
 export function useTimeseriesStats(
-  params: {
-    interval?: TimeseriesInterval;
-    range?: TimeseriesRange;
-    partitionId?: string;
-    instanceId?: string;
-  } = {},
-  options: { refetchIntervalMs?: number; enabled?: boolean } = {}
+  params: TimeseriesParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(params.instanceId);
 
-  return useQuery<TimeseriesStatsResponse>({
+  return useConsoleJsonQuery<TimeseriesStatsResponse>({
     queryKey: queryKeys.timeseries({ ...params, instanceId }),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      // Use fetch directly since this endpoint may not be in OpenAPI yet
-      const queryString = new URLSearchParams();
-      if (params.interval) queryString.set('interval', params.interval);
-      if (params.range) queryString.set('range', params.range);
-      if (params.partitionId)
-        queryString.set('partitionId', params.partitionId);
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        `${connectionConfig.serverUrl}/console/stats/timeseries?${queryString}`,
-        { headers: { Authorization: `Bearer ${connectionConfig.token}` } }
-      );
-      if (!response.ok) throw new Error('Failed to fetch timeseries stats');
-      return response.json();
+    path: '/console/stats/timeseries',
+    query: {
+      interval: params.interval,
+      range: params.range,
+      partitionId: params.partitionId,
+      instanceId,
     },
-    enabled: (options.enabled ?? true) && !!client && !!connectionConfig,
+    errorMessage: 'Failed to fetch timeseries stats',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 30000),
   });
 }
 
 export function useLatencyStats(
-  params: {
-    range?: TimeseriesRange;
-    partitionId?: string;
-    instanceId?: string;
-  } = {},
-  options: { refetchIntervalMs?: number; enabled?: boolean } = {}
+  params: LatencyParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(params.instanceId);
 
-  return useQuery<LatencyStatsResponse>({
+  return useConsoleJsonQuery<LatencyStatsResponse>({
     queryKey: queryKeys.latency({ ...params, instanceId }),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      // Use fetch directly since this endpoint may not be in OpenAPI yet
-      const queryString = new URLSearchParams();
-      if (params.range) queryString.set('range', params.range);
-      if (params.partitionId)
-        queryString.set('partitionId', params.partitionId);
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        `${connectionConfig.serverUrl}/console/stats/latency?${queryString}`,
-        { headers: { Authorization: `Bearer ${connectionConfig.token}` } }
-      );
-      if (!response.ok) throw new Error('Failed to fetch latency stats');
-      return response.json();
+    path: '/console/stats/latency',
+    query: {
+      range: params.range,
+      partitionId: params.partitionId,
+      instanceId,
     },
-    enabled: (options.enabled ?? true) && !!client && !!connectionConfig,
+    errorMessage: 'Failed to fetch latency stats',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 30000),
   });
 }
 
 export function useCommits(
-  params: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-  } = {},
-  options: { refetchIntervalMs?: number; enabled?: boolean } = {}
+  params: ListParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
-  const query = withInstanceQuery(
-    {
+  const instanceId = useEffectiveInstanceId(params.instanceId);
+
+  return useConsoleJsonQuery<PaginatedResponse<ConsoleCommitListItem>>({
+    queryKey: queryKeys.commits({ ...params, instanceId }),
+    path: '/console/commits',
+    query: {
       limit: params.limit,
       offset: params.offset,
       partitionId: params.partitionId,
+      instanceId,
     },
-    instanceId
-  );
-
-  return useQuery<PaginatedResponse<ConsoleCommitListItem>>({
-    queryKey: queryKeys.commits({ ...params, instanceId }),
-    queryFn: () => {
-      if (!client) throw new Error('Not connected');
-      return unwrap(client.GET('/console/commits', { params: { query } }));
-    },
-    enabled: (options.enabled ?? true) && !!client,
+    errorMessage: 'Failed to fetch commits',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 10000),
   });
 }
 
 export function useCommitDetail(
   seq: string | number | undefined,
-  options: { enabled?: boolean; partitionId?: string; instanceId?: string } = {}
+  options: EntityLookupOptions = {}
 ) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(options.instanceId);
 
-  return useQuery<ConsoleCommitDetail>({
+  return useConsoleEntityQuery<ConsoleCommitDetail>({
     queryKey: queryKeys.commitDetail(seq, options.partitionId, instanceId),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      if (seq === undefined) throw new Error('Commit sequence is required');
-      const queryString = new URLSearchParams();
-      if (options.partitionId)
-        queryString.set('partitionId', options.partitionId);
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const suffix = queryString.toString();
-      const response = await fetch(
-        `${connectionConfig.serverUrl}/console/commits/${serializePathSegment(seq)}${suffix ? `?${suffix}` : ''}`,
-        { headers: { Authorization: `Bearer ${connectionConfig.token}` } }
-      );
-      if (!response.ok) throw new Error('Failed to fetch commit detail');
-      return response.json();
+    id: seq,
+    requiredMessage: 'Commit sequence is required',
+    path: (value) => `/console/commits/${encodeURIComponent(String(value))}`,
+    query: {
+      partitionId: options.partitionId,
+      instanceId,
     },
-    enabled: (options.enabled ?? true) && seq !== undefined && !!client,
+    errorMessage: 'Failed to fetch commit detail',
+    enabled: options.enabled,
   });
 }
 
 export function useTimeline(
-  params: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-    view?: 'all' | 'commits' | 'events';
-    eventType?: 'push' | 'pull';
-    actorId?: string;
-    clientId?: string;
-    requestId?: string;
-    traceId?: string;
-    table?: string;
-    outcome?: string;
-    search?: string;
-    from?: string;
-    to?: string;
-  } = {},
-  options: { refetchIntervalMs?: number; enabled?: boolean } = {}
+  params: TimelineParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
-  const query = withInstanceQuery(
-    {
+  const instanceId = useEffectiveInstanceId(params.instanceId);
+
+  return useConsoleJsonQuery<PaginatedResponse<ConsoleTimelineItem>>({
+    queryKey: queryKeys.timeline({ ...params, instanceId }),
+    path: '/console/timeline',
+    query: {
       limit: params.limit,
       offset: params.offset,
       partitionId: params.partitionId,
@@ -345,586 +451,322 @@ export function useTimeline(
       search: params.search,
       from: params.from,
       to: params.to,
+      instanceId,
     },
-    instanceId
-  );
-
-  return useQuery<PaginatedResponse<ConsoleTimelineItem>>({
-    queryKey: queryKeys.timeline({ ...params, instanceId }),
-    queryFn: () => {
-      if (!client) throw new Error('Not connected');
-      return unwrap(client.GET('/console/timeline', { params: { query } }));
-    },
-    enabled: (options.enabled ?? true) && !!client,
+    errorMessage: 'Failed to fetch timeline',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 10000),
   });
 }
 
 export function useClients(
-  params: {
-    limit?: number;
-    offset?: number;
-    partitionId?: string;
-    instanceId?: string;
-  } = {},
-  options: { refetchIntervalMs?: number; enabled?: boolean } = {}
+  params: ListParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
-  const query = withInstanceQuery(
-    {
+  const instanceId = useEffectiveInstanceId(params.instanceId);
+
+  return useConsoleJsonQuery<PaginatedResponse<ConsoleClient>>({
+    queryKey: queryKeys.clients({ ...params, instanceId }),
+    path: '/console/clients',
+    query: {
       limit: params.limit,
       offset: params.offset,
       partitionId: params.partitionId,
+      instanceId,
     },
-    instanceId
-  );
-
-  return useQuery<PaginatedResponse<ConsoleClient>>({
-    queryKey: queryKeys.clients({ ...params, instanceId }),
-    queryFn: () => {
-      if (!client) throw new Error('Not connected');
-      return unwrap(client.GET('/console/clients', { params: { query } }));
-    },
-    enabled: (options.enabled ?? true) && !!client,
+    errorMessage: 'Failed to fetch clients',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 10000),
   });
 }
 
 export function useRequestEventDetail(
   id: string | number | undefined,
-  options: { enabled?: boolean; partitionId?: string; instanceId?: string } = {}
+  options: EntityLookupOptions = {}
 ) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(options.instanceId);
 
-  return useQuery<ConsoleRequestEvent>({
+  return useConsoleEntityQuery<ConsoleRequestEvent>({
     queryKey: queryKeys.eventDetail(id, options.partitionId, instanceId),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      if (id === undefined) throw new Error('Event id is required');
-      const queryString = new URLSearchParams();
-      if (options.partitionId)
-        queryString.set('partitionId', options.partitionId);
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const suffix = queryString.toString();
-      const response = await fetch(
-        `${connectionConfig.serverUrl}/console/events/${serializePathSegment(id)}${suffix ? `?${suffix}` : ''}`,
-        { headers: { Authorization: `Bearer ${connectionConfig.token}` } }
-      );
-      if (!response.ok) throw new Error('Failed to fetch event detail');
-      return response.json();
+    id,
+    requiredMessage: 'Event id is required',
+    path: (value) => `/console/events/${encodeURIComponent(String(value))}`,
+    query: {
+      partitionId: options.partitionId,
+      instanceId,
     },
-    enabled: (options.enabled ?? true) && id !== undefined && !!client,
+    errorMessage: 'Failed to fetch event detail',
+    enabled: options.enabled,
   });
 }
 
 export function useRequestEventPayload(
   id: string | number | undefined,
-  options: { enabled?: boolean; partitionId?: string; instanceId?: string } = {}
+  options: EntityLookupOptions = {}
 ) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(options.instanceId);
 
-  return useQuery<ConsoleRequestPayload>({
+  return useConsoleEntityQuery<ConsoleRequestPayload>({
     queryKey: queryKeys.eventPayload(id, options.partitionId, instanceId),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      if (id === undefined) throw new Error('Event id is required');
-      const queryString = new URLSearchParams();
-      if (options.partitionId)
-        queryString.set('partitionId', options.partitionId);
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const suffix = queryString.toString();
-      const response = await fetch(
-        `${connectionConfig.serverUrl}/console/events/${serializePathSegment(id)}/payload${suffix ? `?${suffix}` : ''}`,
-        { headers: { Authorization: `Bearer ${connectionConfig.token}` } }
-      );
-      if (!response.ok) throw new Error('Failed to fetch event payload');
-      return response.json();
+    id,
+    requiredMessage: 'Event id is required',
+    path: (value) =>
+      `/console/events/${encodeURIComponent(String(value))}/payload`,
+    query: {
+      partitionId: options.partitionId,
+      instanceId,
     },
-    enabled: (options.enabled ?? true) && id !== undefined && !!client,
+    errorMessage: 'Failed to fetch event payload',
+    enabled: options.enabled,
   });
 }
 
 export function useHandlers(options: { instanceId?: string } = {}) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
+  const instanceId = useEffectiveInstanceId(options.instanceId);
 
-  return useQuery<{ items: ConsoleHandler[] }>({
+  return useConsoleJsonQuery<{ items: ConsoleHandler[] }>({
     queryKey: queryKeys.handlers(instanceId),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/handlers',
-          queryString
-        ),
-        {
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to fetch handlers');
-      return response.json();
-    },
-    enabled: !!client && !!connectionConfig,
+    path: '/console/handlers',
+    query: { instanceId },
+    errorMessage: 'Failed to fetch handlers',
   });
 }
 
-export function usePrunePreview(
-  options: { enabled?: boolean; instanceId?: string } = {}
-) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = options.instanceId ?? selectedInstanceId;
+export function usePrunePreview(options: PrunePreviewOptions = {}) {
+  const instanceId = useEffectiveInstanceId(options.instanceId);
 
-  return useQuery<{ watermarkCommitSeq: number; commitsToDelete: number }>({
+  return useConsoleJsonQuery<{
+    watermarkCommitSeq: number;
+    commitsToDelete: number;
+  }>({
     queryKey: queryKeys.prunePreview(instanceId),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/prune/preview',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to fetch prune preview');
-      return response.json();
-    },
-    enabled: !!client && !!connectionConfig && (options.enabled ?? true),
+    path: '/console/prune/preview',
+    query: { instanceId },
+    method: 'POST',
+    errorMessage: 'Failed to fetch prune preview',
+    enabled: options.enabled,
   });
 }
 
 export function useOperationEvents(
-  params: {
-    limit?: number;
-    offset?: number;
-    operationType?: ConsoleOperationType;
-    partitionId?: string;
-    instanceId?: string;
-  } = {},
-  options: { enabled?: boolean; refetchIntervalMs?: number } = {}
+  params: OperationEventsParams = {},
+  options: RefetchableQueryOptions = {}
 ) {
-  const client = useApiClient();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
-  const query = withInstanceQuery(
-    {
+  const instanceId = useEffectiveInstanceId(params.instanceId);
+
+  return useConsoleJsonQuery<PaginatedResponse<ConsoleOperationEvent>>({
+    queryKey: queryKeys.operations({ ...params, instanceId }),
+    path: '/console/operations',
+    query: {
       limit: params.limit,
       offset: params.offset,
       operationType: params.operationType,
       partitionId: params.partitionId,
+      instanceId,
     },
-    instanceId
-  );
-
-  return useQuery<PaginatedResponse<ConsoleOperationEvent>>({
-    queryKey: queryKeys.operations({ ...params, instanceId }),
-    queryFn: () => {
-      if (!client) throw new Error('Not connected');
-      return unwrap(client.GET('/console/operations', { params: { query } }));
-    },
-    enabled: (options.enabled ?? true) && !!client,
+    errorMessage: 'Failed to fetch operations',
+    enabled: options.enabled,
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 10000),
   });
 }
 
-export function useEvictClientMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
+export function useClearEventsMutation() {
+  return useConsoleJsonMutation<{ deletedCount: number }, void>({
+    mutationFn: async ({ connectionConfig, selectedInstanceId }) =>
+      fetchConsoleJson<{ deletedCount: number }>({
+        connectionConfig,
+        path: '/console/events',
+        query: { instanceId: selectedInstanceId },
+        method: 'DELETE',
+        errorMessage: 'Failed to clear events',
+      }),
+    invalidateQueryKeys: [['console', 'events']],
+  });
+}
 
-  return useMutation<
-    { evicted: boolean },
-    Error,
-    { clientId: string; partitionId?: string; instanceId?: string }
-  >({
-    mutationFn: async ({ clientId, partitionId, instanceId }) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const effectiveInstanceId = instanceId ?? selectedInstanceId;
-      const queryString = new URLSearchParams();
-      if (partitionId) queryString.set('partitionId', partitionId);
-      if (effectiveInstanceId)
-        queryString.set('instanceId', effectiveInstanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          `/console/clients/${serializePathSegment(clientId)}`,
-          queryString
-        ),
-        {
-          method: 'DELETE',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to evict client');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'clients'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'stats'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'operations'] });
+export function useEvictClientMutation() {
+  return useConsoleJsonMutation<{ evicted: boolean }, EvictClientRequest>({
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      const effectiveInstanceId = variables.instanceId ?? selectedInstanceId;
+      return fetchConsoleJson<{ evicted: boolean }>({
+        connectionConfig,
+        path: `/console/clients/${encodeURIComponent(variables.clientId)}`,
+        query: {
+          partitionId: variables.partitionId,
+          instanceId: effectiveInstanceId,
+        },
+        method: 'DELETE',
+        errorMessage: 'Failed to evict client',
+      });
     },
+    invalidateQueryKeys: [
+      ['console', 'clients'],
+      ['console', 'stats'],
+      ['console', 'operations'],
+    ],
   });
 }
 
 export function usePruneMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<{ deletedCommits: number }, Error, void>({
-    mutationFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/prune',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to prune');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'stats'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'commits'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'timeline'] });
-      queryClient.invalidateQueries({
-        queryKey: ['console', 'prune', 'preview'],
-      });
-      queryClient.invalidateQueries({ queryKey: ['console', 'operations'] });
-    },
+  return useConsoleJsonMutation<{ deletedCommits: number }, void>({
+    mutationFn: async ({ connectionConfig, selectedInstanceId }) =>
+      fetchConsoleJson<{ deletedCommits: number }>({
+        connectionConfig,
+        path: '/console/prune',
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        errorMessage: 'Failed to prune',
+      }),
+    invalidateQueryKeys: [
+      ['console', 'stats'],
+      ['console', 'commits'],
+      ['console', 'timeline'],
+      ['console', 'prune', 'preview'],
+      ['console', 'operations'],
+    ],
   });
 }
 
 export function useCompactMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<{ deletedChanges: number }, Error, void>({
-    mutationFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/compact',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to compact');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'stats'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'operations'] });
-    },
+  return useConsoleJsonMutation<{ deletedChanges: number }, void>({
+    mutationFn: async ({ connectionConfig, selectedInstanceId }) =>
+      fetchConsoleJson<{ deletedChanges: number }>({
+        connectionConfig,
+        path: '/console/compact',
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        errorMessage: 'Failed to compact',
+      }),
+    invalidateQueryKeys: [
+      ['console', 'stats'],
+      ['console', 'operations'],
+    ],
   });
 }
 
 export function useNotifyDataChangeMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<
+  return useConsoleJsonMutation<
     ConsoleNotifyDataChangeResponse,
-    Error,
-    { tables: string[]; partitionId?: string; instanceId?: string }
+    NotifyDataChangeRequest
   >({
-    mutationFn: async (request) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const effectiveInstanceId = request.instanceId ?? selectedInstanceId;
-      const queryString = new URLSearchParams();
-      if (effectiveInstanceId)
-        queryString.set('instanceId', effectiveInstanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/notify-data-change',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${connectionConfig.token}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify({
-            tables: request.tables,
-            partitionId: request.partitionId,
-          }),
-        }
-      );
-      if (!response.ok) throw new Error('Failed to notify data change');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'stats'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'commits'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'timeline'] });
-      queryClient.invalidateQueries({ queryKey: ['console', 'operations'] });
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      const effectiveInstanceId = variables.instanceId ?? selectedInstanceId;
+      return fetchConsoleJson<ConsoleNotifyDataChangeResponse>({
+        connectionConfig,
+        path: '/console/notify-data-change',
+        query: { instanceId: effectiveInstanceId },
+        method: 'POST',
+        body: {
+          tables: variables.tables,
+          partitionId: variables.partitionId,
+        },
+        errorMessage: 'Failed to notify data change',
+      });
     },
+    invalidateQueryKeys: [
+      ['console', 'stats'],
+      ['console', 'commits'],
+      ['console', 'timeline'],
+      ['console', 'operations'],
+    ],
   });
 }
 
-export function useApiKeys(
-  params: {
-    limit?: number;
-    offset?: number;
-    type?: 'relay' | 'proxy' | 'admin';
-    status?: 'active' | 'revoked' | 'expiring';
-    expiresWithinDays?: number;
-    instanceId?: string;
-  } = {}
-) {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId: selectedInstanceId } = useInstanceContext();
-  const instanceId = params.instanceId ?? selectedInstanceId;
+export function useApiKeys(params: ApiKeysParams = {}) {
+  const instanceId = useEffectiveInstanceId(params.instanceId);
 
-  return useQuery<PaginatedResponse<ConsoleApiKey>>({
+  return useConsoleJsonQuery<PaginatedResponse<ConsoleApiKey>>({
     queryKey: queryKeys.apiKeys({ ...params, instanceId }),
-    queryFn: async () => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (params.limit !== undefined)
-        queryString.set('limit', String(params.limit));
-      if (params.offset !== undefined)
-        queryString.set('offset', String(params.offset));
-      if (params.type) queryString.set('type', params.type);
-      if (params.status) queryString.set('status', params.status);
-      if (params.expiresWithinDays !== undefined) {
-        queryString.set('expiresWithinDays', String(params.expiresWithinDays));
-      }
-      if (instanceId) queryString.set('instanceId', instanceId);
-
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/api-keys',
-          queryString
-        ),
-        {
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to fetch API keys');
-      return response.json();
+    path: '/console/api-keys',
+    query: {
+      limit: params.limit,
+      offset: params.offset,
+      type: params.type,
+      status: params.status,
+      expiresWithinDays: params.expiresWithinDays,
+      instanceId,
     },
-    enabled: !!client && !!connectionConfig,
+    errorMessage: 'Failed to fetch API keys',
   });
 }
 
 export function useCreateApiKeyMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<
-    { key: ConsoleApiKey; secretKey: string },
-    Error,
-    {
-      name: string;
-      keyType: 'relay' | 'proxy' | 'admin';
-      scopeKeys?: string[];
-      actorId?: string;
-      expiresInDays?: number;
-    }
-  >({
-    mutationFn: async (request) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/api-keys',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${connectionConfig.token}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify(request),
-        }
-      );
-      if (!response.ok) throw new Error('Failed to create API key');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'api-keys'] });
+  return useConsoleJsonMutation<ApiKeySecretResponse, CreateApiKeyRequest>({
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      return fetchConsoleJson<ApiKeySecretResponse>({
+        connectionConfig,
+        path: '/console/api-keys',
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        body: variables,
+        errorMessage: 'Failed to create API key',
+      });
     },
+    invalidateQueryKeys: [['console', 'api-keys']],
   });
 }
 
 export function useRevokeApiKeyMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<{ revoked: boolean }, Error, string>({
-    mutationFn: async (keyId) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          `/console/api-keys/${serializePathSegment(keyId)}`,
-          queryString
-        ),
-        {
-          method: 'DELETE',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to revoke API key');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'api-keys'] });
+  return useConsoleJsonMutation<{ revoked: boolean }, string>({
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      return fetchConsoleJson<{ revoked: boolean }>({
+        connectionConfig,
+        path: `/console/api-keys/${encodeURIComponent(variables)}`,
+        query: { instanceId: selectedInstanceId },
+        method: 'DELETE',
+        errorMessage: 'Failed to revoke API key',
+      });
     },
+    invalidateQueryKeys: [['console', 'api-keys']],
   });
 }
 
 export function useBulkRevokeApiKeysMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<
+  return useConsoleJsonMutation<
     ConsoleApiKeyBulkRevokeResponse,
-    Error,
     { keyIds: string[] }
   >({
-    mutationFn: async (request) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/api-keys/bulk-revoke',
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: {
-            Authorization: `Bearer ${connectionConfig.token}`,
-            'Content-Type': 'application/json',
-          },
-          body: JSON.stringify(request),
-        }
-      );
-      if (!response.ok) throw new Error('Failed to bulk revoke API keys');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'api-keys'] });
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      return fetchConsoleJson<ConsoleApiKeyBulkRevokeResponse>({
+        connectionConfig,
+        path: '/console/api-keys/bulk-revoke',
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        body: variables,
+        errorMessage: 'Failed to bulk revoke API keys',
+      });
     },
+    invalidateQueryKeys: [['console', 'api-keys']],
   });
 }
 
 export function useRotateApiKeyMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<{ key: ConsoleApiKey; secretKey: string }, Error, string>({
-    mutationFn: async (keyId) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          `/console/api-keys/${serializePathSegment(keyId)}/rotate`,
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to rotate API key');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'api-keys'] });
+  return useConsoleJsonMutation<ApiKeySecretResponse, string>({
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      return fetchConsoleJson<ApiKeySecretResponse>({
+        connectionConfig,
+        path: `/console/api-keys/${encodeURIComponent(variables)}/rotate`,
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        errorMessage: 'Failed to rotate API key',
+      });
     },
+    invalidateQueryKeys: [['console', 'api-keys']],
   });
 }
 
 export function useStageRotateApiKeyMutation() {
-  const client = useApiClient();
-  const { config: connectionConfig } = useConnection();
-  const { instanceId } = useInstanceContext();
-  const queryClient = useQueryClient();
-
-  return useMutation<{ key: ConsoleApiKey; secretKey: string }, Error, string>({
-    mutationFn: async (keyId) => {
-      if (!client || !connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (instanceId) queryString.set('instanceId', instanceId);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          `/console/api-keys/${serializePathSegment(keyId)}/rotate/stage`,
-          queryString
-        ),
-        {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to stage-rotate API key');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'api-keys'] });
+  return useConsoleJsonMutation<ApiKeySecretResponse, string>({
+    mutationFn: async ({ connectionConfig, variables, selectedInstanceId }) => {
+      return fetchConsoleJson<ApiKeySecretResponse>({
+        connectionConfig,
+        path: `/console/api-keys/${encodeURIComponent(variables)}/rotate/stage`,
+        query: { instanceId: selectedInstanceId },
+        method: 'POST',
+        errorMessage: 'Failed to stage-rotate API key',
+      });
     },
+    invalidateQueryKeys: [['console', 'api-keys']],
   });
 }
 
@@ -932,91 +774,45 @@ export function useStageRotateApiKeyMutation() {
 // Blob storage hooks
 // ---------------------------------------------------------------------------
 
-export function useBlobs(
-  options: {
-    prefix?: string;
-    cursor?: string;
-    limit?: number;
-    refetchIntervalMs?: number;
-  } = {}
-) {
-  const { config: connectionConfig } = useConnection();
-  return useQuery<ConsoleBlobListResponse>({
+export function useBlobs(options: BlobsOptions = {}) {
+  return useConsoleJsonQuery<ConsoleBlobListResponse>({
     queryKey: queryKeys.storage({
       prefix: options.prefix,
       cursor: options.cursor,
       limit: options.limit,
     }),
-    queryFn: async () => {
-      if (!connectionConfig) throw new Error('Not connected');
-      const queryString = new URLSearchParams();
-      if (options.prefix) queryString.set('prefix', options.prefix);
-      if (options.cursor) queryString.set('cursor', options.cursor);
-      if (options.limit) queryString.set('limit', String(options.limit));
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          '/console/storage',
-          queryString
-        ),
-        {
-          method: 'GET',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to list blobs');
-      return response.json();
+    path: '/console/storage',
+    query: {
+      prefix: options.prefix,
+      cursor: options.cursor,
+      limit: options.limit,
     },
-    enabled: !!connectionConfig,
+    errorMessage: 'Failed to list blobs',
     refetchInterval: resolveRefetchInterval(options.refetchIntervalMs, 30000),
   });
 }
 
 export function useDeleteBlobMutation() {
-  const { config: connectionConfig } = useConnection();
-  const queryClient = useQueryClient();
-  return useMutation<{ deleted: boolean }, Error, string>({
-    mutationFn: async (key: string) => {
-      if (!connectionConfig) throw new Error('Not connected');
-      const encodedKey = encodeURIComponent(key);
-      const response = await fetch(
-        buildConsoleUrl(
-          connectionConfig.serverUrl,
-          `/console/storage/${encodedKey}`,
-          new URLSearchParams()
-        ),
-        {
-          method: 'DELETE',
-          headers: { Authorization: `Bearer ${connectionConfig.token}` },
-        }
-      );
-      if (!response.ok) throw new Error('Failed to delete blob');
-      return response.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['console', 'storage'] });
-    },
+  return useConsoleJsonMutation<{ deleted: boolean }, string>({
+    mutationFn: async ({ connectionConfig, variables }) =>
+      fetchConsoleJson<{ deleted: boolean }>({
+        connectionConfig,
+        path: `/console/storage/${encodeURIComponent(variables)}`,
+        method: 'DELETE',
+        errorMessage: 'Failed to delete blob',
+      }),
+    invalidateQueryKeys: [['console', 'storage']],
   });
 }
 
 export function useBlobDownload() {
-  const { config: connectionConfig } = useConnection();
+  const { config: connectionConfig, isConnected } = useConnection();
   return async (key: string) => {
-    if (!connectionConfig) throw new Error('Not connected');
-    const encodedKey = encodeURIComponent(key);
-    const response = await fetch(
-      buildConsoleUrl(
-        connectionConfig.serverUrl,
-        `/console/storage/${encodedKey}/download`,
-        new URLSearchParams()
-      ),
-      {
-        method: 'GET',
-        headers: { Authorization: `Bearer ${connectionConfig.token}` },
-      }
-    );
-    if (!response.ok) throw new Error('Failed to download blob');
-    const blob = await response.blob();
+    const blob = await fetchConsoleBlob({
+      connectionConfig: requireConnection(connectionConfig, isConnected),
+      path: `/console/storage/${encodeURIComponent(key)}/download`,
+      errorMessage: 'Failed to download blob',
+    });
     const url = URL.createObjectURL(blob);
     const a = document.createElement('a');
     a.href = url;