@fluxomni/api-client 0.11.0

package/dist/client.js

@@ -0,0 +1,254 @@
+import { ApolloClient, ApolloError, HttpLink, InMemoryCache, 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 { print } from 'graphql';
+import { createClient } from 'graphql-ws';
+import { createSessionFetch, login, } from './auth.js';
+import { GraphQLError, MissingDataError, NetworkError } from './errors.js';
+/**
+ * Low-level GraphQL client wrapping Apollo Client.
+ *
+ * Provides typed query, mutation, and subscription execution with consistent error handling.
+ */
+export class GraphQLClient {
+    config;
+    apolloClient;
+    wsClient;
+    constructor(config, callbacks) {
+        this.config = config;
+        const headers = clientHeaders(config);
+        const httpLink = new HttpLink({
+            uri: config.httpEndpoint,
+            fetch: config.fetch,
+            credentials: config.credentials,
+            headers,
+        });
+        let link = 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, callbacks) {
+        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, callbacks) {
+        const resolvedEnv = env ?? globalThis.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() {
+        return this.apolloClient;
+    }
+    /**
+     * Execute a GraphQL query.
+     */
+    async query(options) {
+        try {
+            const result = await this.apolloClient.query(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(options) {
+        try {
+            const result = await this.apolloClient.mutate(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(options) {
+        return this.apolloClient.subscribe(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(query, variables) {
+        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());
+        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() {
+        this.apolloClient.stop();
+        this.wsClient?.dispose();
+    }
+    /**
+     * Clear the Apollo cache.
+     */
+    async clearCache() {
+        await this.apolloClient.clearStore();
+    }
+    /**
+     * Reset the Apollo store (clear cache and refetch active queries).
+     */
+    async resetStore() {
+        await this.apolloClient.resetStore();
+    }
+}
+function clientHeaders(config) {
+    const headers = {};
+    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) {
+    const params = {};
+    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) {
+    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 };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,59 @@
+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';
+/**
+ * Classify a GraphQL server error into the public automation taxonomy.
+ */
+export declare function classifyGraphQLError(error: GraphQLServerError): GraphQLErrorCategory;
+/**
+ * High-level client errors for the TypeScript GraphQL client.
+ */
+export declare class ClientError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * GraphQL-specific errors.
+ */
+export declare class GraphQLError extends ClientError {
+    readonly errors: GraphQLServerError[];
+    constructor(message: string, errors?: GraphQLServerError[], cause?: Error);
+    static fromGraphQLErrors(errors: readonly GraphQLFormattedError[]): GraphQLError;
+    get categories(): GraphQLErrorCategory[];
+}
+/**
+ * Network-related errors.
+ */
+export declare class NetworkError extends ClientError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, cause?: Error);
+}
+/**
+ * Missing field in response error.
+ */
+export declare class MissingFieldError extends ClientError {
+    readonly fieldName: string;
+    constructor(fieldName: string);
+}
+/**
+ * Missing data in response error.
+ */
+export declare class MissingDataError extends ClientError {
+    constructor();
+}
+/**
+ * Extract a required field from an optional value.
+ */
+export declare function extractField<T>(value: T | null | undefined, fieldName: string): T;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,WAAW,GACX,YAAY,GACZ,WAAW,GACX,UAAU,GACV,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,SAAS,CAAC;AAed;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,GACxB,oBAAoB,CAwCtB;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,KAAK,CAAC,EAAE,KAAK;gBAD7B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,WAAW;aAGzB,MAAM,EAAE,kBAAkB,EAAE;gBAD5C,OAAO,EAAE,MAAM,EACC,MAAM,GAAE,kBAAkB,EAAO,EACjD,KAAK,CAAC,EAAE,KAAK;IAMf,MAAM,CAAC,iBAAiB,CACtB,MAAM,EAAE,SAAS,qBAAqB,EAAE,GACvC,YAAY;IAgBf,IAAI,UAAU,IAAI,oBAAoB,EAAE,CAIvC;CACF;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,WAAW;aAGzB,UAAU,CAAC,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,KAAK,CAAC,EAAE,KAAK;CAKhB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;aACpB,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAI9C;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;;CAKhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,GAChB,CAAC,CAKH"}

package/dist/errors.js

@@ -0,0 +1,135 @@
+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) {
+    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 {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ClientError';
+    }
+}
+/**
+ * GraphQL-specific errors.
+ */
+export class GraphQLError extends ClientError {
+    errors;
+    constructor(message, errors = [], cause) {
+        super(message, cause);
+        this.errors = errors;
+        this.name = 'GraphQLError';
+    }
+    static fromGraphQLErrors(errors) {
+        const serverErrors = errors.map((err) => {
+            const extensions = err.extensions;
+            return {
+                message: err.message,
+                code: extensions?.code,
+                status: extensions?.status,
+                backtrace: extensions?.backtrace,
+            };
+        });
+        return new GraphQLError(`GraphQL errors: ${serverErrors.map((e) => e.message).join(', ')}`, serverErrors);
+    }
+    get categories() {
+        return Array.from(new Set(this.errors.map((error) => classifyGraphQLError(error))));
+    }
+}
+/**
+ * Network-related errors.
+ */
+export class NetworkError extends ClientError {
+    statusCode;
+    constructor(message, statusCode, cause) {
+        super(message, cause);
+        this.statusCode = statusCode;
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Missing field in response error.
+ */
+export class MissingFieldError extends ClientError {
+    fieldName;
+    constructor(fieldName) {
+        super(`Missing field in response: ${fieldName}`);
+        this.fieldName = 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(value, fieldName) {
+    if (value === null || value === undefined) {
+        throw new MissingFieldError(fieldName);
+    }
+    return value;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}