@robosystems/client 0.3.0 → 0.3.1

package/extensions/InvestorClient.d.ts

@@ -1,4 +1,5 @@
 import type { CreatePortfolioRequest, CreatePositionRequest, CreateSecurityRequest, UpdatePortfolioOperation, UpdatePositionOperation, UpdateSecurityOperation } from '../types.gen';
+import type { TokenProvider } from './graphql/client';
 import { type GetInvestorHoldingsQuery, type GetInvestorPortfolioQuery, type GetInvestorPositionQuery, type GetInvestorSecurityQuery, type ListInvestorPortfoliosQuery, type ListInvestorPositionsQuery, type ListInvestorSecuritiesQuery } from './graphql/generated/graphql';
 export type InvestorPortfolioList = NonNullable<ListInvestorPortfoliosQuery['portfolios']>;
 export type InvestorPortfolioSummary = InvestorPortfolioList['portfolios'][number];
@@ -16,7 +17,13 @@ interface InvestorClientConfig {
     baseUrl: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    /** Static credential — use `tokenProvider` instead if the JWT rotates. */
     token?: string;
+    /**
+     * Dynamic credential callback. When set, invoked on every GraphQL
+     * request so refreshes flow through automatically.
+     */
+    tokenProvider?: TokenProvider;
 }
 export declare class InvestorClient {
     private config;

package/extensions/InvestorClient.ts

@@ -38,6 +38,7 @@ import type {
   UpdatePositionOperation,
   UpdateSecurityOperation,
 } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
   GetInvestorHoldingsDocument,
@@ -80,7 +81,13 @@ interface InvestorClientConfig {
   baseUrl: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
+  /** Static credential — use `tokenProvider` instead if the JWT rotates. */
   token?: string
+  /**
+   * Dynamic credential callback. When set, invoked on every GraphQL
+   * request so refreshes flow through automatically.
+   */
+  tokenProvider?: TokenProvider
 }
 
 export class InvestorClient {

package/extensions/LedgerClient.d.ts

@@ -1,4 +1,5 @@
 import type { AutoMapElementsOperation, CreateMappingAssociationOperation, CreateStructureRequest, CreateTaxonomyRequest, DeleteMappingAssociationOperation, OperationEnvelope, UpdateEntityRequest } from '../types.gen';
+import type { TokenProvider } from './graphql/client';
 import { type GetLedgerAccountRollupsQuery, type GetLedgerAccountTreeQuery, type GetLedgerClosingBookStructuresQuery, type GetLedgerEntityQuery, type GetLedgerFiscalCalendarQuery, type GetLedgerMappedTrialBalanceQuery, type GetLedgerMappingCoverageQuery, type GetLedgerMappingQuery, type GetLedgerPeriodCloseStatusQuery, type GetLedgerPeriodDraftsQuery, type GetLedgerReportingTaxonomyQuery, type GetLedgerScheduleFactsQuery, type GetLedgerSummaryQuery, type GetLedgerTransactionQuery, type GetLedgerTrialBalanceQuery, type ListLedgerAccountsQuery, type ListLedgerElementsQuery, type ListLedgerEntitiesQuery, type ListLedgerMappingsQuery, type ListLedgerSchedulesQuery, type ListLedgerStructuresQuery, type ListLedgerTaxonomiesQuery, type ListLedgerTransactionsQuery, type ListLedgerUnmappedElementsQuery } from './graphql/generated/graphql';
 export type LedgerEntity = NonNullable<GetLedgerEntityQuery['entity']>;
 export type LedgerEntitySummary = ListLedgerEntitiesQuery['entities'][number];
@@ -125,7 +126,13 @@ interface LedgerClientConfig {
     baseUrl: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    /** Static credential — use `tokenProvider` instead if the JWT rotates. */
     token?: string;
+    /**
+     * Dynamic credential callback. When set, invoked on every GraphQL
+     * request so refreshes flow through automatically.
+     */
+    tokenProvider?: TokenProvider;
 }
 export declare class LedgerClient {
     private config;

package/extensions/LedgerClient.ts

@@ -57,6 +57,7 @@ import type {
   TruncateScheduleOperation,
   UpdateEntityRequest,
 } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
   GetLedgerAccountRollupsDocument,
@@ -347,7 +348,13 @@ interface LedgerClientConfig {
   baseUrl: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
+  /** Static credential — use `tokenProvider` instead if the JWT rotates. */
   token?: string
+  /**
+   * Dynamic credential callback. When set, invoked on every GraphQL
+   * request so refreshes flow through automatically.
+   */
+  tokenProvider?: TokenProvider
 }
 
 export class LedgerClient {

package/extensions/ReportClient.d.ts

@@ -1,4 +1,5 @@
 import type { OperationEnvelope } from '../types.gen';
+import type { TokenProvider } from './graphql/client';
 import { type GetLedgerPublishListQuery, type GetLedgerReportQuery, type GetLedgerStatementQuery, type ListLedgerPublishListsQuery, type ListLedgerReportsQuery } from './graphql/generated/graphql';
 export type Report = NonNullable<GetLedgerReportQuery['report']>;
 export type ReportListItem = NonNullable<ListLedgerReportsQuery['reports']>['reports'][number];
@@ -50,7 +51,13 @@ interface ReportClientConfig {
     baseUrl: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    /** Static credential — use `tokenProvider` instead if the JWT rotates. */
     token?: string;
+    /**
+     * Dynamic credential callback. When set, invoked on every GraphQL
+     * request so refreshes flow through automatically.
+     */
+    tokenProvider?: TokenProvider;
 }
 export declare class ReportClient {
     private config;

package/extensions/ReportClient.ts

@@ -42,6 +42,7 @@ import type {
   OperationEnvelope,
   UpdatePublishListOperation,
 } from '../types.gen'
+import type { TokenProvider } from './graphql/client'
 import { GraphQLClientCache } from './graphql/client'
 import {
   GetLedgerPublishListDocument,
@@ -119,7 +120,13 @@ interface ReportClientConfig {
   baseUrl: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
+  /** Static credential — use `tokenProvider` instead if the JWT rotates. */
   token?: string
+  /**
+   * Dynamic credential callback. When set, invoked on every GraphQL
+   * request so refreshes flow through automatically.
+   */
+  tokenProvider?: TokenProvider
 }
 
 export class ReportClient {

package/extensions/config.d.ts

@@ -2,11 +2,30 @@
  * Configuration for SDK extensions
  * Provides centralized configuration for CORS, credentials, and other settings
  */
+import type { TokenProvider } from './graphql/client';
 export interface SDKExtensionsConfig {
     baseUrl?: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    /**
+     * Static credential captured at singleton construction. Fine for
+     * long-lived API keys — use `tokenProvider` instead when the
+     * JWT can rotate mid-session (browser login flows).
+     *
+     * When both `token` and `tokenProvider` are set, `tokenProvider`
+     * wins — the static value is effectively ignored. Pass
+     * `tokenProvider: undefined` to explicitly switch back to the
+     * static-token path.
+     */
     token?: string;
+    /**
+     * Dynamic credential callback, invoked on every GraphQL request.
+     * When set, JWT refresh flows through automatically: the lazy
+     * `extensions` singleton picks it up at construction, and each
+     * request consults the callback for the current token instead of
+     * reusing a stale captured value.
+     */
+    tokenProvider?: TokenProvider;
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;

package/extensions/config.ts

@@ -5,11 +5,31 @@
  * Provides centralized configuration for CORS, credentials, and other settings
  */
 
+import type { TokenProvider } from './graphql/client'
+
 export interface SDKExtensionsConfig {
   baseUrl?: string
   credentials?: 'include' | 'same-origin' | 'omit'
   headers?: Record<string, string>
-  token?: string // JWT token for authentication
+  /**
+   * Static credential captured at singleton construction. Fine for
+   * long-lived API keys — use `tokenProvider` instead when the
+   * JWT can rotate mid-session (browser login flows).
+   *
+   * When both `token` and `tokenProvider` are set, `tokenProvider`
+   * wins — the static value is effectively ignored. Pass
+   * `tokenProvider: undefined` to explicitly switch back to the
+   * static-token path.
+   */
+  token?: string
+  /**
+   * Dynamic credential callback, invoked on every GraphQL request.
+   * When set, JWT refresh flows through automatically: the lazy
+   * `extensions` singleton picks it up at construction, and each
+   * request consults the callback for the current token instead of
+   * reusing a stale captured value.
+   */
+  tokenProvider?: TokenProvider
   timeout?: number
   maxRetries?: number
   retryDelay?: number

package/extensions/graphql/client.d.ts

@@ -19,9 +19,36 @@
  * from the query files in sdk-extensions/graphql/queries/.
  */
 import { GraphQLClient } from 'graphql-request';
+/**
+ * Callback that returns the current auth credential on demand.
+ *
+ * Use this instead of the static `token` field when the credential
+ * can rotate during the lifetime of the client — the primary case
+ * is short-lived JWTs that auto-refresh from browser token storage.
+ * The provider is invoked on **every** GraphQL request, so the
+ * returned value should be cheap to obtain (a localStorage read or
+ * an in-memory lookup, not a network call if avoidable).
+ *
+ * May return `null`/`undefined` to indicate "no credential available
+ * right now" — the request will be sent unauthenticated in that
+ * case, which lets the caller distinguish auth-expired errors from
+ * never-authed errors at the transport layer.
+ */
+export type TokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
 export interface GraphQLClientConfig {
     baseUrl: string;
+    /**
+     * Static credential captured at construction time. Use this when
+     * the token won't rotate (e.g. CLI/server flows using a long-lived
+     * API key). For JWT flows prefer `tokenProvider` so refreshes are
+     * picked up without rebuilding the client.
+     */
     token?: string;
+    /**
+     * Dynamic credential callback, read on every request. Wins over
+     * `token` when both are set. See `TokenProvider` for semantics.
+     */
+    tokenProvider?: TokenProvider;
     headers?: Record<string, string>;
     credentials?: 'include' | 'same-origin' | 'omit';
 }
@@ -41,6 +68,15 @@ export declare class GraphQLClientCache {
     private clients;
     constructor(config: GraphQLClientConfig);
     get(graphId: string): GraphQLClient;
-    /** Drop all cached clients. Useful after a token rotation. */
+    /**
+     * Drop all cached clients. Only needed when swapping **static**
+     * credentials — e.g. replacing the `token` field on a long-lived
+     * facade between tenants, or resetting a CLI session. When the
+     * cache was built from a `tokenProvider`, rotation is handled
+     * per-request inside `requestMiddleware` and `clear()` is a no-op
+     * for auth purposes (the cached `GraphQLClient` instances keep
+     * using the same provider reference and will pick up the next
+     * token automatically).
+     */
     clear(): void;
 }

package/extensions/graphql/client.js

@@ -24,6 +24,26 @@ exports.createGraphQLClient = createGraphQLClient;
  * from the query files in sdk-extensions/graphql/queries/.
  */
 const graphql_request_1 = require("graphql-request");
+/**
+ * Apply a credential to an in-progress request's headers, choosing
+ * the right header based on token shape:
+ *
+ *   - `rfs…` prefix → `X-API-Key` (long-lived API key, validated
+ *     against the database's api_keys table).
+ *   - anything else → `Authorization: Bearer …` (short-lived JWT,
+ *     validated by JWT middleware).
+ *
+ * The two credential types are NOT interchangeable at the backend —
+ * sending a JWT as `X-API-Key` or an API key as Bearer both 401.
+ */
+function applyAuthHeader(headers, token) {
+    if (token.startsWith('rfs')) {
+        headers.set('X-API-Key', token);
+    }
+    else {
+        headers.set('Authorization', `Bearer ${token}`);
+    }
+}
 /**
  * Build a new GraphQL client for the given graph. Prefer
  * `GraphQLClientCache.get(graphId)` in facade code — this is the raw
@@ -34,17 +54,62 @@ function createGraphQLClient(config, graphId) {
         throw new Error('createGraphQLClient requires a non-empty graphId');
     }
     const url = `${config.baseUrl.replace(/\/$/, '')}/extensions/${graphId}/graphql`;
-    const headers = {
+    const staticHeaders = {
         ...(config.headers ?? {}),
     };
+    // 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
+    // flows where the token in localStorage rotates every ~30 minutes.
+    if (config.tokenProvider) {
+        const providerFn = config.tokenProvider;
+        return new graphql_request_1.GraphQLClient(url, {
+            headers: staticHeaders,
+            credentials: config.credentials,
+            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.
+                    // eslint-disable-next-line no-console
+                    console.warn('[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:', err);
+                    token = undefined;
+                }
+                if (!token) {
+                    return request;
+                }
+                // `request.headers` is a HeadersInit (Headers | string[][] |
+                // Record<string, string>), so normalize via Headers before
+                // mutating. Spreading it directly loses keys when it's a
+                // Headers instance.
+                const merged = new Headers(request.headers);
+                applyAuthHeader(merged, token);
+                return { ...request, headers: merged };
+            },
+        });
+    }
+    // Static-token path: pick the right header at construction time.
+    // Suitable for long-lived API keys that never rotate.
     if (config.token) {
-        // The backend accepts both Authorization: Bearer and X-API-Key. Match
-        // the existing facade convention of sending the token as X-API-Key,
-        // which is what the local dev workflow uses.
-        headers['X-API-Key'] = config.token;
+        const headers = new Headers(staticHeaders);
+        applyAuthHeader(headers, config.token);
+        return new graphql_request_1.GraphQLClient(url, {
+            headers,
+            credentials: config.credentials,
+        });
     }
+    // No credentials at all — used by unauthenticated introspection
+    // queries against public dev endpoints.
     return new graphql_request_1.GraphQLClient(url, {
-        headers,
+        headers: staticHeaders,
         credentials: config.credentials,
     });
 }
@@ -67,7 +132,16 @@ class GraphQLClientCache {
         this.clients.set(graphId, client);
         return client;
     }
-    /** Drop all cached clients. Useful after a token rotation. */
+    /**
+     * Drop all cached clients. Only needed when swapping **static**
+     * credentials — e.g. replacing the `token` field on a long-lived
+     * facade between tenants, or resetting a CLI session. When the
+     * cache was built from a `tokenProvider`, rotation is handled
+     * per-request inside `requestMiddleware` and `clear()` is a no-op
+     * for auth purposes (the cached `GraphQLClient` instances keep
+     * using the same provider reference and will pick up the next
+     * token automatically).
+     */
     clear() {
         this.clients.clear();
     }

package/extensions/graphql/client.ts

@@ -23,13 +23,61 @@
 
 import { GraphQLClient } from 'graphql-request'
 
+/**
+ * Callback that returns the current auth credential on demand.
+ *
+ * Use this instead of the static `token` field when the credential
+ * can rotate during the lifetime of the client — the primary case
+ * is short-lived JWTs that auto-refresh from browser token storage.
+ * The provider is invoked on **every** GraphQL request, so the
+ * returned value should be cheap to obtain (a localStorage read or
+ * an in-memory lookup, not a network call if avoidable).
+ *
+ * May return `null`/`undefined` to indicate "no credential available
+ * right now" — the request will be sent unauthenticated in that
+ * case, which lets the caller distinguish auth-expired errors from
+ * never-authed errors at the transport layer.
+ */
+export type TokenProvider = () => string | null | undefined | Promise<string | null | undefined>
+
 export interface GraphQLClientConfig {
   baseUrl: string
+  /**
+   * Static credential captured at construction time. Use this when
+   * the token won't rotate (e.g. CLI/server flows using a long-lived
+   * API key). For JWT flows prefer `tokenProvider` so refreshes are
+   * picked up without rebuilding the client.
+   */
   token?: string
+  /**
+   * Dynamic credential callback, read on every request. Wins over
+   * `token` when both are set. See `TokenProvider` for semantics.
+   */
+  tokenProvider?: TokenProvider
   headers?: Record<string, string>
   credentials?: 'include' | 'same-origin' | 'omit'
 }
 
+/**
+ * Apply a credential to an in-progress request's headers, choosing
+ * the right header based on token shape:
+ *
+ *   - `rfs…` prefix → `X-API-Key` (long-lived API key, validated
+ *     against the database's api_keys table).
+ *   - anything else → `Authorization: Bearer …` (short-lived JWT,
+ *     validated by JWT middleware).
+ *
+ * The two credential types are NOT interchangeable at the backend —
+ * sending a JWT as `X-API-Key` or an API key as Bearer both 401.
+ */
+function applyAuthHeader(headers: Headers, token: string): void {
+  if (token.startsWith('rfs')) {
+    headers.set('X-API-Key', token)
+  } else {
+    headers.set('Authorization', `Bearer ${token}`)
+  }
+}
+
 /**
  * Build a new GraphQL client for the given graph. Prefer
  * `GraphQLClientCache.get(graphId)` in facade code — this is the raw
@@ -40,17 +88,67 @@ export function createGraphQLClient(config: GraphQLClientConfig, graphId: string
     throw new Error('createGraphQLClient requires a non-empty graphId')
   }
   const url = `${config.baseUrl.replace(/\/$/, '')}/extensions/${graphId}/graphql`
-  const headers: Record<string, string> = {
+  const staticHeaders: Record<string, string> = {
     ...(config.headers ?? {}),
   }
+
+  // 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
+  // flows where the token in localStorage rotates every ~30 minutes.
+  if (config.tokenProvider) {
+    const providerFn = config.tokenProvider
+    return new GraphQLClient(url, {
+      headers: staticHeaders,
+      credentials: config.credentials,
+      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.
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[RoboSystems SDK] tokenProvider threw — sending unauthenticated request:',
+            err
+          )
+          token = undefined
+        }
+        if (!token) {
+          return request
+        }
+        // `request.headers` is a HeadersInit (Headers | string[][] |
+        // Record<string, string>), so normalize via Headers before
+        // mutating. Spreading it directly loses keys when it's a
+        // Headers instance.
+        const merged = new Headers(request.headers as HeadersInit | undefined)
+        applyAuthHeader(merged, token)
+        return { ...request, headers: merged }
+      },
+    })
+  }
+
+  // Static-token path: pick the right header at construction time.
+  // Suitable for long-lived API keys that never rotate.
   if (config.token) {
-    // The backend accepts both Authorization: Bearer and X-API-Key. Match
-    // the existing facade convention of sending the token as X-API-Key,
-    // which is what the local dev workflow uses.
-    headers['X-API-Key'] = config.token
+    const headers = new Headers(staticHeaders)
+    applyAuthHeader(headers, config.token)
+    return new GraphQLClient(url, {
+      headers,
+      credentials: config.credentials,
+    })
   }
+
+  // No credentials at all — used by unauthenticated introspection
+  // queries against public dev endpoints.
   return new GraphQLClient(url, {
-    headers,
+    headers: staticHeaders,
     credentials: config.credentials,
   })
 }
@@ -75,7 +173,16 @@ export class GraphQLClientCache {
     return client
   }
 
-  /** Drop all cached clients. Useful after a token rotation. */
+  /**
+   * Drop all cached clients. Only needed when swapping **static**
+   * credentials — e.g. replacing the `token` field on a long-lived
+   * facade between tenants, or resetting a CLI session. When the
+   * cache was built from a `tokenProvider`, rotation is handled
+   * per-request inside `requestMiddleware` and `clear()` is a no-op
+   * for auth purposes (the cached `GraphQLClient` instances keep
+   * using the same provider reference and will pick up the next
+   * token automatically).
+   */
   clear(): void {
     this.clients.clear()
   }

package/extensions/index.d.ts

@@ -2,6 +2,7 @@
  * RoboSystems SDK Extensions
  * Enhanced clients with SSE support for the RoboSystems API
  */
+import type { TokenProvider } from './graphql/client';
 import { OperationClient } from './OperationClient';
 import { QueryClient } from './QueryClient';
 import { AgentClient } from './AgentClient';
@@ -9,10 +10,22 @@ import { SSEClient } from './SSEClient';
 import { InvestorClient } from './InvestorClient';
 import { LedgerClient } from './LedgerClient';
 import { ReportClient } from './ReportClient';
+export type { TokenProvider } from './graphql/client';
 export interface RoboSystemsExtensionConfig {
     baseUrl?: string;
     credentials?: 'include' | 'same-origin' | 'omit';
+    /**
+     * Static credential captured at construction time. Fine for
+     * long-lived API keys; use `tokenProvider` instead when the JWT
+     * can rotate (browser login flows).
+     */
     token?: string;
+    /**
+     * Dynamic credential callback invoked on every GraphQL request.
+     * When set, JWT refreshes are picked up automatically — no need
+     * to rebuild or clear cached clients after a refresh.
+     */
+    tokenProvider?: TokenProvider;
     headers?: Record<string, string>;
     maxRetries?: number;
     retryDelay?: number;

package/extensions/index.js

@@ -41,10 +41,15 @@ class RoboSystemsExtensions {
         const sdkConfig = client_gen_1.client.getConfig();
         // Extract JWT token using centralized logic
         const token = config.token || (0, config_1.extractTokenFromSDKClient)();
+        // `tokenProvider` falls back to the global SDK extensions config so
+        // apps can wire refresh once via `setSDKExtensionsConfig({ tokenProvider })`
+        // and have the lazy default singleton pick it up automatically.
+        const tokenProvider = config.tokenProvider || (0, config_1.getSDKExtensionsConfig)().tokenProvider;
         this.config = {
             baseUrl: config.baseUrl || sdkConfig.baseUrl || 'http://localhost:8000',
             credentials: config.credentials || 'include',
             token,
+            tokenProvider,
             headers: config.headers,
             maxRetries: config.maxRetries || 5,
             retryDelay: config.retryDelay || 1000,
@@ -68,22 +73,30 @@ class RoboSystemsExtensions {
             maxRetries: this.config.maxRetries,
             retryDelay: this.config.retryDelay,
         });
+        // LedgerClient / InvestorClient / ReportClient all use GraphQL
+        // internally, so they get the tokenProvider — REST-only clients
+        // (QueryClient / AgentClient / OperationClient / SSEClient) do
+        // not, because their refresh story lives in the main SDK client
+        // wrapper, not here.
         this.ledger = new LedgerClient_1.LedgerClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
         });
         this.investor = new InvestorClient_1.InvestorClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
         });
         this.reports = new ReportClient_1.ReportClient({
             baseUrl: this.config.baseUrl,
             credentials: this.config.credentials,
             token: this.config.token,
+            tokenProvider: this.config.tokenProvider,
             headers: this.config.headers,
         });
     }

package/extensions/index.ts

@@ -4,7 +4,8 @@
  */
 
 import { client } from '../client.gen'
-import { extractTokenFromSDKClient } from './config'
+import { extractTokenFromSDKClient, getSDKExtensionsConfig } from './config'
+import type { TokenProvider } from './graphql/client'
 import { OperationClient } from './OperationClient'
 import { QueryClient } from './QueryClient'
 import { AgentClient } from './AgentClient'
@@ -13,10 +14,27 @@ import { InvestorClient } from './InvestorClient'
 import { LedgerClient } from './LedgerClient'
 import { ReportClient } from './ReportClient'
 
+// Re-export the `TokenProvider` type so consumers who want to type
+// their own callback (`const provider: TokenProvider = () => …`) can
+// pull it from the package root instead of reaching into the
+// internal `./graphql/client` module path.
+export type { TokenProvider } from './graphql/client'
+
 export interface RoboSystemsExtensionConfig {
   baseUrl?: string
   credentials?: 'include' | 'same-origin' | 'omit'
-  token?: string // JWT token for authentication
+  /**
+   * Static credential captured at construction time. Fine for
+   * long-lived API keys; use `tokenProvider` instead when the JWT
+   * can rotate (browser login flows).
+   */
+  token?: string
+  /**
+   * Dynamic credential callback invoked on every GraphQL request.
+   * When set, JWT refreshes are picked up automatically — no need
+   * to rebuild or clear cached clients after a refresh.
+   */
+  tokenProvider?: TokenProvider
   headers?: Record<string, string>
   maxRetries?: number
   retryDelay?: number
@@ -27,6 +45,7 @@ interface ResolvedConfig {
   baseUrl: string
   credentials: 'include' | 'same-origin' | 'omit'
   token?: string
+  tokenProvider?: TokenProvider
   headers?: Record<string, string>
   maxRetries: number
   retryDelay: number
@@ -48,10 +67,16 @@ export class RoboSystemsExtensions {
     // Extract JWT token using centralized logic
     const token = config.token || extractTokenFromSDKClient()
 
+    // `tokenProvider` falls back to the global SDK extensions config so
+    // apps can wire refresh once via `setSDKExtensionsConfig({ tokenProvider })`
+    // and have the lazy default singleton pick it up automatically.
+    const tokenProvider = config.tokenProvider || getSDKExtensionsConfig().tokenProvider
+
     this.config = {
       baseUrl: config.baseUrl || sdkConfig.baseUrl || 'http://localhost:8000',
       credentials: config.credentials || 'include',
       token,
+      tokenProvider,
       headers: config.headers,
       maxRetries: config.maxRetries || 5,
       retryDelay: config.retryDelay || 1000,
@@ -79,10 +104,16 @@ export class RoboSystemsExtensions {
       retryDelay: this.config.retryDelay,
     })
 
+    // LedgerClient / InvestorClient / ReportClient all use GraphQL
+    // internally, so they get the tokenProvider — REST-only clients
+    // (QueryClient / AgentClient / OperationClient / SSEClient) do
+    // not, because their refresh story lives in the main SDK client
+    // wrapper, not here.
     this.ledger = new LedgerClient({
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
     })
 
@@ -90,6 +121,7 @@ export class RoboSystemsExtensions {
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
     })
 
@@ -97,6 +129,7 @@ export class RoboSystemsExtensions {
       baseUrl: this.config.baseUrl,
       credentials: this.config.credentials,
       token: this.config.token,
+      tokenProvider: this.config.tokenProvider,
       headers: this.config.headers,
     })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/client",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "TypeScript client library for RoboSystems Financial Knowledge Graph API",
   "main": "index.js",
   "types": "index.d.ts",