@robosystems/client 0.1.20 → 0.1.22

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Harbinger FinLab
+Copyright (c) 2025 RFS LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,451 +3,38 @@
 [![npm version](https://badge.fury.io/js/@robosystems%2Fclient.svg)](https://www.npmjs.com/package/@robosystems/client)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official TypeScript Client for the RoboSystems Financial Knowledge Graph API. Access comprehensive financial data including accounting records, SEC filings, and advanced graph analytics through a type-safe, modern TypeScript interface.
+Official TypeScript Client for the RoboSystems Financial Knowledge Graph API. Access comprehensive financial data including accounting transactions, financial reports, and advanced graph analytics through a type-safe, modern TypeScript interface.
 
 ## Features
 
 - **Type-safe API client** with full TypeScript types
-- **Auto-generated from OpenAPI** for always up-to-date types
 - **Browser & Node.js support** with different auth strategies
 - **React hooks** for seamless UI integration
-- **Queue handling** for long-running operations
-- **Streaming support** for large datasets
-- **Financial AI Agent** integration
+- **Streaming support** for memory-efficient processing of large result sets
+- **Financial AI Agent** integration for natural language queries
 - **Comprehensive error handling** with typed errors
 
 ## Installation
 
 ```bash
 npm install @robosystems/client
-# or
-yarn add @robosystems/client
-# or
-pnpm add @robosystems/client
-```
-
-## Quick Start
-
-### Browser Usage (with cookies)
-
-```typescript
-import { client, getUserMe, listCompanies, executeCypherQuery } from '@robosystems/client'
-
-// Configure the client
-client.setConfig({
-  baseUrl: 'https://api.robosystems.ai',
-  credentials: 'include',
-})
-
-// Use with cookie-based authentication (browser)
-const { data: user, error } = await getCurrentUser()
-if (user) {
-  console.log('Logged in as:', user.email)
-}
-
-// List companies in a graph
-const { data: companies } = await listCompanies({
-  path: { graph_id: 'your-graph-id' },
-  query: { limit: 10 },
-})
-
-// Execute a Cypher query
-const { data: result } = await executeCypherQuery({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    query: 'MATCH (c:Company)-[:HAS_FILING]->(f:Filing) RETURN c.name, f.form_type LIMIT 5',
-  },
-})
-```
-
-### Server Usage (with API key)
-
-```typescript
-import { client, getUserGraphs, listCompanies } from '@robosystems/client'
-
-// Configure with API key for server-side usage
-client.setConfig({
-  baseUrl: 'https://api.robosystems.ai',
-  headers: {
-    'X-API-Key': process.env.ROBOSYSTEMS_API_KEY!,
-  },
-})
-
-// Fetch user's graphs
-const { data: graphs, error } = await getUserGraphs()
-
-// Work with financial data
-if (graphs?.graphs.length) {
-  const graphId = graphs.graphs[0].graph_id
-  const { data: companies } = await listCompanies({
-    path: { graph_id: graphId },
-  })
-}
-```
-
-## Key API Endpoints
-
-### Authentication & User Management
-
-```typescript
-import {
-  registerUser,
-  loginUser,
-  logoutUser,
-  getCurrentUser,
-  createUserApiKey,
-} from '@robosystems/client'
-
-// Register a new user
-const { data, error } = await registerUser({
-  body: {
-    email: 'user@example.com',
-    password: 'secure-password',
-    name: 'John Doe',
-  },
-})
-
-// Sign in
-const { data: session } = await loginUser({
-  body: {
-    username: 'user@example.com',
-    password: 'secure-password',
-  },
-})
-
-// Get current user
-const { data: user } = await getCurrentUser()
-
-// Create API key for programmatic access
-const { data: apiKey } = await createUserApiKey({
-  body: {
-    key_name: 'Production Server',
-    key_type: 'user',
-  },
-})
-console.log('Save this key securely:', apiKey.key)
-
-// Sign out
-await logoutUser()
-```
-
-### Company & Financial Data
-
-```typescript
-import {
-  listCompanies,
-  getCompany,
-  createCompany,
-  createConnection,
-  syncConnection,
-} from '@robosystems/client'
-
-// List companies with pagination
-const { data: companies } = await listCompanies({
-  path: { graph_id: 'your-graph-id' },
-  query: { limit: 20, offset: 0 },
-})
-console.log(`Found ${companies.total} companies`)
-
-// Get specific company details
-const { data: company } = await getCompany({
-  path: {
-    graph_id: 'your-graph-id',
-    company_id: 'AAPL',
-  },
-})
-
-// Create new company
-const { data: newCompany } = await createCompany({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    identifier: 'MSFT',
-    name: 'Microsoft Corporation',
-    metadata: { industry: 'Technology' },
-  },
-})
-
-// Create data connection (QuickBooks, etc.)
-const { data: connection } = await createConnection({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    name: 'QuickBooks Integration',
-    connection_type: 'quickbooks',
-    config: { company_id: '123456' },
-  },
-})
-
-// Sync data from connection
-const { data: syncResult } = await syncConnection({
-  path: {
-    graph_id: 'your-graph-id',
-    connection_id: connection.id,
-  },
-})
-```
-
-### Graph Queries & Analytics
-
-```typescript
-import {
-  executeCypherQuery,
-  executeReadOnlyCypherQuery,
-  getGraphMetrics,
-} from '@robosystems/client'
-
-// Execute parameterized Cypher queries
-const { data: results } = await executeCypherQuery({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    query: `
-      MATCH (c:Company {ticker: $ticker})-[:HAS_METRIC]->(m:Metric)
-      WHERE m.fiscal_year >= $start_year
-      RETURN m.name, m.value, m.fiscal_year
-      ORDER BY m.fiscal_year DESC
-    `,
-    parameters: { ticker: 'AAPL', start_year: 2020 },
-  },
-})
-
-// Read-only queries for better performance
-const { data: readOnlyResult } = await executeReadOnlyCypherQuery({
-  path: { graph_id: 'your-graph-id' },
-  body: { query: 'MATCH (n) RETURN count(n) as total' },
-})
-
-// Get graph analytics
-const { data: metrics } = await getGraphMetrics({
-  path: { graph_id: 'your-graph-id' },
-})
-console.log(`Total nodes: ${metrics.total_nodes}`)
-console.log(`Total relationships: ${metrics.total_relationships}`)
-```
-
-### Financial AI Agent
-
-```typescript
-import { queryFinancialAgent } from '@robosystems/client'
-
-// Natural language financial queries
-const { data: agentResponse } = await queryFinancialAgent({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    query: "What was Apple's revenue growth over the last 3 years?",
-    include_reasoning: true,
-    max_tokens: 1000,
-  },
-})
-
-console.log('Answer:', agentResponse.answer)
-if (agentResponse.reasoning) {
-  console.log('Reasoning:', agentResponse.reasoning)
-}
-```
-
-## Advanced Features
-
-### Billing & Credit Management
-
-```typescript
-import { getCreditSummary, checkCreditBalance, getCurrentGraphBill } from '@robosystems/client'
-
-// Monitor credits and usage for a specific graph
-const { data: creditSummary } = await getCreditSummary({
-  path: { graph_id: 'your-graph-id' },
-})
-console.log(`Available credits: ${creditSummary.available_credits.toLocaleString()}`)
-console.log(
-  `Monthly usage: ${creditSummary.used_credits.toLocaleString()}/${creditSummary.total_credits.toLocaleString()}`
-)
-
-// Check credit requirements before operations
-const { data: creditCheck } = await checkCreditBalance({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    operation_type: 'query',
-    estimated_credits: 100,
-  },
-})
-
-if (creditCheck.has_sufficient_credits) {
-  // Proceed with operation
-}
-
-// Get billing information
-const { data: currentBill } = await getCurrentGraphBill({
-  path: { graph_id: 'your-graph-id' },
-})
-```
-
-### MCP Tools Integration
-
-```typescript
-import { listMcpTools, callMcpTool } from '@robosystems/client'
-
-// List available MCP tools
-const { data: tools } = await listMcpTools({
-  path: { graph_id: 'your-graph-id' },
-})
-tools.tools.forEach((tool) => {
-  console.log(`${tool.name}: ${tool.description}`)
-})
-
-// Call an MCP tool
-const { data: toolResult } = await callMcpTool({
-  path: { graph_id: 'your-graph-id' },
-  body: {
-    name: 'analyze_financial_statement',
-    arguments: {
-      company_id: 'AAPL',
-      statement_type: 'income',
-      fiscal_year: 2023,
-    },
-  },
-})
-console.log('Analysis result:', toolResult.content)
-```
-
-## Advanced Features
-
-### Error Handling
-
-```typescript
-import { listCompanies } from '@robosystems/client'
-import type { ErrorResponse } from '@robosystems/client'
-
-try {
-  const { data, error } = await listCompanies({
-    path: { graph_id: 'your-graph-id' },
-  })
-
-  if (error) {
-    const apiError = error as ErrorResponse
-
-    switch (apiError.status) {
-      case 400:
-        console.error('Validation error:', apiError.detail)
-        break
-      case 401:
-        console.error('Authentication failed - check your API key')
-        break
-      case 403:
-        console.error('Permission denied - check graph access')
-        break
-      case 429:
-        console.error('Rate limit exceeded - retry later')
-        break
-      case 503:
-        console.error('Service temporarily unavailable')
-        break
-      default:
-        console.error('API Error:', apiError.detail || apiError.message)
-    }
-  } else if (data) {
-    console.log(`Found ${data.total} companies`)
-  }
-} catch (err) {
-  // Network errors
-  console.error('Network Error:', err)
-}
-```
-
-### TypeScript Types
-
-All API responses and requests are fully typed:
-
-```typescript
-import type {
-  User,
-  Graph,
-  Company,
-  CompanyCreate,
-  CypherQueryRequest,
-  CypherQueryResponse,
-  AgentQueryRequest,
-  AgentQueryResponse,
-  ErrorResponse,
-  PaginatedResponse,
-} from '@robosystems/client'
-
-// Type-safe function example
-function processCompany(company: Company): void {
-  console.log(`Company: ${company.name} (${company.identifier})`)
-  if (company.metadata) {
-    console.log('Industry:', company.metadata.industry)
-  }
-}
-
-// Type-safe query builder
-function buildMetricQuery(ticker: string, startYear: number): CypherQueryRequest {
-  return {
-    query: `
-      MATCH (c:Company {ticker: $ticker})-[:HAS_METRIC]->(m:Metric)
-      WHERE m.fiscal_year >= $start_year
-      RETURN m
-    `,
-    parameters: { ticker, start_year: startYear },
-  }
-}
-```
-
-## Environment Configuration
-
-### Next.js App Router
-
-```typescript
-// app/api/robosystems/route.ts
-import { client } from '@robosystems/client'
-
-// Configure for server-side API routes
-client.setConfig({
-  baseUrl: process.env.ROBOSYSTEMS_API_URL || 'https://api.robosystems.ai',
-  headers: {
-    'X-API-Key': process.env.ROBOSYSTEMS_API_KEY!,
-  },
-})
-```
-
-### React SPA
-
-```typescript
-// src/lib/robosystems.ts
-import { client } from '@robosystems/client'
-
-// Configure for browser with cookies
-client.setConfig({
-  baseUrl: import.meta.env.VITE_ROBOSYSTEMS_API_URL || 'https://api.robosystems.ai',
-  credentials: 'include',
-})
-```
-
-### Node.js Script
-
-```typescript
-// scripts/analyze.ts
-import { client } from '@robosystems/client'
-import dotenv from 'dotenv'
-
-dotenv.config()
-
-client.setConfig({
-  baseUrl: process.env.ROBOSYSTEMS_API_URL || 'https://api.robosystems.ai',
-  headers: {
-    'X-API-Key': process.env.ROBOSYSTEMS_API_KEY!,
-  },
-})
 ```
 
 ## API Reference
 
-- Full API documentation: [https://api.robosystems.ai](https://api.robosystems.ai)
+- API reference: [https://api.robosystems.ai](https://api.robosystems.ai)
+- API documentation: [https://api.robosystems.ai/docs](https://api.robosystems.ai/docs)
 - OpenAPI specification: [https://api.robosystems.ai/openapi.json](https://api.robosystems.ai/openapi.json)
 
 ## Support
 
-- Issues: [GitHub Issues](https://github.com/RoboFinSystems/robosystems-typescript-client/issues)
+- Issues: [Issues](https://github.com/RoboFinSystems/robosystems-typescript-client/issues)
+- Discussions: [Discussions](https://github.com/RoboFinSystems/robosystems-typescript-client/discussions)
+- Projects: [Projects](https://github.com/RoboFinSystems/robosystems-typescript-client/projects)
+- Wiki: [Wiki](https://github.com/RoboFinSystems/robosystems-typescript-client/wiki)
 
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-MIT © 2025 Harbinger FinLab
+MIT © 2025 RFS LLC

package/bin/create-feature

@@ -39,16 +39,9 @@ echo ""
 
 # Check for uncommitted changes
 if ! git diff --quiet || ! git diff --cached --quiet; then
-  echo "⚠️  You have uncommitted changes."
-  read -p "Do you want to stash them? (y/N): " -n 1 -r
-  echo
-  if [[ $REPLY =~ ^[Yy]$ ]]; then
-    git stash push -m "Auto-stash before creating branch $FULL_BRANCH"
-    echo "✅ Changes stashed"
-  else
-    echo "❌ Please commit or stash your changes first"
-    exit 1
-  fi
+  echo "⚠️  You have uncommitted changes. Auto-stashing..."
+  git stash push -m "Auto-stash before creating branch $FULL_BRANCH"
+  echo "✅ Changes stashed"
 fi
 
 # Fetch latest changes from remote
@@ -92,13 +85,10 @@ echo "  2. Push your changes: git push"
 echo "  3. Create a PR: gh pr create --base $BASE_BRANCH --title \"Your PR title\" --body \"Your PR description\""
 echo "     or use: npm run pr:create"
 
-# Check if we had stashed changes
+# Check if we had stashed changes and auto-apply them
 if git stash list | grep -q "Auto-stash before creating branch $FULL_BRANCH"; then
   echo ""
-  read -p "Do you want to apply your stashed changes? (y/N): " -n 1 -r
-  echo
-  if [[ $REPLY =~ ^[Yy]$ ]]; then
-    git stash pop
-    echo "✅ Stashed changes applied"
-  fi
+  echo "Auto-applying stashed changes..."
+  git stash pop
+  echo "✅ Stashed changes applied"
 fi

package/extensions/CopyClient.d.ts

@@ -34,6 +34,7 @@ export declare class CopyClient {
         baseUrl: string;
         credentials?: 'include' | 'same-origin' | 'omit';
         headers?: Record<string, string>;
+        token?: string;
     });
     /**
      * Copy data from S3 to graph database

package/extensions/CopyClient.js

@@ -39,6 +39,9 @@ class CopyClient {
             url: '/v1/{graph_id}/copy',
             path: { graph_id: graphId },
             body: request,
+            query: {
+                token: this.config.token, // Pass JWT token for SSE authentication
+            },
         };
         try {
             // Execute the copy request

package/extensions/CopyClient.ts

@@ -53,12 +53,14 @@ export class CopyClient {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
   }
 
   constructor(config: {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
   }) {
     this.config = config
   }
@@ -111,6 +113,9 @@ export class CopyClient {
       url: '/v1/{graph_id}/copy' as const,
       path: { graph_id: graphId },
       body: request,
+      query: {
+        token: this.config.token, // Pass JWT token for SSE authentication
+      },
     }
 
     try {

package/extensions/OperationClient.d.ts

@@ -24,6 +24,7 @@ export declare class OperationClient {
         baseUrl: string;
         credentials?: 'include' | 'same-origin' | 'omit';
         headers?: Record<string, string>;
+        token?: string;
         maxRetries?: number;
         retryDelay?: number;
     });

package/extensions/OperationClient.ts

@@ -34,6 +34,7 @@ export class OperationClient {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
     maxRetries?: number
     retryDelay?: number
   }
@@ -44,6 +45,7 @@ export class OperationClient {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
     maxRetries?: number
     retryDelay?: number
   }) {

package/extensions/QueryClient.d.ts

@@ -33,6 +33,7 @@ export declare class QueryClient {
         baseUrl: string;
         credentials?: 'include' | 'same-origin' | 'omit';
         headers?: Record<string, string>;
+        token?: string;
     });
     executeQuery(graphId: string, request: QueryRequest, options?: QueryOptions): Promise<QueryResult | AsyncIterableIterator<any>>;
     private streamQueryResults;

package/extensions/QueryClient.js

@@ -23,6 +23,7 @@ class QueryClient {
             query: {
                 mode: options.mode,
                 test_mode: options.testMode,
+                token: this.config.token, // Pass JWT token for SSE authentication
             },
         };
         // Execute the query

package/extensions/QueryClient.ts

@@ -47,12 +47,14 @@ export class QueryClient {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
   }
 
   constructor(config: {
     baseUrl: string
     credentials?: 'include' | 'same-origin' | 'omit'
     headers?: Record<string, string>
+    token?: string // JWT token for authentication
   }) {
     this.config = config
   }
@@ -72,6 +74,7 @@ export class QueryClient {
       query: {
         mode: options.mode,
         test_mode: options.testMode,
+        token: this.config.token, // Pass JWT token for SSE authentication
       },
     }
 

package/extensions/SSEClient.d.ts

@@ -1,11 +1,25 @@
 /**
  * Core SSE (Server-Sent Events) client for RoboSystems API
  * Provides automatic reconnection, event replay, and type-safe event handling
+ *
+ * SECURITY NOTE: When using JWT authentication, tokens are passed as query parameters
+ * due to EventSource API limitations. This means tokens may appear in:
+ * - Server access logs
+ * - Proxy logs
+ * - Browser history
+ * - Referer headers
+ *
+ * For production environments with sensitive data, consider:
+ * - Using cookie-based authentication instead
+ * - Implementing a WebSocket-based alternative
+ * - Using short-lived tokens that expire quickly
+ * - Ensuring all connections use HTTPS
  */
 export interface SSEConfig {
     baseUrl: string;
     credentials?: 'include' | 'same-origin' | 'omit';
     headers?: Record<string, string>;
+    token?: string;
     maxRetries?: number;
     retryDelay?: number;
     heartbeatInterval?: number;

package/extensions/SSEClient.js

@@ -28,7 +28,13 @@ class SSEClient {
     }
     async connect(operationId, fromSequence = 0) {
         return new Promise((resolve, reject) => {
-            const url = `${this.config.baseUrl}/v1/operations/${operationId}/stream?from_sequence=${fromSequence}`;
+            let url = `${this.config.baseUrl}/v1/operations/${operationId}/stream?from_sequence=${fromSequence}`;
+            // Add JWT token as query parameter if provided
+            // WARNING: EventSource API doesn't support custom headers, so tokens are passed via query param
+            // This has security implications - see class documentation
+            if (this.config.token) {
+                url += `&token=${encodeURIComponent(this.config.token)}`;
+            }
             this.eventSource = new EventSource(url, {
                 withCredentials: this.config.credentials === 'include',
             });