@robosystems/client 0.3.0 → 0.3.2

package/{extensions → artifacts}/config.d.ts

@@ -1,30 +1,49 @@
 /**
- * Configuration for SDK extensions
+ * Configuration for SDK clients
  * Provides centralized configuration for CORS, credentials, and other settings
  */
-export interface SDKExtensionsConfig {
+import type { TokenProvider } from './graphql/client';
+export interface SDKClientConfig {
     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
+     * `clients` 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;
 }
 /**
- * Set global configuration for SDK extensions
+ * Set global configuration for SDK clients
  * @param config Partial configuration to merge with defaults
  */
-export declare function setSDKExtensionsConfig(config: Partial<SDKExtensionsConfig>): void;
+export declare function setSDKClientConfig(config: Partial<SDKClientConfig>): void;
 /**
- * Get current SDK extensions configuration
+ * Get current SDK clients configuration
  * @returns Current configuration
  */
-export declare function getSDKExtensionsConfig(): SDKExtensionsConfig;
+export declare function getSDKClientConfig(): SDKClientConfig;
 /**
  * Reset configuration to defaults
  */
-export declare function resetSDKExtensionsConfig(): void;
+export declare function resetSDKClientConfig(): void;
 /**
  * Extract JWT token from Authorization header
  * @param authHeader Authorization header value
@@ -44,14 +63,14 @@ export declare function isValidJWT(token: string | undefined): boolean;
  */
 export declare function extractTokenFromSDKClient(): string | undefined;
 /**
- * Configure SDK extensions for JWT authentication
+ * Configure SDK clients for JWT authentication
  * @param token JWT token
  * @param config Additional configuration options
  */
-export declare function configureWithJWT(token: string, config?: Partial<SDKExtensionsConfig>): void;
+export declare function configureWithJWT(token: string, config?: Partial<SDKClientConfig>): void;
 /**
  * Get configuration for a specific environment
  * @param env Environment name (production, staging, development)
  * @returns Environment-specific configuration
  */
-export declare function getEnvironmentConfig(env?: 'production' | 'staging' | 'development'): SDKExtensionsConfig;
+export declare function getEnvironmentConfig(env?: 'production' | 'staging' | 'development'): SDKClientConfig;

package/{extensions → artifacts}/config.js

@@ -1,9 +1,9 @@
 'use client';
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setSDKExtensionsConfig = setSDKExtensionsConfig;
-exports.getSDKExtensionsConfig = getSDKExtensionsConfig;
-exports.resetSDKExtensionsConfig = resetSDKExtensionsConfig;
+exports.setSDKClientConfig = setSDKClientConfig;
+exports.getSDKClientConfig = getSDKClientConfig;
+exports.resetSDKClientConfig = resetSDKClientConfig;
 exports.extractJWTFromHeader = extractJWTFromHeader;
 exports.isValidJWT = isValidJWT;
 exports.extractTokenFromSDKClient = extractTokenFromSDKClient;
@@ -21,26 +21,26 @@ const defaultConfig = {
 // Global configuration singleton
 let globalConfig = { ...defaultConfig };
 /**
- * Set global configuration for SDK extensions
+ * Set global configuration for SDK clients
  * @param config Partial configuration to merge with defaults
  */
-function setSDKExtensionsConfig(config) {
+function setSDKClientConfig(config) {
     globalConfig = {
         ...globalConfig,
         ...config,
     };
 }
 /**
- * Get current SDK extensions configuration
+ * Get current SDK clients configuration
  * @returns Current configuration
  */
-function getSDKExtensionsConfig() {
+function getSDKClientConfig() {
     return { ...globalConfig };
 }
 /**
  * Reset configuration to defaults
  */
-function resetSDKExtensionsConfig() {
+function resetSDKClientConfig() {
     globalConfig = { ...defaultConfig };
 }
 /**
@@ -82,7 +82,7 @@ function isValidJWT(token) {
 function extractTokenFromSDKClient() {
     // Import dynamically to avoid circular dependency
     const { client } = require('../client.gen');
-    const sdkConfig = getSDKExtensionsConfig();
+    const sdkConfig = getSDKClientConfig();
     // Priority 1: Use explicitly configured token
     if (sdkConfig.token) {
         return sdkConfig.token;
@@ -101,7 +101,7 @@ function extractTokenFromSDKClient() {
     return undefined;
 }
 /**
- * Configure SDK extensions for JWT authentication
+ * Configure SDK clients for JWT authentication
  * @param token JWT token
  * @param config Additional configuration options
  */
@@ -109,7 +109,7 @@ function configureWithJWT(token, config) {
     if (!isValidJWT(token)) {
         console.warn('Warning: Provided JWT token does not appear to be valid');
     }
-    setSDKExtensionsConfig({
+    setSDKClientConfig({
         ...config,
         token,
         // When using JWT, typically don't need cookies

package/{extensions → artifacts}/config.ts

@@ -1,22 +1,42 @@
 'use client'
 
 /**
- * Configuration for SDK extensions
+ * Configuration for SDK clients
  * Provides centralized configuration for CORS, credentials, and other settings
  */
 
-export interface SDKExtensionsConfig {
+import type { TokenProvider } from './graphql/client'
+
+export interface SDKClientConfig {
   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
+   * `clients` 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
 }
 
 // Default configuration
-const defaultConfig: SDKExtensionsConfig = {
+const defaultConfig: SDKClientConfig = {
   baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
   credentials: 'include',
   token: undefined, // Will be set from environment or programmatically
@@ -26,13 +46,13 @@ const defaultConfig: SDKExtensionsConfig = {
 }
 
 // Global configuration singleton
-let globalConfig: SDKExtensionsConfig = { ...defaultConfig }
+let globalConfig: SDKClientConfig = { ...defaultConfig }
 
 /**
- * Set global configuration for SDK extensions
+ * Set global configuration for SDK clients
  * @param config Partial configuration to merge with defaults
  */
-export function setSDKExtensionsConfig(config: Partial<SDKExtensionsConfig>) {
+export function setSDKClientConfig(config: Partial<SDKClientConfig>) {
   globalConfig = {
     ...globalConfig,
     ...config,
@@ -40,17 +60,17 @@ export function setSDKExtensionsConfig(config: Partial<SDKExtensionsConfig>) {
 }
 
 /**
- * Get current SDK extensions configuration
+ * Get current SDK clients configuration
  * @returns Current configuration
  */
-export function getSDKExtensionsConfig(): SDKExtensionsConfig {
+export function getSDKClientConfig(): SDKClientConfig {
   return { ...globalConfig }
 }
 
 /**
  * Reset configuration to defaults
  */
-export function resetSDKExtensionsConfig() {
+export function resetSDKClientConfig() {
   globalConfig = { ...defaultConfig }
 }
 
@@ -96,7 +116,7 @@ export function extractTokenFromSDKClient(): string | undefined {
   // Import dynamically to avoid circular dependency
   const { client } = require('../client.gen')
 
-  const sdkConfig = getSDKExtensionsConfig()
+  const sdkConfig = getSDKClientConfig()
 
   // Priority 1: Use explicitly configured token
   if (sdkConfig.token) {
@@ -119,16 +139,16 @@ export function extractTokenFromSDKClient(): string | undefined {
 }
 
 /**
- * Configure SDK extensions for JWT authentication
+ * Configure SDK clients for JWT authentication
  * @param token JWT token
  * @param config Additional configuration options
  */
-export function configureWithJWT(token: string, config?: Partial<SDKExtensionsConfig>) {
+export function configureWithJWT(token: string, config?: Partial<SDKClientConfig>) {
   if (!isValidJWT(token)) {
     console.warn('Warning: Provided JWT token does not appear to be valid')
   }
 
-  setSDKExtensionsConfig({
+  setSDKClientConfig({
     ...config,
     token,
     // When using JWT, typically don't need cookies
@@ -143,8 +163,8 @@ export function configureWithJWT(token: string, config?: Partial<SDKExtensionsCo
  */
 export function getEnvironmentConfig(
   env: 'production' | 'staging' | 'development' = 'development'
-): SDKExtensionsConfig {
-  const baseConfigs: Record<string, Partial<SDKExtensionsConfig>> = {
+): SDKClientConfig {
+  const baseConfigs: Record<string, Partial<SDKClientConfig>> = {
     production: {
       baseUrl: process.env.NEXT_PUBLIC_API_URL || 'https://api.robosystems.ai',
       credentials: 'include',

package/artifacts/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 clients/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/artifacts/graphql/client.js

@@ -0,0 +1,148 @@
+'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 clients/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.
+                    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;