@fluxomni/api-client 0.11.0

package/src/client.ts

@@ -0,0 +1,412 @@
+import type { Observable } from '@apollo/client/core/index.js';
+import {
+  ApolloClient,
+  ApolloError,
+  type ApolloLink,
+  type DocumentNode,
+  type FetchResult,
+  HttpLink,
+  InMemoryCache,
+  type MutationOptions,
+  type NormalizedCacheObject,
+  type OperationVariables,
+  type QueryOptions,
+  type SubscriptionOptions,
+  split,
+} from '@apollo/client/core/index.js';
+import { GraphQLWsLink } from '@apollo/client/link/subscriptions/index.js';
+import { getMainDefinition } from '@apollo/client/utilities/index.js';
+import { type GraphQLFormattedError, print } from 'graphql';
+import { createClient, type Client as WsClient } from 'graphql-ws';
+import {
+  type AuthStatus,
+  createSessionFetch,
+  type LoginOptions,
+  login,
+} from './auth.js';
+import { GraphQLError, MissingDataError, NetworkError } from './errors.js';
+
+export interface GraphQLClientConfig {
+  /** HTTP endpoint for queries and mutations */
+  httpEndpoint: string;
+  /** WebSocket endpoint for subscriptions (optional) */
+  wsEndpoint?: string;
+  /** Optional Authorization header for trusted/internal callers; user auth normally uses session cookies. */
+  authHeader?: string;
+  /** Cookie header for server-side session-auth callers, for example `fluxomni_session=...`. */
+  cookieHeader?: string;
+  /** Browser credential mode for GraphQL HTTP requests. */
+  credentials?: RequestCredentials;
+  /** Custom fetch function for HTTP requests */
+  fetch?: typeof fetch;
+}
+
+export interface ConnectionCallbacks {
+  onConnect?: () => void;
+  onDisconnect?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export type GraphQLClientLoginOptions = LoginOptions & {
+  /** HTTP endpoint for queries and mutations. Defaults to `${baseUrl}/api` or `/api` for same-origin callers. */
+  httpEndpoint?: string;
+  /** WebSocket endpoint for subscriptions. Defaults to `ws(s)://<baseUrl>/api/subscriptions` or `/api/subscriptions` for same-origin callers. */
+  wsEndpoint?: string;
+};
+
+export type GraphQLClientLoginResult = {
+  client: GraphQLClient;
+  status: AuthStatus;
+  /** `Cookie` header value for server-side callers when the runtime exposes Set-Cookie. */
+  cookieHeader?: string;
+};
+
+type ProcessEnvLike = {
+  process?: {
+    env?: Record<string, string | undefined>;
+  };
+};
+
+/**
+ * Low-level GraphQL client wrapping Apollo Client.
+ *
+ * Provides typed query, mutation, and subscription execution with consistent error handling.
+ */
+export class GraphQLClient {
+  private readonly config: GraphQLClientConfig;
+  private apolloClient: ApolloClient<NormalizedCacheObject>;
+  private wsClient?: WsClient;
+
+  constructor(config: GraphQLClientConfig, callbacks?: ConnectionCallbacks) {
+    this.config = config;
+    const headers = clientHeaders(config);
+
+    const httpLink = new HttpLink({
+      uri: config.httpEndpoint,
+      fetch: config.fetch,
+      credentials: config.credentials,
+      headers,
+    });
+
+    let link: ApolloLink = httpLink;
+
+    if (config.wsEndpoint) {
+      this.wsClient = createClient({
+        url: config.wsEndpoint,
+        keepAlive: 10_000,
+        connectionParams: connectionParams(config),
+        on: {
+          connected: () => callbacks?.onConnect?.(),
+          closed: () => callbacks?.onDisconnect?.(),
+          error: (err) => callbacks?.onError?.(err),
+        },
+      });
+
+      const wsLink = new GraphQLWsLink(this.wsClient);
+
+      link = split(
+        ({ query }) => {
+          const definition = getMainDefinition(query);
+          return (
+            definition.kind === 'OperationDefinition' &&
+            definition.operation === 'subscription'
+          );
+        },
+        wsLink,
+        httpLink,
+      );
+    }
+
+    this.apolloClient = new ApolloClient({
+      link,
+      cache: new InMemoryCache(),
+      defaultOptions: {
+        query: { fetchPolicy: 'network-only' },
+        mutate: { fetchPolicy: 'no-cache' },
+      },
+    });
+  }
+
+  /**
+   * Log in with the session endpoint and return a session-aware client.
+   */
+  static async login(
+    options: GraphQLClientLoginOptions,
+    callbacks?: ConnectionCallbacks,
+  ): Promise<GraphQLClientLoginResult> {
+    const auth = await login(options);
+    const endpoints = endpointsFromLoginOptions(options);
+    const fetchFn = auth.cookieHeader
+      ? createSessionFetch(auth.cookieHeader, options.fetch)
+      : options.fetch;
+
+    return {
+      client: new GraphQLClient(
+        {
+          httpEndpoint: endpoints.httpEndpoint,
+          wsEndpoint: endpoints.wsEndpoint,
+          cookieHeader: auth.cookieHeader,
+          credentials: options.credentials ?? 'same-origin',
+          fetch: fetchFn,
+        },
+        callbacks,
+      ),
+      status: auth.status,
+      cookieHeader: auth.cookieHeader,
+    };
+  }
+
+  /**
+   * Create a client from environment variables.
+   */
+  static fromEnv(
+    env?: Record<string, string | undefined>,
+    callbacks?: ConnectionCallbacks,
+  ): GraphQLClient {
+    const resolvedEnv =
+      env ?? (globalThis as ProcessEnvLike).process?.env ?? {};
+    const httpEndpoint =
+      resolvedEnv.FLUXOMNI_HTTP_ENDPOINT || resolvedEnv.GRAPHQL_ENDPOINT;
+
+    if (!httpEndpoint) {
+      throw new Error(
+        'FLUXOMNI_HTTP_ENDPOINT or GRAPHQL_ENDPOINT environment variable must be set',
+      );
+    }
+
+    return new GraphQLClient(
+      {
+        httpEndpoint,
+        wsEndpoint: resolvedEnv.FLUXOMNI_WS_ENDPOINT,
+        authHeader: resolvedEnv.FLUXOMNI_AUTH || resolvedEnv.GRAPHQL_AUTH,
+      },
+      callbacks,
+    );
+  }
+
+  /**
+   * Get the underlying Apollo Client instance.
+   */
+  get apollo(): ApolloClient<NormalizedCacheObject> {
+    return this.apolloClient;
+  }
+
+  /**
+   * Execute a GraphQL query.
+   */
+  async query<
+    TData,
+    TVariables extends OperationVariables = OperationVariables,
+  >(options: QueryOptions<TVariables, TData>): Promise<TData> {
+    try {
+      const result = await this.apolloClient.query<TData, TVariables>(options);
+
+      if (result.errors?.length) {
+        throw GraphQLError.fromGraphQLErrors(result.errors);
+      }
+
+      if (!result.data) {
+        throw new MissingDataError();
+      }
+
+      return result.data;
+    } catch (error) {
+      if (error instanceof GraphQLError) throw error;
+      if (error instanceof ApolloError) {
+        if (error.graphQLErrors.length) {
+          throw GraphQLError.fromGraphQLErrors(error.graphQLErrors);
+        }
+        if (error.networkError) {
+          throw new NetworkError(error.networkError.message, undefined, error);
+        }
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : 'Unknown error',
+        undefined,
+        error instanceof Error ? error : undefined,
+      );
+    }
+  }
+
+  /**
+   * Execute a GraphQL mutation.
+   */
+  async mutate<
+    TData,
+    TVariables extends OperationVariables = OperationVariables,
+  >(options: MutationOptions<TData, TVariables>): Promise<TData> {
+    try {
+      const result = await this.apolloClient.mutate<TData, TVariables>(options);
+
+      if (result.errors?.length) {
+        throw GraphQLError.fromGraphQLErrors(result.errors);
+      }
+
+      if (!result.data) {
+        throw new MissingDataError();
+      }
+
+      return result.data;
+    } catch (error) {
+      if (error instanceof GraphQLError) throw error;
+      if (error instanceof ApolloError) {
+        if (error.graphQLErrors.length) {
+          throw GraphQLError.fromGraphQLErrors(error.graphQLErrors);
+        }
+        if (error.networkError) {
+          throw new NetworkError(error.networkError.message, undefined, error);
+        }
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : 'Unknown error',
+        undefined,
+        error instanceof Error ? error : undefined,
+      );
+    }
+  }
+
+  /**
+   * Create a subscription observable.
+   */
+  subscribe<TData, TVariables extends OperationVariables = OperationVariables>(
+    options: SubscriptionOptions<TVariables, TData>,
+  ): Observable<FetchResult<TData>> {
+    return this.apolloClient.subscribe<TData, TVariables>(options);
+  }
+
+  /**
+   * Execute a raw GraphQL operation with untyped variables.
+   *
+   * This is the recommended automation surface when generated operation
+   * documents are more structure than needed.
+   */
+  async executeRaw<TData = unknown>(
+    query: DocumentNode | string,
+    variables?: Record<string, unknown>,
+  ): Promise<TData> {
+    const fetchFn = this.config.fetch ?? globalThis.fetch;
+    if (!fetchFn) {
+      throw new NetworkError('No fetch implementation available');
+    }
+
+    const response = await fetchFn(this.config.httpEndpoint, {
+      method: 'POST',
+      credentials: this.config.credentials,
+      headers: {
+        'content-type': 'application/json',
+        ...clientHeaders(this.config),
+      },
+      body: JSON.stringify({
+        query: typeof query === 'string' ? query : print(query),
+        variables: variables ?? {},
+      }),
+    });
+
+    if (!response.ok) {
+      throw new NetworkError(
+        `HTTP ${response.status}: ${await response.text()}`,
+        response.status,
+      );
+    }
+
+    const body = (await response.json()) as {
+      data?: TData | null;
+      errors?: readonly GraphQLFormattedError[];
+    };
+
+    if (body.errors?.length) {
+      throw GraphQLError.fromGraphQLErrors(body.errors);
+    }
+
+    if (!body.data) {
+      throw new MissingDataError();
+    }
+
+    return body.data;
+  }
+
+  /**
+   * Stop the client and clean up resources.
+   */
+  stop(): void {
+    this.apolloClient.stop();
+    this.wsClient?.dispose();
+  }
+
+  /**
+   * Clear the Apollo cache.
+   */
+  async clearCache(): Promise<void> {
+    await this.apolloClient.clearStore();
+  }
+
+  /**
+   * Reset the Apollo store (clear cache and refetch active queries).
+   */
+  async resetStore(): Promise<void> {
+    await this.apolloClient.resetStore();
+  }
+}
+
+function clientHeaders(
+  config: GraphQLClientConfig,
+): Record<string, string> | undefined {
+  const headers: Record<string, string> = {};
+
+  if (config.authHeader) {
+    headers.Authorization = config.authHeader;
+  }
+
+  if (config.cookieHeader) {
+    headers.Cookie = config.cookieHeader;
+  }
+
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+function connectionParams(
+  config: GraphQLClientConfig,
+): Record<string, string> | undefined {
+  const params: Record<string, string> = {};
+
+  if (config.authHeader) {
+    params.authorization = config.authHeader;
+  }
+
+  if (config.cookieHeader) {
+    params.cookie = config.cookieHeader;
+  }
+
+  return Object.keys(params).length > 0 ? params : undefined;
+}
+
+function endpointsFromLoginOptions(options: GraphQLClientLoginOptions): {
+  httpEndpoint: string;
+  wsEndpoint?: string;
+} {
+  if (options.httpEndpoint) {
+    return {
+      httpEndpoint: options.httpEndpoint,
+      wsEndpoint: options.wsEndpoint,
+    };
+  }
+
+  const hasWebSocket = typeof globalThis.WebSocket !== 'undefined';
+
+  if (!options.baseUrl) {
+    return {
+      httpEndpoint: '/api',
+      wsEndpoint:
+        options.wsEndpoint ?? (hasWebSocket ? '/api/subscriptions' : undefined),
+    };
+  }
+
+  const httpEndpoint = new URL('/api', options.baseUrl).toString();
+  const wsEndpoint =
+    options.wsEndpoint ??
+    (hasWebSocket
+      ? httpEndpoint.replace(/^http(?=:)/, 'ws').concat('/subscriptions')
+      : undefined);
+
+  return { httpEndpoint, wsEndpoint };
+}

package/src/errors.ts

@@ -0,0 +1,183 @@
+import type { GraphQLFormattedError } from 'graphql';
+
+/**
+ * Structured error details returned by the GraphQL server.
+ */
+export interface GraphQLServerError {
+  message: string;
+  code?: string;
+  status?: number;
+  backtrace?: string[];
+}
+
+/**
+ * Public automation categories for GraphQL errors.
+ */
+export type GraphQLErrorCategory =
+  | 'unauthenticated'
+  | 'forbidden'
+  | 'validation'
+  | 'not_found'
+  | 'conflict'
+  | 'persistence_failure'
+  | 'runtime_unavailable'
+  | 'operation_rejected'
+  | 'unknown';
+
+const VALIDATION_CODE_PREFIXES = ['INVALID_', 'EMPTY_', 'TOO_MUCH_'];
+const VALIDATION_CODE_SUFFIXES = ['_INVALID', '_VALIDATION_FAILED'];
+const VALIDATION_CODE_EXACT = new Set([
+  'INVALID_JSON',
+  'INVALID_SPEC',
+  'NO_API_KEY',
+  'ROUTE_SOURCES_EMPTY',
+  'WRONG_ARRAY_INDEX',
+]);
+const PERSISTENCE_CODE_PARTS = ['PERSIST', 'STORAGE', 'DATABASE'];
+const RUNTIME_UNAVAILABLE_CODE_PARTS = ['RUNTIME_STATE_UNAVAILABLE', 'UNAVAILABLE'];
+const OPERATION_REJECTED_CODE_PARTS = ['REJECTED', 'STALE_ASSIGNMENT'];
+
+/**
+ * Classify a GraphQL server error into the public automation taxonomy.
+ */
+export function classifyGraphQLError(
+  error: GraphQLServerError,
+): GraphQLErrorCategory {
+  switch (error.status) {
+    case 401:
+      return 'unauthenticated';
+    case 403:
+      return 'forbidden';
+    case 404:
+      return 'not_found';
+    case 409:
+      return 'conflict';
+    case 400:
+      return 'validation';
+    default:
+      break;
+  }
+
+  const code = error.code?.toUpperCase();
+  if (!code) return 'unknown';
+  if (code === 'UNAUTHORIZED') return 'unauthenticated';
+  if (code === 'FORBIDDEN') return 'forbidden';
+  if (code.endsWith('_NOT_FOUND') || code === 'NOT_FOUND') return 'not_found';
+  if (code.includes('CONFLICT') || code.includes('DUPLICATE')) return 'conflict';
+  if (
+    VALIDATION_CODE_EXACT.has(code) ||
+    VALIDATION_CODE_PREFIXES.some((prefix) => code.startsWith(prefix)) ||
+    VALIDATION_CODE_SUFFIXES.some((suffix) => code.endsWith(suffix))
+  ) {
+    return 'validation';
+  }
+  if (PERSISTENCE_CODE_PARTS.some((part) => code.includes(part))) {
+    return 'persistence_failure';
+  }
+  if (RUNTIME_UNAVAILABLE_CODE_PARTS.some((part) => code.includes(part))) {
+    return 'runtime_unavailable';
+  }
+  if (OPERATION_REJECTED_CODE_PARTS.some((part) => code.includes(part))) {
+    return 'operation_rejected';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * High-level client errors for the TypeScript GraphQL client.
+ */
+export class ClientError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: Error,
+  ) {
+    super(message);
+    this.name = 'ClientError';
+  }
+}
+
+/**
+ * GraphQL-specific errors.
+ */
+export class GraphQLError extends ClientError {
+  constructor(
+    message: string,
+    public readonly errors: GraphQLServerError[] = [],
+    cause?: Error,
+  ) {
+    super(message, cause);
+    this.name = 'GraphQLError';
+  }
+
+  static fromGraphQLErrors(
+    errors: readonly GraphQLFormattedError[],
+  ): GraphQLError {
+    const serverErrors = errors.map((err) => {
+      const extensions = err.extensions as Record<string, unknown> | undefined;
+      return {
+        message: err.message,
+        code: extensions?.code as string | undefined,
+        status: extensions?.status as number | undefined,
+        backtrace: extensions?.backtrace as string[] | undefined,
+      };
+    });
+    return new GraphQLError(
+      `GraphQL errors: ${serverErrors.map((e) => e.message).join(', ')}`,
+      serverErrors,
+    );
+  }
+
+  get categories(): GraphQLErrorCategory[] {
+    return Array.from(
+      new Set(this.errors.map((error) => classifyGraphQLError(error))),
+    );
+  }
+}
+
+/**
+ * Network-related errors.
+ */
+export class NetworkError extends ClientError {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    cause?: Error,
+  ) {
+    super(message, cause);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * Missing field in response error.
+ */
+export class MissingFieldError extends ClientError {
+  constructor(public readonly fieldName: string) {
+    super(`Missing field in response: ${fieldName}`);
+    this.name = 'MissingFieldError';
+  }
+}
+
+/**
+ * Missing data in response error.
+ */
+export class MissingDataError extends ClientError {
+  constructor() {
+    super('Missing data in response');
+    this.name = 'MissingDataError';
+  }
+}
+
+/**
+ * Extract a required field from an optional value.
+ */
+export function extractField<T>(
+  value: T | null | undefined,
+  fieldName: string,
+): T {
+  if (value === null || value === undefined) {
+    throw new MissingFieldError(fieldName);
+  }
+  return value;
+}