@chittyos/chittycontextual-client/README.md

TypeScript client for ChittyContextul cross-source temporal intelligence platform

# @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

```bash
npm install @chittyos/chittycontextual-client
```

For React hooks support:
```bash
npm install @chittyos/chittycontextual-client @tanstack/react-query
```

## Quick Start

### Basic Usage (Node.js/Browser)

```typescript
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

```tsx
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

```typescript
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

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

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

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

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

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

### Cross References API

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

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

### Analytics API

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

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

### Analysis API

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

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

### Party Learning API

```typescript
// 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:

```typescript
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:

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

## Advanced Usage

### Custom Timeout per Request

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

### Progress Tracking for Uploads

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

### Query Invalidation

```typescript
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