@robosystems/client 0.2.49 → 0.3.1

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.js

@@ -81,7 +81,7 @@ function isValidJWT(token) {
  */
 function extractTokenFromSDKClient() {
     // Import dynamically to avoid circular dependency
-    const { client } = require('../sdk/client.gen');
+    const { client } = require('../client.gen');
     const sdkConfig = getSDKExtensionsConfig();
     // Priority 1: Use explicitly configured token
     if (sdkConfig.token) {

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
@@ -94,7 +114,7 @@ export function isValidJWT(token: string | undefined): boolean {
  */
 export function extractTokenFromSDKClient(): string | undefined {
   // Import dynamically to avoid circular dependency
-  const { client } = require('../sdk/client.gen')
+  const { client } = require('../client.gen')
 
   const sdkConfig = getSDKExtensionsConfig()
 

package/extensions/graphql/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * GraphQL client factory used internally by the facade clients.
+ *
+ * This is an implementation detail — consumers never interact with it
+ * directly. They call methods on LedgerClient / InvestorClient / etc.,
+ * which use this to execute GraphQL queries against
+ * `/extensions/{graph_id}/graphql`.
+ *
+ * **Graph scoping.** The GraphQL endpoint is mounted per-graph at
+ * `/extensions/{graph_id}/graphql`. Resolvers read the graph from the URL
+ * path parameter — never from GraphQL variables. Every facade method
+ * takes a `graphId` and resolves the correct per-graph client via
+ * `getGraphQLClient(graphId)`, which caches one `GraphQLClient` instance
+ * per graph to avoid rebuilding headers + URLs on every call.
+ *
+ * We pick graphql-request (tiny, no React, no caching) because the facade
+ * doesn't need the hook ergonomics that urql/Apollo provide. Type safety
+ * comes from GraphQL Code Generator, which produces typed DocumentNodes
+ * 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';
+}
+/**
+ * Build a new GraphQL client for the given graph. Prefer
+ * `GraphQLClientCache.get(graphId)` in facade code — this is the raw
+ * factory and bypasses the cache.
+ */
+export declare function createGraphQLClient(config: GraphQLClientConfig, graphId: string): GraphQLClient;
+/**
+ * Per-graph cache of GraphQL clients. Facade clients own one instance of
+ * this and call `.get(graphId)` on every GraphQL method — cheap after the
+ * first call per graph.
+ */
+export declare class GraphQLClientCache {
+    private config;
+    private clients;
+    constructor(config: GraphQLClientConfig);
+    get(graphId: string): GraphQLClient;
+    /**
+     * 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

@@ -0,0 +1,149 @@
+'use client';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphQLClientCache = void 0;
+exports.createGraphQLClient = createGraphQLClient;
+/**
+ * GraphQL client factory used internally by the facade clients.
+ *
+ * This is an implementation detail — consumers never interact with it
+ * directly. They call methods on LedgerClient / InvestorClient / etc.,
+ * which use this to execute GraphQL queries against
+ * `/extensions/{graph_id}/graphql`.
+ *
+ * **Graph scoping.** The GraphQL endpoint is mounted per-graph at
+ * `/extensions/{graph_id}/graphql`. Resolvers read the graph from the URL
+ * path parameter — never from GraphQL variables. Every facade method
+ * takes a `graphId` and resolves the correct per-graph client via
+ * `getGraphQLClient(graphId)`, which caches one `GraphQLClient` instance
+ * per graph to avoid rebuilding headers + URLs on every call.
+ *
+ * We pick graphql-request (tiny, no React, no caching) because the facade
+ * doesn't need the hook ergonomics that urql/Apollo provide. Type safety
+ * comes from GraphQL Code Generator, which produces typed DocumentNodes
+ * 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
+ * factory and bypasses the cache.
+ */
+function createGraphQLClient(config, graphId) {
+    if (!graphId) {
+        throw new Error('createGraphQLClient requires a non-empty graphId');
+    }
+    const url = `${config.baseUrl.replace(/\/$/, '')}/extensions/${graphId}/graphql`;
+    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) {
+        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: staticHeaders,
+        credentials: config.credentials,
+    });
+}
+/**
+ * Per-graph cache of GraphQL clients. Facade clients own one instance of
+ * this and call `.get(graphId)` on every GraphQL method — cheap after the
+ * first call per graph.
+ */
+class GraphQLClientCache {
+    constructor(config) {
+        this.config = config;
+        this.clients = new Map();
+    }
+    get(graphId) {
+        const existing = this.clients.get(graphId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const client = createGraphQLClient(this.config, graphId);
+        this.clients.set(graphId, client);
+        return client;
+    }
+    /**
+     * 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();
+    }
+}
+exports.GraphQLClientCache = GraphQLClientCache;

package/extensions/graphql/client.ts

@@ -0,0 +1,189 @@
+'use client'
+
+/**
+ * GraphQL client factory used internally by the facade clients.
+ *
+ * This is an implementation detail — consumers never interact with it
+ * directly. They call methods on LedgerClient / InvestorClient / etc.,
+ * which use this to execute GraphQL queries against
+ * `/extensions/{graph_id}/graphql`.
+ *
+ * **Graph scoping.** The GraphQL endpoint is mounted per-graph at
+ * `/extensions/{graph_id}/graphql`. Resolvers read the graph from the URL
+ * path parameter — never from GraphQL variables. Every facade method
+ * takes a `graphId` and resolves the correct per-graph client via
+ * `getGraphQLClient(graphId)`, which caches one `GraphQLClient` instance
+ * per graph to avoid rebuilding headers + URLs on every call.
+ *
+ * We pick graphql-request (tiny, no React, no caching) because the facade
+ * doesn't need the hook ergonomics that urql/Apollo provide. Type safety
+ * comes from GraphQL Code Generator, which produces typed DocumentNodes
+ * 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'
+}
+
+/**
+ * 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
+ * factory and bypasses the cache.
+ */
+export function createGraphQLClient(config: GraphQLClientConfig, graphId: string): GraphQLClient {
+  if (!graphId) {
+    throw new Error('createGraphQLClient requires a non-empty graphId')
+  }
+  const url = `${config.baseUrl.replace(/\/$/, '')}/extensions/${graphId}/graphql`
+  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) {
+    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: staticHeaders,
+    credentials: config.credentials,
+  })
+}
+
+/**
+ * Per-graph cache of GraphQL clients. Facade clients own one instance of
+ * this and call `.get(graphId)` on every GraphQL method — cheap after the
+ * first call per graph.
+ */
+export class GraphQLClientCache {
+  private clients = new Map<string, GraphQLClient>()
+
+  constructor(private config: GraphQLClientConfig) {}
+
+  get(graphId: string): GraphQLClient {
+    const existing = this.clients.get(graphId)
+    if (existing !== undefined) {
+      return existing
+    }
+    const client = createGraphQLClient(this.config, graphId)
+    this.clients.set(graphId, client)
+    return client
+  }
+
+  /**
+   * 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()
+  }
+}