@tai42/api-client 0.1.0

package/src/errors.ts

@@ -0,0 +1,67 @@
+/**
+ * Loud error types. Every failure surfaces — a failed request or a schema
+ * mismatch throws, so the UI can render a visible error state, never a silent
+ * empty render.
+ */
+
+/** The skeleton returned `{ "error": "<message>" }` (or a non-2xx status). */
+export class ApiError extends Error {
+  readonly status: number;
+  /** The optional machine-readable `code` from the `{ error, code }` envelope. */
+  readonly code: string | undefined;
+  constructor(message: string, status: number, code?: string) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** A 401 from any data route. The shell routes this back to `/login`. */
+export class ApiUnauthorizedError extends ApiError {
+  constructor(message = 'unauthorized') {
+    super(message, 401);
+    this.name = 'ApiUnauthorizedError';
+  }
+}
+
+/** A duplicate answer / alias collision etc. (HTTP 409). */
+export class ApiConflictError extends ApiError {
+  constructor(message: string) {
+    super(message, 409);
+    this.name = 'ApiConflictError';
+  }
+}
+
+/**
+ * A login attempt was REJECTED (bad credentials, expired invite/SSO code,
+ * rate-limited). Deliberately NOT an ApiUnauthorizedError: that type means "your
+ * stored session credential is dead" and routes to /login globally (the
+ * create-studio wiring); this one means "the credentials you just typed on the
+ * login page were refused" and renders inline, on the page the user is already
+ * on.
+ */
+export class ApiLoginFailedError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ApiLoginFailedError';
+    this.status = status;
+  }
+}
+
+/**
+ * The response body did not match its declared zod schema. This is a contract
+ * drift between the Studio and the skeleton — a loud, visible error, never a
+ * silently-coerced value.
+ */
+export class ApiSchemaError extends Error {
+  readonly endpoint: string;
+  readonly issues: unknown;
+  constructor(endpoint: string, issues: unknown) {
+    super(`response from ${endpoint} did not match its expected schema`);
+    this.name = 'ApiSchemaError';
+    this.endpoint = endpoint;
+    this.issues = issues;
+  }
+}

package/src/fleet-report.ts

@@ -0,0 +1,94 @@
+/**
+ * The shared fleet-report handler — the single interpreter of a config mutation's
+ * fleet broadcast. Every mutation surface (connector, backup, mcp-config, env,
+ * extensions, single-MCP reload, fleet reload) routes its broadcast report through
+ * this one function so a FAILED propagation is never invisible: an unconfirmed
+ * sibling (`failed`/`missing`/`departed`/`timed_out`) or an unreachable bus becomes
+ * an explicit summary the UI renders as a loud, user-visible state — never a faked
+ * success on a departed/timed_out/failed origin.
+ *
+ * A mutation embeds its broadcast in one of two shapes: the mode-wrapped
+ * {@link FleetReportFanout} (`fanout` field) or the bare {@link FleetResult} (the
+ * fleet-reload and single-MCP-reload bodies). Both normalize to a
+ * {@link FleetReportSummary} through the functions here; the SDK's `FleetReport`
+ * component renders the summary.
+ */
+import type { FleetOutcome, FleetReportFanout, FleetResult } from './schemas';
+
+/** A per-origin propagation FAILURE: an origin that did not confirm `applied`. */
+export type FleetFailureOutcome = Exclude<FleetOutcome, 'applied'>;
+
+/** One origin that failed to converge, with the report's message for it. */
+export interface FleetOriginFailure {
+  readonly origin: string;
+  readonly outcome: FleetFailureOutcome;
+  /** The failed apply's `error`, or the publisher's computed-outcome `detail`. */
+  readonly message: string | null;
+}
+
+/**
+ * The interpreted state of one broadcast.
+ *   - `converged` — the bus was reached and every origin applied (or the change was
+ *     local-only on a lone worker). The caller renders its own success; the report
+ *     needs no loud state.
+ *   - `degraded` — the bus was reached but one or more origins did not confirm; the
+ *     named `failures` are stale/unreached siblings the operator must see.
+ *   - `unreachable` — the bus itself could not be reached, so no sibling was told;
+ *     `error` carries the transport failure.
+ */
+export type FleetReportStatus = 'converged' | 'degraded' | 'unreachable';
+
+export interface FleetReportSummary {
+  readonly status: FleetReportStatus;
+  /** The single-worker `local-only` note, when the broadcast reached no sibling. */
+  readonly note: string | null;
+  /** The origins that did not apply — empty unless `status` is `degraded`. */
+  readonly failures: readonly FleetOriginFailure[];
+  /** The bus-unreachable transport error — non-null only when `unreachable`. */
+  readonly error: string | null;
+}
+
+/** True when a summary describes a propagation the operator must be shown. */
+export function isFleetReportFailure(summary: FleetReportSummary | null): boolean {
+  return summary !== null && summary.status !== 'converged';
+}
+
+/**
+ * Interpret a bare {@link FleetResult} (the fleet-reload / single-MCP-reload body).
+ * An unreachable bus is `unreachable`; a reachable report with any non-`applied`
+ * origin is `degraded` (those origins named); otherwise `converged`.
+ */
+export function summarizeFleetResult(result: FleetResult): FleetReportSummary {
+  if (!result.reachable) {
+    return { status: 'unreachable', note: null, failures: [], error: result.error };
+  }
+  const failures: FleetOriginFailure[] = result.results
+    .filter((entry) => entry.outcome !== 'applied')
+    .map((entry) => ({
+      origin: entry.origin,
+      outcome: entry.outcome as FleetFailureOutcome,
+      message: entry.error ?? entry.detail ?? null,
+    }));
+  return {
+    status: failures.length > 0 ? 'degraded' : 'converged',
+    note: null,
+    failures,
+    error: null,
+  };
+}
+
+/**
+ * Interpret a mutation's mode-wrapped {@link FleetReportFanout}. `null`/`undefined`
+ * (the response path mutated no manifest) yields `null` — there is nothing to report.
+ * A `local-only` fan-out is `converged` with its note; `fleet`/`unreachable` carry a
+ * bare {@link FleetResult} and defer to {@link summarizeFleetResult}.
+ */
+export function summarizeFleetFanout(
+  fanout: FleetReportFanout | null | undefined,
+): FleetReportSummary | null {
+  if (fanout === null || fanout === undefined) return null;
+  if (fanout.mode === 'local-only') {
+    return { status: 'converged', note: fanout.note, failures: [], error: null };
+  }
+  return summarizeFleetResult(fanout);
+}

package/src/http.ts

@@ -0,0 +1,198 @@
+/**
+ * The HTTP core: a fetch wrapper that attaches the auth header, unwraps the
+ * skeleton's `{ "data" }` / `{ "error" }` envelope, and validates the payload
+ * against a per-endpoint zod schema. Every failure throws.
+ *
+ * Same-origin by default: the skeleton serves the built SPA, so requests use
+ * relative `/api/...` URLs. `VITE_API_BASE_URL` can override for cross-origin
+ * deployments (documented as requiring CORS on the skeleton).
+ */
+import type { z } from 'zod';
+
+import { ApiConflictError, ApiError, ApiSchemaError, ApiUnauthorizedError } from './errors';
+
+/** Supplies the current API key (in-memory or sessionStorage-backed) + base URL. */
+export interface ApiConfig {
+  /** Absolute base (e.g. `https://host`) or '' for same-origin relative `/api`. */
+  readonly baseUrl?: string;
+  /** Returns the pre-provisioned API key, or null when unauthenticated. */
+  getToken: () => string | null;
+  /** Optional fetch impl (tests inject one; defaults to global fetch). */
+  fetch?: typeof fetch;
+}
+
+export interface RequestOptions {
+  readonly method?: string;
+  readonly body?: unknown;
+  // An array value is sent as REPEATED params, one occurrence per element (e.g.
+  // `tags=a&tags=b`); a scalar is sent once. `undefined` values are dropped.
+  readonly query?: Record<string, string | number | string[] | undefined>;
+  readonly signal?: AbortSignal;
+}
+
+const JSON_HEADERS = { 'content-type': 'application/json' } as const;
+
+/**
+ * Whether a value can never be faithfully transmitted as a single URL path
+ * segment. The browser's WHATWG URL parser removes dot-segments (`.`, `..`) from a
+ * relative request path before it is sent — even percent-encoded — and reads an
+ * empty or absolute (`/`-prefixed) value as a path boundary, so any of these would
+ * silently retarget the request at an unrelated same-origin route. The path
+ * encoders reject such a segment loudly at the client boundary instead of letting
+ * it leave; the server enforces the same relative-path rule.
+ */
+export function isUnsafePathSegment(segment: string): boolean {
+  return segment === '' || segment === '.' || segment === '..' || segment.startsWith('/');
+}
+
+/**
+ * Encode a single id (string or number) as ONE URL path segment.
+ * `encodeURIComponent` already percent-encodes any interior `/`, so the value is
+ * guaranteed to stay a single segment (spaces, `#`, `?`, … all escape). An empty,
+ * `.`, `..`, or absolute id is REJECTED loudly rather than encoded (see
+ * `isUnsafePathSegment`): the browser would collapse it and retarget the request
+ * at a different route. A number stringifies to digits and is always safe.
+ */
+export function encodeSegment(value: string | number): string {
+  const segment = String(value);
+  if (isUnsafePathSegment(segment)) {
+    throw new Error(
+      `URL path segment must not be empty, '.', '..', or absolute; received ${JSON.stringify(segment)}`,
+    );
+  }
+  return encodeURIComponent(segment);
+}
+
+function buildUrl(base: string, path: string, query?: RequestOptions['query']): string {
+  const url = `${base}${path}`;
+  if (!query) return url;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const element of value) params.append(key, element);
+    } else {
+      params.set(key, String(value));
+    }
+  }
+  const qs = params.toString();
+  return qs ? `${url}?${qs}` : url;
+}
+
+/**
+ * Send a request and validate the unwrapped `data` against `schema`. The auth
+ * header is `X-Api-Key` (the skeleton's access-control middleware also accepts
+ * `Authorization: Bearer`; we use the dedicated key header).
+ */
+export async function apiRequest<S extends z.ZodTypeAny>(
+  config: ApiConfig,
+  path: string,
+  schema: S,
+  options: RequestOptions = {},
+): Promise<z.infer<S>> {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const token = config.getToken();
+  const headers: Record<string, string> = { ...JSON_HEADERS };
+  if (token) headers['x-api-key'] = token;
+
+  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    signal: options.signal,
+  });
+
+  if (response.status === 401) throw new ApiUnauthorizedError();
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch {
+    if (response.ok) throw new ApiSchemaError(path, 'response was not valid JSON');
+    throw new ApiError(response.statusText || 'request failed', response.status);
+  }
+
+  if (!response.ok) {
+    const { message, code } = extractError(payload);
+    const text = message ?? (response.statusText || 'request failed');
+    if (response.status === 409) throw new ApiConflictError(text);
+    throw new ApiError(text, response.status, code);
+  }
+
+  if (!isDataEnvelope(payload)) {
+    throw new ApiSchemaError(path, 'response was not a { data } envelope');
+  }
+
+  const parsed = schema.safeParse(payload.data);
+  if (!parsed.success) throw new ApiSchemaError(path, parsed.error.issues);
+  return parsed.data as z.infer<S>;
+}
+
+/**
+ * Fetch a plain-text endpoint (the skeleton's `/health` → `"OK"` and `/metrics`
+ * → Prometheus text). No `{ data }` envelope, no zod — the body is returned
+ * verbatim. Non-2xx still throws loudly.
+ */
+export async function apiText(
+  config: ApiConfig,
+  path: string,
+  options: RequestOptions = {},
+): Promise<string> {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const token = config.getToken();
+  const headers: Record<string, string> = {};
+  if (token) headers['x-api-key'] = token;
+
+  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    signal: options.signal,
+  });
+
+  if (response.status === 401) throw new ApiUnauthorizedError();
+  if (!response.ok) throw new ApiError(response.statusText || 'request failed', response.status);
+  return response.text();
+}
+
+/**
+ * Fetch a raw file download (the skeleton's backup export and observability
+ * exports stream a document, NOT a `{ data }` envelope). Attaches the auth
+ * header, serializes a JSON body when one is given (POST exports), and returns
+ * the response as a `Blob`. Non-2xx throws loudly — no silent empty download.
+ */
+export async function apiDownload(
+  config: ApiConfig,
+  path: string,
+  options: RequestOptions = {},
+): Promise<Blob> {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const token = config.getToken();
+  const headers: Record<string, string> = {};
+  if (options.body !== undefined) Object.assign(headers, JSON_HEADERS);
+  if (token) headers['x-api-key'] = token;
+
+  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    signal: options.signal,
+  });
+
+  if (response.status === 401) throw new ApiUnauthorizedError();
+  if (!response.ok) throw new ApiError(response.statusText || 'download failed', response.status);
+  return response.blob();
+}
+
+function isDataEnvelope(value: unknown): value is { data: unknown } {
+  return typeof value === 'object' && value !== null && 'data' in value;
+}
+
+/** Pull the `error` message and optional machine `code` from the failure envelope. */
+export function extractError(value: unknown): { message: string | null; code: string | undefined } {
+  if (typeof value === 'object' && value !== null) {
+    const message = 'error' in value && typeof value.error === 'string' ? value.error : null;
+    const code = 'code' in value && typeof value.code === 'string' ? value.code : undefined;
+    return { message, code };
+  }
+  return { message: null, code: undefined };
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * @tai42/api-client — the typed transport for the tai-skeleton HTTP API.
+ *
+ * One zod schema per consumed endpoint; every response is
+ * validated and every failure throws. No caching of its own — server state
+ * lives in TanStack Query in the feature packages.
+ */
+export { createApiClient, isSafeApiPath } from './client';
+export type {
+  ApiClient,
+  RunToolArgs,
+  StartConnectArgs,
+  ApiKeyBody,
+  ClaimLinkBody,
+  ValidateConditionBody,
+  TopicVerifierBody,
+  AddUrlToScopeBody,
+  PinRoutePublicBody,
+  CreatePresetBody,
+  SavePresetVersionBody,
+  ValidatePresetBody,
+  StorageUploadBody,
+  MetricsQuery,
+  RunsQuery,
+  MarketplaceSearchQuery,
+  MarketplaceInstallBody,
+  MarketplaceUninstallBody,
+} from './client';
+export type { ApiConfig, RequestOptions } from './http';
+export { apiRequest, apiText, apiDownload } from './http';
+export {
+  ApiError,
+  ApiUnauthorizedError,
+  ApiConflictError,
+  ApiLoginFailedError,
+  ApiSchemaError,
+} from './errors';
+export { SseFrameParser, readSseFrames } from './sse';
+export type { SseFrame } from './sse';
+export { parseAgentFrame, parseAgentTranscript, agentEventSchema } from './agents';
+export type { AgentSummary, AgentEvent, UnknownAgentEvent, ParsedAgentEvent } from './agents';
+export {
+  toolRunStatus,
+  toolRunSubmitResult,
+  toolRunRecord,
+  toolRunListItem,
+  toolRunList,
+  isTerminalRunStatus,
+} from './tool-runs';
+export type {
+  ToolRunStatus,
+  ToolRunSubmitResult,
+  ToolRunRecord,
+  ToolRunListItem,
+  SubmitToolRunArgs,
+} from './tool-runs';
+export { summarizeFleetResult, summarizeFleetFanout, isFleetReportFailure } from './fleet-report';
+export type {
+  FleetReportSummary,
+  FleetReportStatus,
+  FleetOriginFailure,
+  FleetFailureOutcome,
+} from './fleet-report';
+export * as schemas from './schemas';
+export type {
+  ToolSchema,
+  ToolMediaResult,
+  ToolTagEntry,
+  AuthRoute,
+  PresetRecord,
+  PresetDetail,
+  PresetBody,
+  PresetVersion,
+  PresetRenamed,
+  PresetReferees,
+  PresetValidation,
+  PresetVersionTags,
+  PresetExtensionElement,
+  PolicyBody,
+  PolicyVersion,
+  ValidateConditionResult,
+  Extension,
+  ToolExtensions,
+  ToolExtensionsApplyResult,
+  ProviderView,
+  ConnectionView,
+  OAuthCompleteResult,
+  StudioPluginManifest,
+  Interaction,
+  InteractionAnswered,
+  InteractionMediaItem,
+  MediaKind,
+  AnswerFormat,
+  Channels,
+  Notification,
+  Notifications,
+  HookParams,
+  SettingsSchema,
+  TokensPayload,
+  LoginFormField,
+  LoginMethod,
+  LoginMethods,
+  LoginResult,
+  MeProjection,
+  RouteEntry,
+  PatternEntry,
+  SubMcpEntry,
+  ClaimLinkCreated,
+  LogoutResult,
+  AuthCapabilities,
+  BackupDocument,
+  BackupImportReport,
+  ScheduleItem,
+  StorageInfo,
+  StorageResourceStat,
+  BackendInfo,
+  OriginKind,
+  FleetOrigin,
+  FleetWorkers,
+  FleetOutcome,
+  FleetOriginResult,
+  FleetResult,
+  FleetReloadResult,
+  FleetReportFanout,
+  ReloadConfigResult,
+  McpReloadResult,
+  KindStatus,
+  DashboardMetrics,
+  Run,
+  RunSpan,
+  RunTrace,
+  MarketplaceItem,
+  MarketplaceSearchRow,
+  MarketplaceSearchPage,
+  MarketplaceVersion,
+  MarketplaceLatestVersion,
+  MarketplaceAdvisory,
+  MarketplacePluginDetail,
+  MarketplaceInstalledPlugin,
+  MarketplaceInstallResult,
+  MarketplaceUninstallResult,
+} from './schemas';