Package Exports

@robosystems/client
@robosystems/client/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@robosystems/client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

RoboSystems TypeScript Client

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.

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
Comprehensive error handling with typed errors

Installation

npm install @robosystems/client
# or
yarn add @robosystems/client
# or
pnpm add @robosystems/client

Quick Start

Browser Usage (with cookies)

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)

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

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

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

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

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

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

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

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:

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

// 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

// 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

// 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/docs
OpenAPI specification: https://api.robosystems.ai/openapi.json

Support

Documentation: https://docs.robosystems.ai
Issues: GitHub Issues
Email: support@robosystems.ai

License

This project is licensed under the MIT License - see the LICENSE file for details.