@chittyos/chittycontextual-client

TypeScript client library for ChittyContextul cross-source temporal intelligence platform. Provides type-safe access to all ChittyContextul APIs with built-in error handling, retry logic, and React hooks for TanStack Query.

Installation

npm install @chittyos/chittycontextual-client

For React hooks support:

npm install @chittyos/chittycontextual-client @tanstack/react-query

Quick Start

Basic Usage (Node.js/Browser)

import { ChittyContextualClient } from '@chittyos/chittycontextual-client';

const client = new ChittyContextualClient({
  baseUrl: 'https://api.chittycontextual.com',
  apiKey: 'your-api-key', // Optional
  timeout: 30000, // Default: 30s
  retryAttempts: 3, // Default: 3
});

// Fetch messages
const messages = await client.messages.list({ limit: 50 });

// Search messages
const results = await client.messages.search({
  query: 'contract negotiation',
  timeRange: {
    start: new Date('2025-01-01'),
    end: new Date('2025-01-31'),
  },
});

// Upload documents
const files = [/* File objects */];
const uploadResult = await client.documents.upload(files, (progress) => {
  console.log(`Upload progress: ${progress}%`);
});

React Hooks Usage

import { ChittyContextualClient } from '@chittyos/chittycontextual-client';
import { useMessages, useSearchMessages, useUploadDocuments } from '@chittyos/chittycontextual-client/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const client = new ChittyContextualClient({
  baseUrl: 'http://localhost:5000',
});

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Dashboard />
    </QueryClientProvider>
  );
}

function Dashboard() {
  // Fetch messages with automatic caching and refetching
  const { data: messages, isLoading, error } = useMessages(client, { limit: 100 });

  // Upload documents with progress tracking
  const uploadMutation = useUploadDocuments(client, (progress) => {
    console.log(`Upload: ${progress}%`);
  });

  const handleUpload = (files: File[]) => {
    uploadMutation.mutate(files, {
      onSuccess: (data) => {
        console.log('Upload successful:', data);
      },
    });
  };

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>Messages ({messages?.length})</h1>
      {/* Render messages */}
    </div>
  );
}

API Reference

Client Configuration

interface ClientConfig {
  baseUrl?: string;        // Default: 'http://localhost:5000'
  apiKey?: string;         // Optional API key for authentication
  timeout?: number;        // Request timeout in ms (default: 30000)
  retryAttempts?: number;  // Number of retry attempts (default: 3)
  retryDelay?: number;     // Delay between retries in ms (default: 1000)
}

Messages API

// List messages
client.messages.list({ limit?: number }): Promise<Message[]>

// Search messages with full-text search
client.messages.search({
  query: string;
  timeRange?: { start: Date | string; end: Date | string };
}): Promise<Message[]>

// Get timeline of messages
client.messages.timeline({
  start: Date | string;
  end: Date | string;
}): Promise<Message[]>

Documents API

// Upload documents with progress callback
client.documents.upload(
  files: File[],
  onProgress?: (percent: number, loaded: number, total: number) => void
): Promise<UploadDocumentsResult>

// List all documents
client.documents.list(): Promise<Document[]>

Topics API

// List all topics
client.topics.list(): Promise<Topic[]>

// Get topic analysis
client.topics.analysis(timeRange?: {
  start: Date | string;
  end: Date | string;
}): Promise<TopicAnalysis[]>

// Get topic evolution over time
client.topics.evolution(
  topicId: number,
  timeRange: { start: Date | string; end: Date | string }
): Promise<TopicEvolution[]>

Entities API

// List all entities
client.entities.list(): Promise<Entity[]>

// Get entity extractions
client.entities.extractions(): Promise<EntityExtraction[]>

Cross References API

// List cross references
client.crossReferences.list(): Promise<CrossReference[]>

// Analyze cross references
client.crossReferences.analyze({
  start: Date | string;
  end: Date | string;
}): Promise<CrossReferenceResult>

Analytics API

// Get source correlations
client.analytics.correlations(): Promise<SourceCorrelation[]>

// Get processing stats
client.analytics.stats(): Promise<ProcessingStats>

Analysis API

// Bulk analysis
client.analyze.bulk({
  start: Date | string;
  end: Date | string;
}): Promise<BulkAnalysisResult>

// Comprehensive analysis
client.analyze.comprehensive({
  start: Date | string;
  end: Date | string;
  focusTopics?: string[];
  focusParties?: string[];
}): Promise<ComprehensiveAnalysisResult>

Search API

// Intelligent search
client.search.intelligent({
  q: string;
  party?: string;
  source?: MessageSource;
  start?: Date | string;
  end?: Date | string;
}): Promise<IntelligentSearchResult[]>

Party Learning API

// Learn party communication patterns
client.parties.learn({
  partyIdentifier: string;
  timeframe?: string;
}): Promise<PartyLearningResult>

React Hooks

All hooks accept the client instance as the first parameter and optional query/mutation options.

Query Hooks

• useMessages(client, options?, queryOptions?)
• useSearchMessages(client, params, queryOptions?)
• useTimeline(client, params, queryOptions?)
• useDocuments(client, queryOptions?)
• useTopics(client, queryOptions?)
• useTopicAnalysis(client, timeRange?, queryOptions?)
• useTopicEvolution(client, topicId, timeRange, queryOptions?)
• useEntities(client, queryOptions?)
• useEntityExtractions(client, queryOptions?)
• useCrossReferences(client, queryOptions?)
• useAnalyticsCorrelations(client, queryOptions?)
• useAnalyticsStats(client, queryOptions?)
• useIntelligentSearch(client, params, queryOptions?)

Mutation Hooks

• useUploadDocuments(client, onProgress?, mutationOptions?)
• useAnalyzeCrossReferences(client, mutationOptions?)
• useBulkAnalysis(client, mutationOptions?)
• useComprehensiveAnalysis(client, mutationOptions?)
• usePartyLearning(client, mutationOptions?)

Error Handling

The client provides structured error types:

import {
  ChittyContextualError,
  NetworkError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  TimeoutError,
} from '@chittyos/chittycontextual-client';

try {
  await client.messages.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed');
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  Message,
  Document,
  Topic,
  Entity,
  CrossReference,
  MessageSource,
  ProcessingStatus,
  EntityType,
  // ... and many more
} from '@chittyos/chittycontextual-client';

Advanced Usage

Custom Timeout per Request

const client = new ChittyContextualClient({
  baseUrl: 'http://localhost:5000',
  timeout: 60000, // 60 seconds for long-running operations
});

Progress Tracking for Uploads

const uploadMutation = useUploadDocuments(
  client,
  (progress, loaded, total) => {
    console.log(`Uploaded ${loaded} of ${total} bytes (${progress.toFixed(1)}%)`);
  }
);

Query Invalidation

import { queryKeys } from '@chittyos/chittycontextual-client/react';
import { useQueryClient } from '@tanstack/react-query';

const queryClient = useQueryClient();

// Invalidate messages cache after an operation
queryClient.invalidateQueries({ queryKey: queryKeys.messages.all });

License

MIT

Support

For issues and questions, please visit:

• GitHub: https://github.com/chittycorp/chittycontextual
• Documentation: https://docs.chittycontextual.com