@robosystems/client 0.6.3 → 1.1.0

package/artifacts/LibraryClient.ts

@@ -29,7 +29,7 @@
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
 import { ClientError } from 'graphql-request'
 import type { TokenProvider } from './graphql/client'
-import { GraphQLClientCache } from './graphql/client'
+import { GraphQLClientCache, toGraphQLError } from './graphql/client'
 import {
   GetLibraryElementArcsDocument,
   GetLibraryElementClassificationsDocument,
@@ -53,6 +53,10 @@ import {
   type SearchLibraryElementsQuery,
 } from './graphql/generated/graphql'
 
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/library` subpath can `instanceof` it.
+export { GraphQLError } from './graphql/client'
+
 // ── Friendly types derived from GraphQL codegen ────────────────────────
 //
 // These are the single source of truth for library payload shapes —
@@ -144,6 +148,8 @@ interface LibraryClientConfig {
    * request so refreshes flow through automatically.
    */
   tokenProvider?: TokenProvider
+  /** GraphQL request timeout in milliseconds (default 60s). */
+  timeout?: number
 }
 
 export class LibraryClient {
@@ -388,7 +394,7 @@ export class LibraryClient {
       return pick(data)
     } catch (err) {
       if (err instanceof ClientError) {
-        throw new Error(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`)
+        throw toGraphQLError(label, err)
       }
       throw err
     }

package/artifacts/graphql/client.d.ts

@@ -18,7 +18,43 @@
  * comes from GraphQL Code Generator, which produces typed DocumentNodes
  * from the query files in clients/graphql/queries/.
  */
-import { GraphQLClient } from 'graphql-request';
+import { ClientError, GraphQLClient } from 'graphql-request';
+/**
+ * Default request timeout for GraphQL calls, in milliseconds.
+ *
+ * Matches the Python client's httpx default (60 seconds). Without a
+ * timeout a hung backend hangs callers forever — every GraphQL request
+ * carries an `AbortSignal.timeout(...)` so transport stalls surface as
+ * an abort error instead of an eternal pending promise. Override
+ * per-client via `GraphQLClientConfig.timeout`.
+ */
+export declare const DEFAULT_GRAPHQL_TIMEOUT_MS = 60000;
+/**
+ * Structured error thrown by facade GraphQL reads.
+ *
+ * Mirrors the Python client's `GraphQLError` (message, `errors`,
+ * `status_code`): the message keeps the legacy
+ * `"<label> failed: <json>"` format so string-matching consumers keep
+ * working, while the raw GraphQL error objects and HTTP status are
+ * available as structured fields for programmatic handling.
+ */
+export declare class GraphQLError extends Error {
+    /** Raw GraphQL error objects from the response body (empty for HTTP-level failures). */
+    readonly errors: unknown[];
+    /** HTTP status code, when known. */
+    readonly statusCode?: number;
+    constructor(message: string, options?: {
+        errors?: unknown[];
+        statusCode?: number;
+    });
+}
+/**
+ * Convert a graphql-request `ClientError` into the facade's structured
+ * {@link GraphQLError}, preserving the legacy message format
+ * (`"<label> failed: <json>"`). Shared by the LedgerClient /
+ * InvestorClient / LibraryClient `gqlQuery` catch paths.
+ */
+export declare function toGraphQLError(label: string, err: ClientError): GraphQLError;
 /**
  * Callback that returns the current auth credential on demand.
  *
@@ -51,6 +87,12 @@ export interface GraphQLClientConfig {
     tokenProvider?: TokenProvider;
     headers?: Record<string, string>;
     credentials?: 'include' | 'same-origin' | 'omit';
+    /**
+     * Request timeout in milliseconds. Defaults to
+     * {@link DEFAULT_GRAPHQL_TIMEOUT_MS} (60s, matching the Python
+     * client). Applied per request via `AbortSignal.timeout(...)`.
+     */
+    timeout?: number;
 }
 /**
  * Build a new GraphQL client for the given graph. Prefer

package/artifacts/graphql/client.js

@@ -1,7 +1,8 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphQLClientCache = void 0;
+exports.GraphQLClientCache = exports.GraphQLError = exports.DEFAULT_GRAPHQL_TIMEOUT_MS = void 0;
+exports.toGraphQLError = toGraphQLError;
 exports.createGraphQLClient = createGraphQLClient;
 /**
  * GraphQL client factory used internally by the facade clients.
@@ -24,6 +25,72 @@ exports.createGraphQLClient = createGraphQLClient;
  * from the query files in clients/graphql/queries/.
  */
 const graphql_request_1 = require("graphql-request");
+/**
+ * Default request timeout for GraphQL calls, in milliseconds.
+ *
+ * Matches the Python client's httpx default (60 seconds). Without a
+ * timeout a hung backend hangs callers forever — every GraphQL request
+ * carries an `AbortSignal.timeout(...)` so transport stalls surface as
+ * an abort error instead of an eternal pending promise. Override
+ * per-client via `GraphQLClientConfig.timeout`.
+ */
+exports.DEFAULT_GRAPHQL_TIMEOUT_MS = 60000;
+/**
+ * Structured error thrown by facade GraphQL reads.
+ *
+ * Mirrors the Python client's `GraphQLError` (message, `errors`,
+ * `status_code`): the message keeps the legacy
+ * `"<label> failed: <json>"` format so string-matching consumers keep
+ * working, while the raw GraphQL error objects and HTTP status are
+ * available as structured fields for programmatic handling.
+ */
+class GraphQLError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'GraphQLError';
+        this.errors = options?.errors ?? [];
+        this.statusCode = options?.statusCode;
+    }
+}
+exports.GraphQLError = GraphQLError;
+/**
+ * Convert a graphql-request `ClientError` into the facade's structured
+ * {@link GraphQLError}, preserving the legacy message format
+ * (`"<label> failed: <json>"`). Shared by the LedgerClient /
+ * InvestorClient / LibraryClient `gqlQuery` catch paths.
+ */
+function toGraphQLError(label, err) {
+    const errors = err.response.errors ?? [];
+    return new GraphQLError(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`, {
+        errors,
+        statusCode: err.response.status,
+    });
+}
+/**
+ * Wrap the global `fetch` so every request carries a timeout
+ * `AbortSignal`. If a signal is already present on the request we
+ * combine the two via `AbortSignal.any` (whichever aborts first wins);
+ * in environments without `AbortSignal.timeout` support the wrapper
+ * degrades to plain `fetch`.
+ *
+ * `fetch` is resolved from the global scope at call time (not
+ * captured at construction) so test harnesses that swap
+ * `globalThis.fetch` keep working.
+ */
+function createTimeoutFetch(timeoutMs) {
+    return (input, init) => {
+        if (typeof AbortSignal.timeout !== 'function') {
+            return fetch(input, init);
+        }
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const signal = init?.signal != null
+            ? typeof AbortSignal.any === 'function'
+                ? AbortSignal.any([init.signal, timeoutSignal])
+                : init.signal
+            : timeoutSignal;
+        return fetch(input, { ...init, signal });
+    };
+}
 /**
  * Apply a credential to an in-progress request's headers, choosing
  * the right header based on token shape:
@@ -57,6 +124,7 @@ function createGraphQLClient(config, graphId) {
     const staticHeaders = {
         ...(config.headers ?? {}),
     };
+    const timeoutFetch = createTimeoutFetch(config.timeout ?? exports.DEFAULT_GRAPHQL_TIMEOUT_MS);
     // Dynamic-token path: defer credential injection to a per-request
     // middleware so JWT refreshes are picked up without rebuilding or
     // clearing the client. This is the recommended path for browser
@@ -66,21 +134,24 @@ function createGraphQLClient(config, graphId) {
         return new graphql_request_1.GraphQLClient(url, {
             headers: staticHeaders,
             credentials: config.credentials,
+            fetch: timeoutFetch,
             requestMiddleware: async (request) => {
                 let token;
                 try {
                     token = await providerFn();
                 }
                 catch (err) {
-                    // A provider failure shouldn't crash the request — fall
-                    // through unauthenticated so the backend returns a clean
-                    // 401, which is easier to diagnose than a thrown middleware.
-                    // We still log a breadcrumb so the failure is visible in
-                    // devtools/log aggregators instead of silently disappearing;
-                    // silently swallowing provider bugs in production is worse
-                    // than the noise.
-                    console.warn('[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:', err);
-                    token = undefined;
+                    // Fail fast — a throwing provider means the caller *intended*
+                    // to authenticate but couldn't produce a credential. Sending
+                    // the request unauthenticated would surface as a confusing
+                    // 401 far from the real failure. (Matches the Python client,
+                    // which raises when its credential is missing.) A provider
+                    // that deliberately has no credential should return `null`
+                    // instead — that still sends an unauthenticated request.
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new Error(`RoboSystems SDK: tokenProvider threw while resolving the request credential (${detail}). ` +
+                        'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
+                        'returns the current token, or null to send an unauthenticated (cookie-based) request.');
                 }
                 if (!token) {
                     return request;
@@ -103,6 +174,7 @@ function createGraphQLClient(config, graphId) {
         return new graphql_request_1.GraphQLClient(url, {
             headers,
             credentials: config.credentials,
+            fetch: timeoutFetch,
         });
     }
     // No credentials at all — used by unauthenticated introspection
@@ -110,6 +182,7 @@ function createGraphQLClient(config, graphId) {
     return new graphql_request_1.GraphQLClient(url, {
         headers: staticHeaders,
         credentials: config.credentials,
+        fetch: timeoutFetch,
     });
 }
 /**

package/artifacts/graphql/client.ts

@@ -21,7 +21,58 @@
  * from the query files in clients/graphql/queries/.
  */
 
-import { GraphQLClient } from 'graphql-request'
+import { ClientError, GraphQLClient } from 'graphql-request'
+
+/**
+ * Default request timeout for GraphQL calls, in milliseconds.
+ *
+ * Matches the Python client's httpx default (60 seconds). Without a
+ * timeout a hung backend hangs callers forever — every GraphQL request
+ * carries an `AbortSignal.timeout(...)` so transport stalls surface as
+ * an abort error instead of an eternal pending promise. Override
+ * per-client via `GraphQLClientConfig.timeout`.
+ */
+export const DEFAULT_GRAPHQL_TIMEOUT_MS = 60_000
+
+/**
+ * Structured error thrown by facade GraphQL reads.
+ *
+ * Mirrors the Python client's `GraphQLError` (message, `errors`,
+ * `status_code`): the message keeps the legacy
+ * `"<label> failed: <json>"` format so string-matching consumers keep
+ * working, while the raw GraphQL error objects and HTTP status are
+ * available as structured fields for programmatic handling.
+ */
+export class GraphQLError extends Error {
+  /** Raw GraphQL error objects from the response body (empty for HTTP-level failures). */
+  readonly errors: unknown[]
+  /** HTTP status code, when known. */
+  readonly statusCode?: number
+
+  constructor(message: string, options?: { errors?: unknown[]; statusCode?: number }) {
+    super(message)
+    this.name = 'GraphQLError'
+    this.errors = options?.errors ?? []
+    this.statusCode = options?.statusCode
+  }
+}
+
+/**
+ * Convert a graphql-request `ClientError` into the facade's structured
+ * {@link GraphQLError}, preserving the legacy message format
+ * (`"<label> failed: <json>"`). Shared by the LedgerClient /
+ * InvestorClient / LibraryClient `gqlQuery` catch paths.
+ */
+export function toGraphQLError(label: string, err: ClientError): GraphQLError {
+  const errors = err.response.errors ?? []
+  return new GraphQLError(
+    `${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`,
+    {
+      errors,
+      statusCode: err.response.status,
+    }
+  )
+}
 
 /**
  * Callback that returns the current auth credential on demand.
@@ -56,6 +107,39 @@ export interface GraphQLClientConfig {
   tokenProvider?: TokenProvider
   headers?: Record<string, string>
   credentials?: 'include' | 'same-origin' | 'omit'
+  /**
+   * Request timeout in milliseconds. Defaults to
+   * {@link DEFAULT_GRAPHQL_TIMEOUT_MS} (60s, matching the Python
+   * client). Applied per request via `AbortSignal.timeout(...)`.
+   */
+  timeout?: number
+}
+
+/**
+ * Wrap the global `fetch` so every request carries a timeout
+ * `AbortSignal`. If a signal is already present on the request we
+ * combine the two via `AbortSignal.any` (whichever aborts first wins);
+ * in environments without `AbortSignal.timeout` support the wrapper
+ * degrades to plain `fetch`.
+ *
+ * `fetch` is resolved from the global scope at call time (not
+ * captured at construction) so test harnesses that swap
+ * `globalThis.fetch` keep working.
+ */
+function createTimeoutFetch(timeoutMs: number): typeof fetch {
+  return (input, init) => {
+    if (typeof AbortSignal.timeout !== 'function') {
+      return fetch(input, init)
+    }
+    const timeoutSignal = AbortSignal.timeout(timeoutMs)
+    const signal =
+      init?.signal != null
+        ? typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([init.signal, timeoutSignal])
+          : init.signal
+        : timeoutSignal
+    return fetch(input, { ...init, signal })
+  }
 }
 
 /**
@@ -91,6 +175,7 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
   const staticHeaders: Record<string, string> = {
     ...(config.headers ?? {}),
   }
+  const timeoutFetch = createTimeoutFetch(config.timeout ?? DEFAULT_GRAPHQL_TIMEOUT_MS)
 
   // Dynamic-token path: defer credential injection to a per-request
   // middleware so JWT refreshes are picked up without rebuilding or
@@ -101,24 +186,25 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
     return new GraphQLClient(url, {
       headers: staticHeaders,
       credentials: config.credentials,
+      fetch: timeoutFetch,
       requestMiddleware: async (request) => {
         let token: string | null | undefined
         try {
           token = await providerFn()
         } catch (err) {
-          // A provider failure shouldn't crash the request — fall
-          // through unauthenticated so the backend returns a clean
-          // 401, which is easier to diagnose than a thrown middleware.
-          // We still log a breadcrumb so the failure is visible in
-          // devtools/log aggregators instead of silently disappearing;
-          // silently swallowing provider bugs in production is worse
-          // than the noise.
-
-          console.warn(
-            '[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:',
-            err
+          // Fail fast — a throwing provider means the caller *intended*
+          // to authenticate but couldn't produce a credential. Sending
+          // the request unauthenticated would surface as a confusing
+          // 401 far from the real failure. (Matches the Python client,
+          // which raises when its credential is missing.) A provider
+          // that deliberately has no credential should return `null`
+          // instead — that still sends an unauthenticated request.
+          const detail = err instanceof Error ? err.message : String(err)
+          throw new Error(
+            `RoboSystems SDK: tokenProvider threw while resolving the request credential (${detail}). ` +
+              'Fix the tokenProvider passed in the client config (or via setSDKClientConfig) so it ' +
+              'returns the current token, or null to send an unauthenticated (cookie-based) request.'
           )
-          token = undefined
         }
         if (!token) {
           return request
@@ -142,6 +228,7 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
     return new GraphQLClient(url, {
       headers,
       credentials: config.credentials,
+      fetch: timeoutFetch,
     })
   }
 
@@ -150,6 +237,7 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
   return new GraphQLClient(url, {
     headers: staticHeaders,
     credentials: config.credentials,
+    fetch: timeoutFetch,
   })
 }
 

package/artifacts/index.d.ts

@@ -11,6 +11,7 @@ import { OperatorClient } from './OperatorClient';
 import { QueryClient } from './QueryClient';
 import { SSEClient } from './SSEClient';
 export type { TokenProvider } from './graphql/client';
+export { DEFAULT_GRAPHQL_TIMEOUT_MS, GraphQLError } from './graphql/client';
 export interface RoboSystemsClientConfig {
     baseUrl?: string;
     credentials?: 'include' | 'same-origin' | 'omit';
@@ -29,6 +30,11 @@ export interface RoboSystemsClientConfig {
     headers?: Record<string, string>;
     maxRetries?: number;
     retryDelay?: number;
+    /**
+     * GraphQL request timeout in milliseconds. Defaults to 60s
+     * (matching the Python client's httpx default) when omitted.
+     */
+    timeout?: number;
 }
 export declare class RoboSystemsClients {
     readonly query: QueryClient;

package/artifacts/index.js

@@ -18,7 +18,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analyzeFinancials = exports.operatorQuery = exports.streamQuery = exports.executeQuery = exports.monitorOperation = exports.clients = exports.useStreamingQuery = exports.useSDKClients = exports.useQuery = exports.useOperation = exports.useMultipleOperations = exports.SSEClient = exports.QueryClient = exports.OperatorClient = exports.OperationClient = exports.LibraryClient = exports.LedgerClient = exports.InvestorClient = exports.RoboSystemsClients = void 0;
+exports.analyzeFinancials = exports.operatorQuery = exports.streamQuery = exports.executeQuery = exports.monitorOperation = exports.clients = exports.useStreamingQuery = exports.useSDKClients = exports.useQuery = exports.useOperation = exports.useMultipleOperations = exports.SSEClient = exports.QueryClient = exports.OperatorClient = exports.OperationClient = exports.LibraryClient = exports.LedgerClient = exports.InvestorClient = exports.RoboSystemsClients = exports.GraphQLError = exports.DEFAULT_GRAPHQL_TIMEOUT_MS = void 0;
 const client_gen_1 = require("../client.gen");
 const config_1 = require("./config");
 const InvestorClient_1 = require("./InvestorClient");
@@ -35,6 +35,11 @@ const QueryClient_1 = require("./QueryClient");
 Object.defineProperty(exports, "QueryClient", { enumerable: true, get: function () { return QueryClient_1.QueryClient; } });
 const SSEClient_1 = require("./SSEClient");
 Object.defineProperty(exports, "SSEClient", { enumerable: true, get: function () { return SSEClient_1.SSEClient; } });
+// Structured GraphQL error thrown by facade reads (LedgerClient /
+// InvestorClient / LibraryClient), plus the default request timeout.
+var client_1 = require("./graphql/client");
+Object.defineProperty(exports, "DEFAULT_GRAPHQL_TIMEOUT_MS", { enumerable: true, get: function () { return client_1.DEFAULT_GRAPHQL_TIMEOUT_MS; } });
+Object.defineProperty(exports, "GraphQLError", { enumerable: true, get: function () { return client_1.GraphQLError; } });
 class RoboSystemsClients {
     constructor(config = {}) {
         // Get base URL from SDK client config or use provided/default
@@ -53,6 +58,7 @@ class RoboSystemsClients {
             headers: config.headers,
             maxRetries: config.maxRetries || 5,
             retryDelay: config.retryDelay || 1000,
+            timeout: config.timeout,
         };
         this.query = new QueryClient_1.QueryClient({
             baseUrl: this.config.baseUrl,
@@ -81,6 +87,7 @@ class RoboSystemsClients {
             token: this.config.token,
             tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
+            timeout: this.config.timeout,
         });
         this.investor = new InvestorClient_1.InvestorClient({
             baseUrl: this.config.baseUrl,
@@ -88,6 +95,7 @@ class RoboSystemsClients {
             token: this.config.token,
             tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
+            timeout: this.config.timeout,
         });
         // Library uses GraphQL and accepts graphId per-call — pass either
         // the `"library"` sentinel (canonical) or any tenant graph_id
@@ -98,6 +106,7 @@ class RoboSystemsClients {
             token: this.config.token,
             tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
+            timeout: this.config.timeout,
         });
         // Reports consolidated into LedgerClient — alias for backward compat
         this.reports = this.ledger;

package/artifacts/index.ts

@@ -20,6 +20,10 @@ import { SSEClient } from './SSEClient'
 // internal `./graphql/client` module path.
 export type { TokenProvider } from './graphql/client'
 
+// Structured GraphQL error thrown by facade reads (LedgerClient /
+// InvestorClient / LibraryClient), plus the default request timeout.
+export { DEFAULT_GRAPHQL_TIMEOUT_MS, GraphQLError } from './graphql/client'
+
 export interface RoboSystemsClientConfig {
   baseUrl?: string
   credentials?: 'include' | 'same-origin' | 'omit'
@@ -38,6 +42,11 @@ export interface RoboSystemsClientConfig {
   headers?: Record<string, string>
   maxRetries?: number
   retryDelay?: number
+  /**
+   * GraphQL request timeout in milliseconds. Defaults to 60s
+   * (matching the Python client's httpx default) when omitted.
+   */
+  timeout?: number
 }
 
 // Properly typed configuration interface
@@ -49,6 +58,7 @@ interface ResolvedConfig {
   headers?: Record<string, string>
   maxRetries: number
   retryDelay: number
+  timeout?: number
 }
 
 export class RoboSystemsClients {
@@ -85,6 +95,7 @@ export class RoboSystemsClients {
       headers: config.headers,
       maxRetries: config.maxRetries || 5,
       retryDelay: config.retryDelay || 1000,
+      timeout: config.timeout,
     }
 
     this.query = new QueryClient({
@@ -117,6 +128,7 @@ export class RoboSystemsClients {
       token: this.config.token,
       tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
+      timeout: this.config.timeout,
     })
 
     this.investor = new InvestorClient({
@@ -125,6 +137,7 @@ export class RoboSystemsClients {
       token: this.config.token,
       tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
+      timeout: this.config.timeout,
     })
 
     // Library uses GraphQL and accepts graphId per-call — pass either
@@ -136,6 +149,7 @@ export class RoboSystemsClients {
       token: this.config.token,
       tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
+      timeout: this.config.timeout,
     })
 
     // Reports consolidated into LedgerClient — alias for backward compat