@nextclaw/ui 0.12.20-beta.0 → 0.12.20-beta.2

package/src/shared/lib/api/services/config.service.ts

@@ -0,0 +1,171 @@
+import { nextclawClient } from './client.service';
+import type {
+  AuthEnabledUpdateRequest,
+  AuthLoginRequest,
+  AuthPasswordUpdateRequest,
+  AuthSetupRequest,
+  AuthStatusView,
+  AppMetaView,
+  BootstrapStatusView,
+  ConfigView,
+  ConfigMetaView,
+  ConfigSchemaResponse,
+  ProviderConfigView,
+  ChannelConfigUpdate,
+  ProviderConfigUpdate,
+  ProviderConnectionTestRequest,
+  ProviderConnectionTestResult,
+  ProviderAuthStartRequest,
+  ProviderAuthStartResult,
+  ProviderAuthPollRequest,
+  ProviderAuthPollResult,
+  ProviderAuthImportResult,
+  SearchConfigUpdate,
+  SearchConfigView,
+  ProviderCreateRequest,
+  ProviderCreateResult,
+  ProviderDeleteResult,
+  RuntimeConfigUpdate,
+  SecretsConfigUpdate,
+  SecretsView,
+  ConfigActionExecuteRequest,
+  ConfigActionExecuteResult,
+  ChatSessionTypesView,
+  CronListView,
+  CronEnableRequest,
+  CronRunRequest,
+  CronActionResult
+} from '@/shared/lib/api/types';
+
+export async function fetchAuthStatus(options: { timeoutMs?: number } = {}): Promise<AuthStatusView> {
+  return await nextclawClient.auth.fetchStatus({ timeoutMs: options.timeoutMs ?? 5_000 });
+}
+
+export async function setupAuth(data: AuthSetupRequest): Promise<AuthStatusView> {
+  return await nextclawClient.auth.setup(data);
+}
+
+export async function loginAuth(data: AuthLoginRequest): Promise<AuthStatusView> {
+  return await nextclawClient.auth.login(data);
+}
+
+export async function logoutAuth(): Promise<{ success: boolean }> {
+  return await nextclawClient.auth.logout();
+}
+
+export async function updateAuthPassword(data: AuthPasswordUpdateRequest): Promise<AuthStatusView> {
+  return await nextclawClient.auth.updatePassword(data);
+}
+
+export async function updateAuthEnabled(data: AuthEnabledUpdateRequest): Promise<AuthStatusView> {
+  return await nextclawClient.auth.updateEnabled(data);
+}
+
+export async function fetchAppMeta(): Promise<AppMetaView> {
+  return await nextclawClient.app.fetchMeta();
+}
+
+export async function fetchBootstrapStatus(): Promise<BootstrapStatusView> {
+  return await nextclawClient.app.fetchBootstrapStatus();
+}
+
+export async function fetchConfig(): Promise<ConfigView> {
+  return await nextclawClient.config.fetch();
+}
+
+export async function fetchConfigMeta(): Promise<ConfigMetaView> {
+  return await nextclawClient.config.fetchMeta();
+}
+
+export async function fetchConfigSchema(): Promise<ConfigSchemaResponse> {
+  return await nextclawClient.config.fetchSchema();
+}
+
+export async function updateModel(data: { model: string; workspace?: string }): Promise<{ model: string; workspace?: string }> {
+  return await nextclawClient.config.updateModel(data);
+}
+
+export async function updateSearch(data: SearchConfigUpdate): Promise<SearchConfigView> {
+  return await nextclawClient.config.updateSearch(data);
+}
+
+export async function updateProvider(provider: string, data: ProviderConfigUpdate): Promise<ProviderConfigView> {
+  return await nextclawClient.config.updateProvider(provider, data);
+}
+
+export async function createProvider(data: ProviderCreateRequest = {}): Promise<ProviderCreateResult> {
+  return await nextclawClient.config.createProvider(data);
+}
+
+export async function deleteProvider(provider: string): Promise<ProviderDeleteResult> {
+  return await nextclawClient.config.deleteProvider(provider);
+}
+
+export async function testProviderConnection(
+  provider: string,
+  data: ProviderConnectionTestRequest
+): Promise<ProviderConnectionTestResult> {
+  return await nextclawClient.config.testProviderConnection(provider, data);
+}
+
+export async function startProviderAuth(
+  provider: string,
+  data: ProviderAuthStartRequest = {}
+): Promise<ProviderAuthStartResult> {
+  return await nextclawClient.config.startProviderAuth(provider, data);
+}
+
+export async function pollProviderAuth(
+  provider: string,
+  data: ProviderAuthPollRequest
+): Promise<ProviderAuthPollResult> {
+  return await nextclawClient.config.pollProviderAuth(provider, data);
+}
+
+export async function importProviderAuthFromCli(provider: string): Promise<ProviderAuthImportResult> {
+  return await nextclawClient.config.importProviderAuthFromCli(provider);
+}
+
+export async function updateChannel(
+  channel: string,
+  data: ChannelConfigUpdate
+): Promise<Record<string, unknown>> {
+  return await nextclawClient.config.updateChannel(channel, data);
+}
+
+export async function updateRuntime(
+  data: RuntimeConfigUpdate
+): Promise<Pick<ConfigView, 'agents' | 'bindings' | 'session'>> {
+  return await nextclawClient.config.updateRuntime(data) as Pick<ConfigView, 'agents' | 'bindings' | 'session'>;
+}
+
+export async function updateSecrets(data: SecretsConfigUpdate): Promise<SecretsView> {
+  return await nextclawClient.config.updateSecrets(data);
+}
+
+export async function executeConfigAction(
+  actionId: string,
+  data: ConfigActionExecuteRequest
+): Promise<ConfigActionExecuteResult> {
+  return await nextclawClient.config.executeAction(actionId, data);
+}
+
+export async function fetchNcpChatSessionTypes(): Promise<ChatSessionTypesView> {
+  return await nextclawClient.config.fetchChatSessionTypes();
+}
+
+export async function fetchCronJobs(params?: { all?: boolean }): Promise<CronListView> {
+  return await nextclawClient.config.fetchCronJobs(params);
+}
+
+export async function deleteCronJob(id: string): Promise<{ deleted: boolean }> {
+  return await nextclawClient.config.deleteCronJob(id);
+}
+
+export async function setCronJobEnabled(id: string, data: CronEnableRequest): Promise<CronActionResult> {
+  return await nextclawClient.config.setCronJobEnabled(id, data);
+}
+
+export async function runCronJob(id: string, data: CronRunRequest): Promise<CronActionResult> {
+  return await nextclawClient.config.runCronJob(id, data);
+}

package/src/shared/lib/api/services/marketplace.service.ts

@@ -0,0 +1,66 @@
+import { nextclawClient } from './client.service';
+import type {
+  MarketplaceInstallRequest,
+  MarketplaceInstallResult,
+  MarketplaceManageRequest,
+  MarketplaceManageResult,
+  MarketplaceInstalledView,
+  MarketplacePluginContentView,
+  MarketplaceItemType,
+  MarketplaceSkillContentView,
+  MarketplaceItemView,
+  MarketplaceListView,
+  MarketplaceRecommendationView,
+  MarketplaceSort
+} from '@/shared/lib/api/types';
+
+export type MarketplaceListParams = {
+  type: MarketplaceItemType;
+  q?: string;
+  tag?: string;
+  sort?: MarketplaceSort;
+  page?: number;
+  pageSize?: number;
+};
+
+export async function fetchMarketplaceItems(params: MarketplaceListParams): Promise<MarketplaceListView> {
+  return await nextclawClient.marketplace.fetchItems(params);
+}
+
+export async function fetchMarketplaceItem(slug: string, type: MarketplaceItemType): Promise<MarketplaceItemView> {
+  return await nextclawClient.marketplace.fetchItem(slug, type);
+}
+
+export async function fetchMarketplaceSkillContent(slug: string): Promise<MarketplaceSkillContentView> {
+  return await nextclawClient.marketplace.fetchSkillContent(slug);
+}
+
+export async function fetchMarketplacePluginContent(slug: string): Promise<MarketplacePluginContentView> {
+  return await nextclawClient.marketplace.fetchPluginContent(slug);
+}
+
+export async function fetchMarketplaceRecommendations(
+  type: MarketplaceItemType,
+  params: {
+    scene?: string;
+    limit?: number;
+  } = {}
+): Promise<MarketplaceRecommendationView> {
+  return await nextclawClient.marketplace.fetchRecommendations(type, params);
+}
+
+export async function installMarketplaceItem(request: MarketplaceInstallRequest): Promise<MarketplaceInstallResult> {
+  return await nextclawClient.marketplace.install(
+    request as Parameters<typeof nextclawClient.marketplace.install>[0]
+  ) as MarketplaceInstallResult;
+}
+
+export async function fetchMarketplaceInstalled(type: MarketplaceItemType): Promise<MarketplaceInstalledView> {
+  return await nextclawClient.marketplace.fetchInstalled(type);
+}
+
+export async function manageMarketplaceItem(request: MarketplaceManageRequest): Promise<MarketplaceManageResult> {
+  return await nextclawClient.marketplace.manage(
+    request as Parameters<typeof nextclawClient.marketplace.manage>[0]
+  ) as MarketplaceManageResult;
+}

package/src/shared/lib/api/services/mcp-marketplace.service.ts

@@ -0,0 +1,70 @@
+import { nextclawClient } from './client.service';
+import type {
+  MarketplaceInstalledView,
+  MarketplaceItemView,
+  MarketplaceListView,
+  MarketplaceMcpContentView,
+  MarketplaceMcpDoctorResult,
+  MarketplaceRecommendationView,
+  MarketplaceSort
+} from '@/shared/lib/api/types';
+
+export type McpMarketplaceListParams = {
+  q?: string;
+  tag?: string;
+  sort?: MarketplaceSort;
+  page?: number;
+  pageSize?: number;
+};
+
+export async function fetchMcpMarketplaceItems(params: McpMarketplaceListParams): Promise<MarketplaceListView> {
+  return await nextclawClient.mcpMarketplace.fetchItems(params);
+}
+
+export async function fetchMcpMarketplaceInstalled(): Promise<MarketplaceInstalledView> {
+  return await nextclawClient.mcpMarketplace.fetchInstalled();
+}
+
+export async function fetchMcpMarketplaceItem(slug: string): Promise<MarketplaceItemView> {
+  return await nextclawClient.mcpMarketplace.fetchItem(slug);
+}
+
+export async function fetchMcpMarketplaceContent(slug: string): Promise<MarketplaceMcpContentView> {
+  return await nextclawClient.mcpMarketplace.fetchContent(slug);
+}
+
+export async function fetchMcpMarketplaceRecommendations(params: {
+  scene?: string;
+  limit?: number;
+} = {}): Promise<MarketplaceRecommendationView> {
+  return await nextclawClient.mcpMarketplace.fetchRecommendations(params);
+}
+
+export async function installMcpMarketplaceItem(request: {
+  spec: string;
+  name?: string;
+  enabled?: boolean;
+  allAgents?: boolean;
+  agents?: string[];
+  inputs?: Record<string, string>;
+}): Promise<{ type: 'mcp'; spec: string; name?: string; message: string; output?: string }> {
+  return await nextclawClient.mcpMarketplace.install({
+    type: 'mcp',
+    ...request
+  });
+}
+
+export async function manageMcpMarketplaceItem(request: {
+  action: 'enable' | 'disable' | 'remove';
+  id?: string;
+  spec?: string;
+}): Promise<{ type: 'mcp'; action: 'enable' | 'disable' | 'remove'; id: string; message: string; output?: string }> {
+  return await nextclawClient.mcpMarketplace.manage({
+    type: 'mcp',
+    ...request
+  });
+}
+
+export async function doctorMcpMarketplaceItem(name: string): Promise<MarketplaceMcpDoctorResult> {
+  return await nextclawClient.mcpMarketplace.doctor(name);
+}

package/src/shared/lib/api/services/ncp-attachments.service.ts

@@ -0,0 +1,14 @@
+import type { NcpDraftAttachment } from "@nextclaw/ncp-react";
+import { nextclawClient } from "./client.service";
+
+export async function uploadNcpAssets(files: File[]): Promise<NcpDraftAttachment[]> {
+  const payload = await nextclawClient.sessions.uploadAssets(files);
+  return payload.assets.map((asset) => ({
+    id: asset.id,
+    name: asset.name,
+    mimeType: asset.mimeType,
+    sizeBytes: asset.sizeBytes,
+    assetUri: asset.assetUri,
+    url: asset.url,
+  }));
+}

package/src/shared/lib/api/services/ncp-session.service.ts

@@ -0,0 +1,39 @@
+import { nextclawClient } from './client.service';
+import type {
+  NcpSessionMessagesView,
+  NcpSessionSkillsView,
+  NcpSessionsListView,
+  NcpSessionSummaryView,
+  SessionPatchUpdate
+} from '@/shared/lib/api/types';
+
+// GET /api/ncp/sessions
+export async function fetchNcpSessions(params?: { limit?: number }): Promise<NcpSessionsListView> {
+  return await nextclawClient.sessions.list(params) as NcpSessionsListView;
+}
+
+// GET /api/ncp/sessions/:sessionId/messages
+export async function fetchNcpSessionMessages(sessionId: string, limit = 200): Promise<NcpSessionMessagesView> {
+  return await nextclawClient.sessions.listMessages(sessionId, limit) as NcpSessionMessagesView;
+}
+
+// GET /api/ncp/sessions/:sessionId/skills
+export async function fetchNcpSessionSkills(
+  sessionId: string,
+  params?: { projectRoot?: string | null }
+): Promise<NcpSessionSkillsView> {
+  return await nextclawClient.sessions.listSkills(sessionId, params);
+}
+
+// PUT /api/ncp/sessions/:sessionId
+export async function updateNcpSession(
+  sessionId: string,
+  data: SessionPatchUpdate
+): Promise<NcpSessionSummaryView> {
+  return await nextclawClient.sessions.update(sessionId, data) as NcpSessionSummaryView;
+}
+
+// DELETE /api/ncp/sessions/:sessionId
+export async function deleteNcpSession(sessionId: string): Promise<{ deleted: boolean; sessionId: string }> {
+  return await nextclawClient.sessions.delete(sessionId);
+}

package/src/shared/lib/api/services/remote.service.ts

@@ -0,0 +1,50 @@
+import { nextclawClient } from './client.service';
+import type {
+  RemoteAccessView,
+  RemoteAccountProfileUpdateRequest,
+  RemoteBrowserAuthPollRequest,
+  RemoteBrowserAuthPollResult,
+  RemoteBrowserAuthStartRequest,
+  RemoteBrowserAuthStartResult,
+  RemoteDoctorView,
+  RemoteLoginRequest,
+  RemoteServiceAction,
+  RemoteServiceActionResult,
+  RemoteSettingsUpdateRequest
+} from '@/shared/lib/api/remote.types';
+
+export async function fetchRemoteStatus(): Promise<RemoteAccessView> {
+  return await nextclawClient.remote.fetchStatus();
+}
+
+export async function fetchRemoteDoctor(): Promise<RemoteDoctorView> {
+  return await nextclawClient.remote.fetchDoctor();
+}
+
+export async function loginRemote(data: RemoteLoginRequest): Promise<RemoteAccessView> {
+  return await nextclawClient.remote.login(data);
+}
+
+export async function startRemoteBrowserAuth(data: RemoteBrowserAuthStartRequest): Promise<RemoteBrowserAuthStartResult> {
+  return await nextclawClient.remote.startBrowserAuth(data);
+}
+
+export async function pollRemoteBrowserAuth(data: RemoteBrowserAuthPollRequest): Promise<RemoteBrowserAuthPollResult> {
+  return await nextclawClient.remote.pollBrowserAuth(data);
+}
+
+export async function logoutRemote(): Promise<RemoteAccessView> {
+  return await nextclawClient.remote.logout();
+}
+
+export async function updateRemoteAccountProfile(data: RemoteAccountProfileUpdateRequest): Promise<RemoteAccessView> {
+  return await nextclawClient.remote.updateAccountProfile(data);
+}
+
+export async function updateRemoteSettings(data: RemoteSettingsUpdateRequest): Promise<RemoteAccessView> {
+  return await nextclawClient.remote.updateSettings(data);
+}
+
+export async function controlRemoteService(action: RemoteServiceAction): Promise<RemoteServiceActionResult> {
+  return await nextclawClient.remote.controlService(action);
+}

package/src/shared/lib/api/services/runtime-control.service.ts

@@ -0,0 +1,18 @@
+import { nextclawClient } from './client.service';
+import type { RuntimeControlActionResult, RuntimeControlView } from '@/shared/lib/api/runtime-control.types';
+
+export async function fetchRuntimeControl(): Promise<RuntimeControlView> {
+  return await nextclawClient.runtimeControl.fetch();
+}
+
+export async function startRuntimeService(): Promise<RuntimeControlActionResult> {
+  return await nextclawClient.runtimeControl.startService();
+}
+
+export async function restartRuntimeService(): Promise<RuntimeControlActionResult> {
+  return await nextclawClient.runtimeControl.restartService();
+}
+
+export async function stopRuntimeService(): Promise<RuntimeControlActionResult> {
+  return await nextclawClient.runtimeControl.stopService();
+}

package/src/shared/lib/api/services/runtime-update.service.ts

@@ -0,0 +1,26 @@
+import type { UpdatePreferences, UpdateSnapshot } from '@nextclaw/kernel';
+import { nextclawClient } from './client.service';
+
+export async function fetchRuntimeUpdate(): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.fetch();
+}
+
+export async function checkRuntimeUpdate(): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.check();
+}
+
+export async function downloadRuntimeUpdate(): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.download();
+}
+
+export async function applyRuntimeUpdate(): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.apply();
+}
+
+export async function updateRuntimeUpdatePreferences(preferences: Partial<UpdatePreferences>): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.updatePreferences(preferences);
+}
+
+export async function updateRuntimeUpdateChannel(channel: UpdateSnapshot['channel']): Promise<UpdateSnapshot> {
+  return await nextclawClient.runtimeUpdate.updateChannel(channel);
+}

package/src/shared/lib/api/services/server-path.service.ts

@@ -0,0 +1,16 @@
+import { nextclawClient } from './client.service';
+import type { ServerPathBrowseView, ServerPathReadView } from '@/shared/lib/api/types';
+
+export async function fetchServerPathBrowse(params?: {
+  path?: string | null;
+  includeFiles?: boolean;
+}): Promise<ServerPathBrowseView> {
+  return await nextclawClient.serverPaths.browse(params);
+}
+
+export async function fetchServerPathRead(params: {
+  path: string;
+  basePath?: string | null;
+}): Promise<ServerPathReadView> {
+  return await nextclawClient.serverPaths.read(params);
+}

package/src/shared/lib/transport/index.ts

@@ -1,4 +1,5 @@
 export { appClient } from './app-client.service';
+export { requestRawApiResponse } from './request-raw-api-response.utils';
 export type {
   AppEvent,
   AppTransport,

package/src/shared/lib/transport/local-transport.service.ts

@@ -1,5 +1,6 @@
 import { systemStatusManager } from '@/features/system-status';
 import type { AppEvent, AppTransport, RequestInput, StreamInput, StreamSession } from './transport.types';
+import { requestRawApiResponse } from './request-raw-api-response.utils';
 import { readSseStreamResult } from './sse-stream.utils';
 import { resolveTransportWebSocketUrl } from './transport-websocket-url.utils';
 
@@ -139,13 +140,14 @@ export class LocalAppTransport implements AppTransport {
     const timeoutId = timeoutMs
       ? window.setTimeout(() => controller?.abort(`Request timed out after ${timeoutMs}ms: ${input.method} ${input.path}`), timeoutMs)
       : null;
+    const requestBody = normalizeRequestBody(input.body);
 
     try {
-      const { requestRawApiResponse } = await import('@/shared/lib/api');
-      const response = await requestRawApiResponse<T>(input.path, {
+      const response = await requestRawApiResponse<T>(this.apiBase, input.path, {
         method: input.method,
-        ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
-        ...(controller ? { signal: controller.signal } : {})
+        ...(requestBody !== undefined ? { body: requestBody } : {}),
+        ...(input.headers ? { headers: input.headers } : {}),
+        signal: controller?.signal ?? input.signal
       });
       if (!response.ok) {
         throw createTransportError(response, `Request failed for ${input.method} ${input.path}`);
@@ -228,3 +230,21 @@ export class LocalAppTransport implements AppTransport {
     return this.realtimeGateway.subscribe(handler);
   };
 }
+
+function normalizeRequestBody(body: unknown): BodyInit | undefined {
+  if (body === undefined) {
+    return undefined;
+  }
+  if (
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof Blob ||
+    body instanceof ArrayBuffer
+  ) {
+    return body;
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  return JSON.stringify(body);
+}

package/src/shared/lib/transport/remote-transport.service.ts

@@ -1,4 +1,4 @@
-import type { ApiError } from '@/shared/lib/api';
+import type { ApiError } from '@nextclaw/server';
 import type { AppEvent, AppTransport, RemoteRuntimeInfo, RequestInput, StreamInput, StreamSession } from './transport.types';
 import { resolveTransportWebSocketUrl } from './transport-websocket-url.utils';
 

package/src/shared/lib/transport/request-raw-api-response.utils.ts

@@ -0,0 +1,133 @@
+import type { ApiResponse } from '@nextclaw/server';
+import { systemStatusManager } from '@/features/system-status';
+
+function compactSnippet(text: string) {
+  return text.replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+
+function inferNonJsonHint(endpoint: string, status: number): string | undefined {
+  if (
+    status === 404 &&
+    endpoint.startsWith('/api/config/providers/') &&
+    endpoint.endsWith('/test')
+  ) {
+    return 'Provider test endpoint is missing. This usually means nextclaw runtime version is outdated.';
+  }
+  if (status === 401 || status === 403) {
+    return 'Authentication failed. Check apiKey and custom headers.';
+  }
+  if (status === 429) {
+    return 'Rate limited by upstream provider. Retry later or switch model/provider.';
+  }
+  if (status >= 500) {
+    return 'Upstream service error. Retry later and inspect server logs if it persists.';
+  }
+  return undefined;
+}
+
+function formatUnknownFetchError(error: unknown): {
+  summary: string;
+  details: Record<string, unknown>;
+} {
+  if (error instanceof Error) {
+    const name = error.name?.trim() || 'Error';
+    const message = error.message?.trim() || 'Unknown error';
+    return {
+      summary: `${name}: ${message}`,
+      details: {
+        errorName: name,
+        errorMessage: message,
+        ...(error.stack?.trim() ? { errorStack: error.stack.trim() } : {})
+      }
+    };
+  }
+  return {
+    summary: String(error ?? 'Unknown error'),
+    details: {
+      errorName: 'NonError',
+      errorMessage: String(error ?? 'Unknown error')
+    }
+  };
+}
+
+export async function requestRawApiResponse<T>(
+  apiBase: string,
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<ApiResponse<T>> {
+  const url = `${apiBase}${endpoint}`;
+  const method = (options.method || 'GET').toUpperCase();
+
+  let response: Response;
+  try {
+    const headers = new Headers(options.headers);
+    if (!(options.body instanceof FormData) && !headers.has('Content-Type')) {
+      headers.set('Content-Type', 'application/json');
+    }
+    response = await fetch(url, {
+      credentials: 'include',
+      headers,
+      ...options
+    });
+  } catch (error) {
+    const formatted = formatUnknownFetchError(error);
+    systemStatusManager.reportTransportFailure(formatted.summary);
+    return {
+      ok: false,
+      error: {
+        code: 'NETWORK_ERROR',
+        message: `Fetch failed on ${method} ${endpoint} | ${formatted.summary}`,
+        details: {
+          method,
+          endpoint,
+          url,
+          ...formatted.details
+        }
+      }
+    };
+  }
+
+  const text = await response.text();
+  let data: ApiResponse<T> | null = null;
+  if (text) {
+    try {
+      data = JSON.parse(text) as ApiResponse<T>;
+    } catch {
+      // fall through to build a synthetic error response
+    }
+  }
+
+  if (!data) {
+    const snippet = text ? compactSnippet(text) : '';
+    const hint = inferNonJsonHint(endpoint, response.status);
+    const parts = [`Non-JSON response (${response.status} ${response.statusText}) on ${method} ${endpoint}`];
+    if (snippet) {
+      parts.push(`body=${snippet}`);
+    }
+    if (hint) {
+      parts.push(`hint=${hint}`);
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_RESPONSE',
+        message: parts.join(' | '),
+        details: {
+          status: response.status,
+          statusText: response.statusText,
+          method,
+          endpoint,
+          url,
+          bodySnippet: snippet || undefined,
+          hint
+        }
+      }
+    };
+  }
+
+  if (!response.ok) {
+    return data as ApiResponse<T>;
+  }
+
+  return data as ApiResponse<T>;
+}