@robosystems/client 0.6.2 → 1.0.0

package/README.md

@@ -10,9 +10,9 @@ Official TypeScript Client for the RoboSystems Financial Knowledge Graph API. Ac
 - **Type-safe API client** with full TypeScript types
 - **Browser & Node.js support** with different auth strategies
 - **React hooks** for seamless UI integration
-- **Table ingestion** with simplified Parquet file uploads
+- **High-level domain clients** for RoboLedger, RoboInvestor, and the element library
 - **Streaming support** for memory-efficient processing of large result sets
-- **Financial AI Agent** integration for natural language queries
+- **AI Operator** integration for natural language financial analysis
 - **Comprehensive error handling** with typed errors
 
 ## Installation

package/artifacts/InvestorClient.d.ts

@@ -1,6 +1,7 @@
 import type { CreatePortfolioBlockRequest, CreateSecurityRequest, PortfolioBlockPortfolioPatch, PortfolioBlockPositions, UpdateSecurityOperation } from '../types.gen';
 import type { TokenProvider } from './graphql/client';
 import { type GetInvestorHoldingsQuery, type GetInvestorPortfolioBlockQuery, type GetInvestorPositionQuery, type GetInvestorSecurityQuery, type ListInvestorPortfoliosQuery, type ListInvestorPositionsQuery, type ListInvestorSecuritiesQuery } from './graphql/generated/graphql';
+export { GraphQLError } from './graphql/client';
 export type InvestorPortfolioList = NonNullable<ListInvestorPortfoliosQuery['portfolios']>;
 export type InvestorPortfolioSummary = InvestorPortfolioList['portfolios'][number];
 export type InvestorPortfolioBlock = NonNullable<GetInvestorPortfolioBlockQuery['portfolioBlock']>;
@@ -27,6 +28,8 @@ interface InvestorClientConfig {
      * request so refreshes flow through automatically.
      */
     tokenProvider?: TokenProvider;
+    /** GraphQL request timeout in milliseconds (default 60s). */
+    timeout?: number;
 }
 export declare class InvestorClient {
     private config;
@@ -110,4 +113,3 @@ export declare class InvestorClient {
     private gqlQuery;
     private callOperation;
 }
-export {};

package/artifacts/InvestorClient.js

@@ -1,11 +1,15 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvestorClient = void 0;
+exports.InvestorClient = exports.GraphQLError = void 0;
 const graphql_request_1 = require("graphql-request");
 const sdk_gen_1 = require("../sdk.gen");
 const client_1 = require("./graphql/client");
 const graphql_1 = require("./graphql/generated/graphql");
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/investor` subpath can `instanceof` it.
+var client_2 = require("./graphql/client");
+Object.defineProperty(exports, "GraphQLError", { enumerable: true, get: function () { return client_2.GraphQLError; } });
 class InvestorClient {
     constructor(config) {
         this.config = config;
@@ -141,7 +145,7 @@ class InvestorClient {
         }
         catch (err) {
             if (err instanceof graphql_request_1.ClientError) {
-                throw new Error(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`);
+                throw (0, client_1.toGraphQLError)(label, err);
             }
             throw err;
         }

package/artifacts/InvestorClient.ts

@@ -42,7 +42,7 @@ import type {
   UpdateSecurityOperation,
 } from '../types.gen'
 import type { TokenProvider } from './graphql/client'
-import { GraphQLClientCache } from './graphql/client'
+import { GraphQLClientCache, toGraphQLError } from './graphql/client'
 import {
   GetInvestorHoldingsDocument,
   GetInvestorPortfolioBlockDocument,
@@ -60,6 +60,10 @@ import {
   type ListInvestorSecuritiesQuery,
 } from './graphql/generated/graphql'
 
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/investor` subpath can `instanceof` it.
+export { GraphQLError } from './graphql/client'
+
 // ── Friendly types derived from GraphQL codegen ────────────────────────
 
 export type InvestorPortfolioList = NonNullable<ListInvestorPortfoliosQuery['portfolios']>
@@ -95,6 +99,8 @@ interface InvestorClientConfig {
    * request so refreshes flow through automatically.
    */
   tokenProvider?: TokenProvider
+  /** GraphQL request timeout in milliseconds (default 60s). */
+  timeout?: number
 }
 
 export class InvestorClient {
@@ -363,7 +369,7 @@ export class InvestorClient {
       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/LedgerClient.d.ts

@@ -1,6 +1,7 @@
 import type { AssociationResponse, AutoMapElementsOperation, BindTextBlockRequest, BindTextBlockResponse, ComputeMetricsRequest, ComputeMetricsResponse, CreateAgentRequest, CreateEventBlockRequest, CreateEventHandlerRequest, CreateInformationBlockRequest, CreateMappingAssociationOperation, CreateTaxonomyBlockRequest, CreateViewRequest, DeleteInformationBlockRequest, DeleteInformationBlockResponse, DeleteMappingAssociationOperation, DeleteResult, DeleteTaxonomyBlockRequest, DeleteTaxonomyBlockResponse, EntityTaxonomyResponse, EvaluateRulesRequest, EvaluateRulesResponse, EventBlockEnvelope, EventHandlerResponse, FinancialStatementAnalysisRequest, FinancialStatementAnalysisResponse, InformationBlockEnvelope, JournalEntryResponse, LedgerAgentResponse, LinkEntityTaxonomyRequest, LiveFinancialStatementRequest, LiveFinancialStatementResponse, OperationEnvelope, PreviewEventBlockResponse, PublishListMemberResponse, PublishListResponse, ReportResponse, ShareReportResponse, TaxonomyBlockEnvelope, UpdateAgentRequest, UpdateEntityRequest, UpdateEventBlockRequest, UpdateEventHandlerRequest, UpdateInformationBlockRequest, UpdateJournalEntryRequest, UpdateTaxonomyBlockRequest, ViewResponse } from '../types.gen';
 import type { TokenProvider } from './graphql/client';
 import { type GetInformationBlockQuery, type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerAgentQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerEventBlockQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerPublishListQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerReportPackageQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListInformationBlocksQuery, type ListLedgerAccountsQuery, type ListLedgerAgentsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerEventBlocksQuery, type ListLedgerMappingsQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery, type MappingCandidatesQuery, type ReportDownloadFormat } from './graphql/generated/graphql';
+export { GraphQLError } from './graphql/client';
 export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
 export type LedgerEntitySummary = ListLedgerEntitiesQuery['entities'][number];
 export type LedgerSummary = NonNullable<GetLedgerSummaryQuery['summary']>;
@@ -89,18 +90,6 @@ export interface CreateReportOptions {
     comparative?: boolean;
     periods?: PeriodSpecInput[];
 }
-/**
- * Wrapper returned by report write methods — pairs the audit-side
- * envelope fields (`operationId`, `status`) with the typed result
- * payload. Generic on ``T`` so each method advertises its specific
- * result type (e.g. ``ReportResponse`` for creates, ``DeleteResult``
- * for deletes).
- */
-export interface ReportOperationAck<T = unknown> {
-    operationId: string;
-    status: OperationEnvelope['status'];
-    result: T | null;
-}
 export interface InitializeLedgerResult {
     fiscalCalendar: LedgerFiscalCalendar;
     periodsCreated: number;
@@ -218,6 +207,8 @@ interface LedgerClientConfig {
      * request so refreshes flow through automatically.
      */
     tokenProvider?: TokenProvider;
+    /** GraphQL request timeout in milliseconds (default 60s). */
+    timeout?: number;
 }
 export declare class LedgerClient {
     private config;
@@ -635,10 +626,11 @@ export declare class LedgerClient {
      */
     private gqlQuery;
     /**
-     * Kick off report creation (async). Use the returned `operationId` to
-     * subscribe to progress via SSE, then call `getReport()` once finished.
+     * Generate report facts from the ledger and publish a Report
+     * definition. Synchronous — the backend materializes the report
+     * inline and this resolves with the published report header.
      */
-    createReport(graphId: string, options: CreateReportOptions): Promise<ReportOperationAck<ReportResponse>>;
+    createReport(graphId: string, options: CreateReportOptions): Promise<ReportResponse>;
     /** List all reports for a graph (includes received shared reports). */
     listReports(graphId: string): Promise<ReportListItem[]>;
     /** Get a single report with its period list + available structures. */
@@ -657,10 +649,11 @@ export declare class LedgerClient {
      */
     getStatement(graphId: string, reportId: string, blockType: string): Promise<StatementData | null>;
     /**
-     * Regenerate an existing report (async). Returns an operation id;
-     * subscribe via SSE for progress.
+     * Re-run fact generation for an existing Report against the latest
+     * ledger state. Synchronous — resolves with the regenerated report
+     * header.
      */
-    regenerateReport(graphId: string, reportId: string, periodStart?: string, periodEnd?: string): Promise<ReportOperationAck<ReportResponse>>;
+    regenerateReport(graphId: string, reportId: string, periodStart?: string, periodEnd?: string): Promise<ReportResponse>;
     /** Delete a report and its generated facts. */
     deleteReport(graphId: string, reportId: string): Promise<DeleteResult>;
     /**
@@ -693,20 +686,24 @@ export declare class LedgerClient {
     /**
      * Share a published report to every member of a publish list. Each
      * target graph receives a snapshot copy of the report's facts.
+     * Synchronous — per-recipient outcomes appear in the response's
+     * `results` list.
      */
-    shareReport(graphId: string, reportId: string, publishListId: string): Promise<ReportOperationAck<ShareReportResponse>>;
+    shareReport(graphId: string, reportId: string, publishListId: string): Promise<ShareReportResponse>;
     /**
      * Transition a Report's filing_status to 'filed' — locks the package.
      * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
-     * from the auth context + server clock.
+     * from the auth context + server clock. Synchronous — resolves with
+     * the updated report header.
      */
-    fileReport(graphId: string, reportId: string): Promise<ReportOperationAck<ReportResponse>>;
+    fileReport(graphId: string, reportId: string): Promise<ReportResponse>;
     /**
      * Move a Report along the non-file legs of the filing lifecycle
      * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
-     * reach 'filed' so the audit fields land cleanly.
+     * reach 'filed' so the audit fields land cleanly. Synchronous —
+     * resolves with the updated report header.
      */
-    transitionFilingStatus(graphId: string, reportId: string, targetStatus: string): Promise<ReportOperationAck<ReportResponse>>;
+    transitionFilingStatus(graphId: string, reportId: string, targetStatus: string): Promise<ReportResponse>;
     /** Check if a report was received via sharing (vs locally created). */
     isSharedReport(report: Report): boolean;
     /** List publish lists with pagination. */
@@ -751,9 +748,10 @@ export declare class LedgerClient {
      * calls. Mirrors the GraphQL client's behaviour — dynamic
      * ``tokenProvider`` is consulted first (so JWT rotation flows
      * naturally), then the static ``token`` config. Returns ``null``
-     * when no credential is configured; the caller decides whether to
-     * proceed anonymously or short-circuit with an error.
+     * when no credential is configured (cookie-based / anonymous flows).
+     * A ``tokenProvider`` that **throws** fails the call fast instead of
+     * silently proceeding unauthenticated — matching the Python client,
+     * which raises when its configured credential cannot be resolved.
      */
     private resolveToken;
 }
-export {};

package/artifacts/LedgerClient.js

@@ -1,11 +1,15 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LedgerClient = void 0;
+exports.LedgerClient = exports.GraphQLError = void 0;
 const graphql_request_1 = require("graphql-request");
 const sdk_gen_1 = require("../sdk.gen");
 const client_1 = require("./graphql/client");
 const graphql_1 = require("./graphql/generated/graphql");
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/ledger` subpath can `instanceof` it.
+var client_2 = require("./graphql/client");
+Object.defineProperty(exports, "GraphQLError", { enumerable: true, get: function () { return client_2.GraphQLError; } });
 class LedgerClient {
     constructor(config) {
         this.config = config;
@@ -790,15 +794,16 @@ class LedgerClient {
         }
         catch (err) {
             if (err instanceof graphql_request_1.ClientError) {
-                throw new Error(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`);
+                throw (0, client_1.toGraphQLError)(label, err);
             }
             throw err;
         }
     }
     // ── Reports ─────────────────────────────────────────────────────────
     /**
-     * Kick off report creation (async). Use the returned `operationId` to
-     * subscribe to progress via SSE, then call `getReport()` once finished.
+     * Generate report facts from the ledger and publish a Report
+     * definition. Synchronous — the backend materializes the report
+     * inline and this resolves with the published report header.
      */
     async createReport(graphId, options) {
         const body = {
@@ -814,11 +819,7 @@ class LedgerClient {
             body.periods = options.periods;
         }
         const envelope = await this.callOperation('Create report', (0, sdk_gen_1.createReport)({ path: { graph_id: graphId }, body }));
-        return {
-            operationId: envelope.operationId,
-            status: envelope.status,
-            result: envelope.result ?? null,
-        };
+        return this.requireResult('Create report', envelope.result);
     }
     /** List all reports for a graph (includes received shared reports). */
     async listReports(graphId) {
@@ -847,8 +848,9 @@ class LedgerClient {
         return this.gqlQuery(graphId, graphql_1.GetLedgerStatementDocument, { reportId, blockType }, 'Get statement', (data) => data.statement);
     }
     /**
-     * Regenerate an existing report (async). Returns an operation id;
-     * subscribe via SSE for progress.
+     * Re-run fact generation for an existing Report against the latest
+     * ledger state. Synchronous — resolves with the regenerated report
+     * header.
      */
     async regenerateReport(graphId, reportId, periodStart, periodEnd) {
         const envelope = await this.callOperation('Regenerate report', (0, sdk_gen_1.regenerateReport)({
@@ -859,11 +861,7 @@ class LedgerClient {
                 period_end: periodEnd,
             },
         }));
-        return {
-            operationId: envelope.operationId,
-            status: envelope.status,
-            result: envelope.result ?? null,
-        };
+        return this.requireResult('Regenerate report', envelope.result);
     }
     /** Delete a report and its generated facts. */
     async deleteReport(graphId, reportId) {
@@ -917,6 +915,8 @@ class LedgerClient {
     /**
      * Share a published report to every member of a publish list. Each
      * target graph receives a snapshot copy of the report's facts.
+     * Synchronous — per-recipient outcomes appear in the response's
+     * `results` list.
      */
     async shareReport(graphId, reportId, publishListId) {
         const envelope = await this.callOperation('Share report', (0, sdk_gen_1.shareReport)({
@@ -926,30 +926,24 @@ class LedgerClient {
                 publish_list_id: publishListId,
             },
         }));
-        return {
-            operationId: envelope.operationId,
-            status: envelope.status,
-            result: envelope.result ?? null,
-        };
+        return this.requireResult('Share report', envelope.result);
     }
     /**
      * Transition a Report's filing_status to 'filed' — locks the package.
      * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
-     * from the auth context + server clock.
+     * from the auth context + server clock. Synchronous — resolves with
+     * the updated report header.
      */
     async fileReport(graphId, reportId) {
         const body = { report_id: reportId };
         const envelope = await this.callOperation('File report', (0, sdk_gen_1.fileReport)({ path: { graph_id: graphId }, body }));
-        return {
-            operationId: envelope.operationId,
-            status: envelope.status,
-            result: envelope.result ?? null,
-        };
+        return this.requireResult('File report', envelope.result);
     }
     /**
      * Move a Report along the non-file legs of the filing lifecycle
      * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
-     * reach 'filed' so the audit fields land cleanly.
+     * reach 'filed' so the audit fields land cleanly. Synchronous —
+     * resolves with the updated report header.
      */
     async transitionFilingStatus(graphId, reportId, targetStatus) {
         const body = {
@@ -957,11 +951,7 @@ class LedgerClient {
             target_status: targetStatus,
         };
         const envelope = await this.callOperation('Transition filing status', (0, sdk_gen_1.transitionFilingStatus)({ path: { graph_id: graphId }, body }));
-        return {
-            operationId: envelope.operationId,
-            status: envelope.status,
-            result: envelope.result ?? null,
-        };
+        return this.requireResult('Transition filing status', envelope.result);
     }
     /** Check if a report was received via sharing (vs locally created). */
     isSharedReport(report) {
@@ -1065,19 +1055,24 @@ class LedgerClient {
      * calls. Mirrors the GraphQL client's behaviour — dynamic
      * ``tokenProvider`` is consulted first (so JWT rotation flows
      * naturally), then the static ``token`` config. Returns ``null``
-     * when no credential is configured; the caller decides whether to
-     * proceed anonymously or short-circuit with an error.
+     * when no credential is configured (cookie-based / anonymous flows).
+     * A ``tokenProvider`` that **throws** fails the call fast instead of
+     * silently proceeding unauthenticated — matching the Python client,
+     * which raises when its configured credential cannot be resolved.
      */
     async resolveToken() {
         if (this.config.tokenProvider) {
+            let token;
             try {
-                const token = await this.config.tokenProvider();
-                return token ?? null;
+                token = await this.config.tokenProvider();
             }
             catch (err) {
-                console.warn('[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:', err);
-                return null;
+                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.');
             }
+            return token ?? null;
         }
         return this.config.token ?? null;
     }

package/artifacts/LedgerClient.ts

@@ -131,7 +131,7 @@ import type {
   ViewResponse,
 } from '../types.gen'
 import type { TokenProvider } from './graphql/client'
-import { GraphQLClientCache } from './graphql/client'
+import { GraphQLClientCache, toGraphQLError } from './graphql/client'
 import {
   GetInformationBlockDocument,
   GetInformationBlockWindowedDocument,
@@ -208,6 +208,10 @@ import {
   type ReportDownloadFormat,
 } from './graphql/generated/graphql'
 
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/ledger` subpath can `instanceof` it.
+export { GraphQLError } from './graphql/client'
+
 // ── Friendly types derived from GraphQL codegen ────────────────────────
 //
 // These are the single source of truth for read payload shapes. Write
@@ -334,19 +338,6 @@ export interface CreateReportOptions {
   periods?: PeriodSpecInput[]
 }
 
-/**
- * Wrapper returned by report write methods — pairs the audit-side
- * envelope fields (`operationId`, `status`) with the typed result
- * payload. Generic on ``T`` so each method advertises its specific
- * result type (e.g. ``ReportResponse`` for creates, ``DeleteResult``
- * for deletes).
- */
-export interface ReportOperationAck<T = unknown> {
-  operationId: string
-  status: OperationEnvelope['status']
-  result: T | null
-}
-
 // ── Write result shapes (envelope.result payloads) ─────────────────────
 //
 // Backend Pydantic models serialize these write results in snake_case.
@@ -536,6 +527,8 @@ interface LedgerClientConfig {
    * request so refreshes flow through automatically.
    */
   tokenProvider?: TokenProvider
+  /** GraphQL request timeout in milliseconds (default 60s). */
+  timeout?: number
 }
 
 export class LedgerClient {
@@ -1941,7 +1934,7 @@ export class LedgerClient {
       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
     }
@@ -1950,13 +1943,11 @@ export class LedgerClient {
   // ── Reports ─────────────────────────────────────────────────────────
 
   /**
-   * Kick off report creation (async). Use the returned `operationId` to
-   * subscribe to progress via SSE, then call `getReport()` once finished.
+   * Generate report facts from the ledger and publish a Report
+   * definition. Synchronous — the backend materializes the report
+   * inline and this resolves with the published report header.
    */
-  async createReport(
-    graphId: string,
-    options: CreateReportOptions
-  ): Promise<ReportOperationAck<ReportResponse>> {
+  async createReport(graphId: string, options: CreateReportOptions): Promise<ReportResponse> {
     const body: CreateReportRequest = {
       name: options.name,
       mapping_id: options.mappingId,
@@ -1973,11 +1964,7 @@ export class LedgerClient {
       'Create report',
       createReport({ path: { graph_id: graphId }, body })
     )
-    return {
-      operationId: envelope.operationId,
-      status: envelope.status,
-      result: envelope.result ?? null,
-    }
+    return this.requireResult('Create report', envelope.result)
   }
 
   /** List all reports for a graph (includes received shared reports). */
@@ -2039,15 +2026,16 @@ export class LedgerClient {
   }
 
   /**
-   * Regenerate an existing report (async). Returns an operation id;
-   * subscribe via SSE for progress.
+   * Re-run fact generation for an existing Report against the latest
+   * ledger state. Synchronous — resolves with the regenerated report
+   * header.
    */
   async regenerateReport(
     graphId: string,
     reportId: string,
     periodStart?: string,
     periodEnd?: string
-  ): Promise<ReportOperationAck<ReportResponse>> {
+  ): Promise<ReportResponse> {
     const envelope = await this.callOperation(
       'Regenerate report',
       regenerateReport({
@@ -2059,11 +2047,7 @@ export class LedgerClient {
         } as Parameters<typeof regenerateReport>[0]['body'],
       })
     )
-    return {
-      operationId: envelope.operationId,
-      status: envelope.status,
-      result: envelope.result ?? null,
-    }
+    return this.requireResult('Regenerate report', envelope.result)
   }
 
   /** Delete a report and its generated facts. */
@@ -2132,12 +2116,14 @@ export class LedgerClient {
   /**
    * Share a published report to every member of a publish list. Each
    * target graph receives a snapshot copy of the report's facts.
+   * Synchronous — per-recipient outcomes appear in the response's
+   * `results` list.
    */
   async shareReport(
     graphId: string,
     reportId: string,
     publishListId: string
-  ): Promise<ReportOperationAck<ShareReportResponse>> {
+  ): Promise<ShareReportResponse> {
     const envelope = await this.callOperation(
       'Share report',
       shareReport({
@@ -2148,41 +2134,35 @@ export class LedgerClient {
         } as Parameters<typeof shareReport>[0]['body'],
       })
     )
-    return {
-      operationId: envelope.operationId,
-      status: envelope.status,
-      result: envelope.result ?? null,
-    }
+    return this.requireResult('Share report', envelope.result)
   }
 
   /**
    * Transition a Report's filing_status to 'filed' — locks the package.
    * Allowed from 'draft' or 'under_review'. Stamps filed_at + filed_by
-   * from the auth context + server clock.
+   * from the auth context + server clock. Synchronous — resolves with
+   * the updated report header.
    */
-  async fileReport(graphId: string, reportId: string): Promise<ReportOperationAck<ReportResponse>> {
+  async fileReport(graphId: string, reportId: string): Promise<ReportResponse> {
     const body: FileReportRequest = { report_id: reportId }
     const envelope = await this.callOperation(
       'File report',
       fileReport({ path: { graph_id: graphId }, body })
     )
-    return {
-      operationId: envelope.operationId,
-      status: envelope.status,
-      result: envelope.result ?? null,
-    }
+    return this.requireResult('File report', envelope.result)
   }
 
   /**
    * Move a Report along the non-file legs of the filing lifecycle
    * (draft ↔ under_review, filed → archived). Use ``fileReport`` to
-   * reach 'filed' so the audit fields land cleanly.
+   * reach 'filed' so the audit fields land cleanly. Synchronous —
+   * resolves with the updated report header.
    */
   async transitionFilingStatus(
     graphId: string,
     reportId: string,
     targetStatus: string
-  ): Promise<ReportOperationAck<ReportResponse>> {
+  ): Promise<ReportResponse> {
     const body: TransitionFilingStatusRequest = {
       report_id: reportId,
       target_status: targetStatus,
@@ -2191,11 +2171,7 @@ export class LedgerClient {
       'Transition filing status',
       transitionFilingStatus({ path: { graph_id: graphId }, body })
     )
-    return {
-      operationId: envelope.operationId,
-      status: envelope.status,
-      result: envelope.result ?? null,
-    }
+    return this.requireResult('Transition filing status', envelope.result)
   }
 
   /** Check if a report was received via sharing (vs locally created). */
@@ -2361,21 +2337,25 @@ export class LedgerClient {
    * calls. Mirrors the GraphQL client's behaviour — dynamic
    * ``tokenProvider`` is consulted first (so JWT rotation flows
    * naturally), then the static ``token`` config. Returns ``null``
-   * when no credential is configured; the caller decides whether to
-   * proceed anonymously or short-circuit with an error.
+   * when no credential is configured (cookie-based / anonymous flows).
+   * A ``tokenProvider`` that **throws** fails the call fast instead of
+   * silently proceeding unauthenticated — matching the Python client,
+   * which raises when its configured credential cannot be resolved.
    */
   private async resolveToken(): Promise<string | null> {
     if (this.config.tokenProvider) {
+      let token: string | null | undefined
       try {
-        const token = await this.config.tokenProvider()
-        return token ?? null
+        token = await this.config.tokenProvider()
       } catch (err) {
-        console.warn(
-          '[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:',
-          err
+        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.'
         )
-        return null
       }
+      return token ?? null
     }
     return this.config.token ?? null
   }

package/artifacts/LibraryClient.d.ts

@@ -1,5 +1,6 @@
 import type { TokenProvider } from './graphql/client';
 import { type GetLibraryElementArcsQuery, type GetLibraryElementClassificationsQuery, type GetLibraryElementEquivalentsQuery, type GetLibraryElementQuery, type GetLibraryTaxonomyQuery, type ListLibraryElementsQuery, type ListLibraryStructuresQuery, type ListLibraryTaxonomiesQuery, type ListLibraryTaxonomyArcsQuery, type SearchLibraryElementsQuery } from './graphql/generated/graphql';
+export { GraphQLError } from './graphql/client';
 export type LibraryTaxonomy = ListLibraryTaxonomiesQuery['libraryTaxonomies'][number];
 export type LibraryTaxonomyDetail = NonNullable<GetLibraryTaxonomyQuery['libraryTaxonomy']>;
 export type LibraryElement = ListLibraryElementsQuery['libraryElements'][number];
@@ -68,6 +69,8 @@ interface LibraryClientConfig {
      * request so refreshes flow through automatically.
      */
     tokenProvider?: TokenProvider;
+    /** GraphQL request timeout in milliseconds (default 60s). */
+    timeout?: number;
 }
 export declare class LibraryClient {
     private config;
@@ -131,4 +134,3 @@ export declare class LibraryClient {
     getLibraryElementEquivalents(graphId: string, id: string): Promise<LibraryEquivalence | null>;
     private gqlQuery;
 }
-export {};

package/artifacts/LibraryClient.js

@@ -1,10 +1,14 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LibraryClient = exports.LIBRARY_GRAPH_ID = void 0;
+exports.LibraryClient = exports.LIBRARY_GRAPH_ID = exports.GraphQLError = void 0;
 const graphql_request_1 = require("graphql-request");
 const client_1 = require("./graphql/client");
 const graphql_1 = require("./graphql/generated/graphql");
+// Re-export the structured GraphQL error type so consumers importing
+// from the `@robosystems/client/library` subpath can `instanceof` it.
+var client_2 = require("./graphql/client");
+Object.defineProperty(exports, "GraphQLError", { enumerable: true, get: function () { return client_2.GraphQLError; } });
 // ── Client ──────────────────────────────────────────────────────────────
 /**
  * Sentinel graph_id for the canonical library read surface. Passing
@@ -139,7 +143,7 @@ class LibraryClient {
         }
         catch (err) {
             if (err instanceof graphql_request_1.ClientError) {
-                throw new Error(`${label} failed: ${JSON.stringify(err.response.errors ?? err.message)}`);
+                throw (0, client_1.toGraphQLError)(label, err);
             }
             throw err;
         }