@trustgraph/client

TypeScript/JavaScript client library for TrustGraph WebSocket API. This package provides a framework-agnostic client for communicating with TrustGraph services.

Features

• 🌐 WebSocket-based - Real-time communication with TrustGraph services
• 📦 Zero Dependencies - No external runtime dependencies
• 🔐 Authentication Support - Optional API key authentication
• 🔄 Auto-reconnection - Handles connection failures gracefully
• 📝 Full TypeScript Support - Complete type definitions
• 🎯 Framework Agnostic - Works with any JavaScript framework or vanilla JS

Installation

npm install @trustgraph/client

Quick Start

import { createTrustGraphSocket } from "@trustgraph/client";

// Create a socket connection
const socket = createTrustGraphSocket("your-username");

// Query triples from the knowledge graph
const triples = await socket.triplesQuery(
  { v: "http://example.org/subject", e: true },
  { v: "http://example.org/predicate", e: true },
  undefined,
  10, // limit
);

console.log(triples);

With Authentication

const socket = createTrustGraphSocket("your-username", "your-api-key");

Core APIs

Knowledge Graph Operations

Query Triples

const triples = await socket.triplesQuery(
  subject?: Value,    // Optional subject filter
  predicate?: Value,  // Optional predicate filter
  object?: Value,     // Optional object filter
  limit: number,      // Maximum results
  collection?: string // Optional collection name
);

Graph Embeddings Query

const entities = await socket.graphEmbeddingsQuery(
  vectors: number[][],  // Embedding vectors
  limit: number,        // Maximum results
  collection?: string   // Optional collection name
);

Text & LLM Operations

Text Completion

const response = await socket.textCompletion(
  system: string,    // System prompt
  prompt: string,    // User prompt
  temperature?: number
);

Graph RAG

const answer = await socket.graphRag(
  query: string,
  options?: {
    'entity-limit'?: number,
    'triple-limit'?: number,
    'max-subgraph-size'?: number,
    'max-path-length'?: number
  },
  collection?: string
);

Agent

socket.agent(
  question: string,
  think: (thought: string) => void,      // Called when agent is thinking
  observe: (observation: string) => void, // Called on observations
  answer: (answer: string) => void,      // Called with final answer
  error: (error: string) => void,        // Called on errors
  collection?: string
);

Embeddings

const vectors = await socket.embeddings(text: string);

Document Operations

Load Document

await socket.loadDocument(
  id: string,           // Document ID
  data: string,         // Base64-encoded document
  metadata: Triple[],   // Document metadata as triples
  collection?: string
);

Load Text

await socket.loadText(
  id: string,           // Document ID
  text: string,         // Plain text content
  charset: string,      // Character encoding (e.g., 'utf-8')
  metadata: Triple[],   // Document metadata as triples
  collection?: string
);

Library Operations

List Documents

const docs = await socket.library.listDocuments(
  user?: string,
  collection?: string
);

Get Document

const doc = await socket.library.getDocument(
  id: string,
  user?: string,
  collection?: string
);

Delete Document

await socket.library.deleteDocument(
  id: string,
  user?: string,
  collection?: string
);

Flow Operations

Flows represent processing pipelines for documents and queries.

Create Flow API

const flowApi = socket.flow("flow-id");
// flowApi has same methods as socket but scoped to this flow

Start Flow

await socket.flows.startFlow(
  flowId: string,
  className: string,
  description: string
);

Stop Flow

await socket.flows.stopFlow(flowId: string);

List Flows

const flowIds = await socket.flows.getFlows();

Get Flow Definition

const flowDef = await socket.flows.getFlow(flowId: string);

List Flow Classes

const classes = await socket.flows.getFlowClasses();

Get Flow Class

const classDef = await socket.flows.getFlowClass(className: string);

Connection State Monitoring

// Subscribe to connection state changes
const unsubscribe = socket.onConnectionStateChange((state) => {
  console.log("Status:", state.status); // 'connecting' | 'connected' | 'authenticated' | 'disconnected' | 'error'
  console.log("Authenticated:", state.authenticated);
  console.log("Error:", state.error);
});

// Unsubscribe when done
unsubscribe();

Data Types

Value

Represents a subject, predicate, or object in a triple:

interface Value {
  v: string; // Value (URI or literal)
  e: boolean; // Is entity (true) or literal (false)
  label?: string; // Optional human-readable label
}

Triple

Represents a subject-predicate-object relationship:

interface Triple {
  s: Value; // Subject
  p: Value; // Predicate
  o: Value; // Object
}

Advanced Usage

Custom Timeout and Retries

Most methods accept optional timeout and retry parameters:

await socket.triplesQuery(
  subject,
  predicate,
  object,
  limit,
  collection,
  30000, // timeout in ms
  5, // retry attempts
);

Closing the Connection

socket.close();

Error Handling

All async methods return Promises that reject on error:

try {
  const result = await socket.triplesQuery(...);
} catch (error) {
  console.error('Query failed:', error);
}

React Integration

For React applications, use the companion package:

npm install @trustgraph/react-provider

See @trustgraph/react-provider for React-specific hooks and providers.

API Reference

Full API documentation is available in the TypeScript definitions. Your IDE will provide autocomplete and inline documentation for all methods.

License

Apache 2.0

(c) KnowNext Inc., KnowNext Limited 2025