# Official SDKs

Veritas provides official SDKs for JavaScript/TypeScript and Python.

## JavaScript/TypeScript SDK

### Installation

```bash
npm install @veritas/b2b-sdk
# or
yarn add @veritas/b2b-sdk
# or
pnpm add @veritas/b2b-sdk
```

### Quick Start

```typescript
import { VeritasClient } from '@veritas/b2b-sdk';

const client = new VeritasClient({
  apiKey: 'sk_live_your_api_key',
});

// List articles
const { items, nextCursor } = await client.feed.list({ limit: 10 });

// Search articles
const results = await client.search.query({ q: 'climate change' });

// Iterate through all articles
for await (const article of client.feed.iterate({ category: 'politics' })) {
  console.log(article.headline);
}
```

### Configuration

```typescript
const client = new VeritasClient({
  apiKey: 'sk_live_your_api_key', // Required
  baseUrl: 'https://api.veritas.news', // Default
  timeout: 30000, // 30 seconds (default)
  retry: true, // Enable automatic retries (default)
  maxRetries: 3, // Maximum retry attempts (default)
  sandbox: false, // Force sandbox mode (auto-detected from key)
  headers: {}, // Custom headers
  fetch: fetch, // Custom fetch implementation
});
```

### Resources

| Resource          | Description             |
| ----------------- | ----------------------- |
| `client.feed`     | News Feed API           |
| `client.search`   | Search API              |
| `client.claims`   | Fact-Check API          |
| `client.entities` | Entity API              |
| `client.media`    | Media API               |
| `client.alerts`   | Monitoring & Alerts API |
| `client.sandbox`  | Sandbox management      |

### Feed API

```typescript
// List articles
const response = await client.feed.list({
  limit: 20,
  category: 'politics',
  topic: 'elections',
  lang: 'en',
  from: '2024-01-01',
  to: '2024-12-31',
});

// Get single article
const { article } = await client.feed.get('article-uuid');

// Get trending
const { items } = await client.feed.trending({ hours: 24, limit: 10 });

// Auto-pagination iterator
for await (const article of client.feed.iterate({ category: 'sports' })) {
  console.log(article.headline);
}

// Collect all articles (with limit)
const allArticles = await client.feed.all({ category: 'tech' }, 500);
```

### Search API

```typescript
// Search with filters
const results = await client.search.query({
  q: 'climate change',
  page: 1,
  pageSize: 20,
  category: ['science', 'politics'],
  bias: ['center', 'center-left'],
  sortBy: 'relevance',
});

// Access aggregations
console.log(results.aggregations.categories);
console.log(results.aggregations.biasDistribution);

// Autocomplete suggestions
const { suggestions } = await client.search.suggest({ q: 'presi', limit: 5 });

// Iterate through all search results
for await (const article of client.search.iterate({ q: 'election' })) {
  console.log(article.headline);
}
```

### Claims API

```typescript
// List claims
const claims = await client.claims.list({ verdict: 'false', limit: 10 });

// Get claim detail
const { claim } = await client.claims.get('claim-uuid');

// Search claims
const results = await client.claims.search({ q: 'vaccine safety' });

// Quick verify a statement
const claim = await client.claims.verify('The earth is flat');
if (claim) {
  console.log(`Verdict: ${claim.verdict}`);
  console.log(`Evidence: ${claim.evidenceSummary}`);
}
```

### Entities API

```typescript
// Search entities
const { entities, total } = await client.entities.search({
  q: 'Elon Musk',
  type: 'person',
});

// Get entity with relationships
const { entity, relationships } =
  await client.entities.getWithRelationships('entity-uuid');

// Create entity
const { entity: newEntity } = await client.entities.create({
  name: 'New Organization',
  type: 'organization',
  description: 'Description...',
});

// Find or create
const { entity, created } = await client.entities.findOrCreate({
  name: 'John Doe',
  type: 'person',
});

// Get articles mentioning entity
const articles = await client.entities.articles('entity-uuid', { limit: 20 });

// Create relationship
await client.entities.createRelationship({
  sourceEntityId: 'person-uuid',
  targetEntityId: 'org-uuid',
  relationType: 'works_for',
  confidence: 0.95,
});
```

### Media API

```typescript
// List media
const media = await client.media.list({
  kind: 'image',
  role: 'featured_image',
});

// Get media for article
const { items } = await client.media.forArticle('article-uuid');

// Search media
const results = await client.media.search({ q: 'parliament', kind: 'video' });

// Get best variant for responsive display
const url = client.media.getBestVariant(mediaAsset, 800);

// Convenience methods
const images = await client.media.images({ limit: 10 });
const videos = await client.media.videos({ limit: 10 });
```

### Alerts API

```typescript
// Create keyword alert
const { subscription } = await client.alerts.createKeywordAlert(
  'Election Alert',
  ['election', 'voting', 'ballot'],
  {
    categories: ['politics'],
    webhookUrl: 'https://your-server.com/webhook',
    frequency: 'instant',
  }
);

// Create entity alert
await client.alerts.createEntityAlert('Track CEO', ['entity-uuid'], {
  email: 'alerts@example.com',
});

// Create breaking news alert
await client.alerts.createBreakingNewsAlert('Breaking Politics', {
  categories: ['politics'],
});

// List subscriptions
const subs = await client.alerts.list({ isActive: true });

// Update subscription
await client.alerts.update(subscriptionId, { frequency: 'daily' });

// Enable/disable
await client.alerts.enable(subscriptionId);
await client.alerts.disable(subscriptionId);

// Get notifications
const notifications = await client.alerts.notifications({ delivered: false });

// Get monitoring stats
const stats = await client.alerts.stats();
```

### Sandbox API

```typescript
// Get status
const status = await client.sandbox.status();

// Configure
await client.sandbox.configure({
  seed: 'my-test-seed',
  simulatedLatencyMs: 500,
  errorRate: 0.1,
});

// Reset
await client.sandbox.reset({ preserveConfig: true });

// Force error
await client.sandbox.forceError(503);

// Convenience methods
await client.sandbox.setSeed('new-seed');
await client.sandbox.setLatency(1000);
await client.sandbox.setErrorRate(0.05);
```

### Error Handling

```typescript
import {
  VeritasError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  ServerError,
  TimeoutError,
  NetworkError,
} from '@veritas/b2b-sdk';

try {
  await client.feed.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle auth error
  } else if (error instanceof NotFoundError) {
    // Handle not found
  } else if (error instanceof RateLimitError) {
    // error.retryAfter - seconds to wait
    // error.resetAt - when limit resets
  } else if (error instanceof ValidationError) {
    // error.details - validation error details
  } else if (error instanceof ServerError) {
    // Retry with backoff
  } else if (error instanceof TimeoutError) {
    // error.timeoutSeconds
  } else if (error instanceof NetworkError) {
    // Check connectivity
  } else if (error instanceof VeritasError) {
    // Generic API error
    // error.code, error.message, error.status
  }
}
```

### TypeScript Types

```typescript
import type {
  Article,
  Entity,
  Claim,
  MediaAsset,
  AlertSubscription,
  SearchResponse,
  PaginatedResponse,
  EntityType,
  ClaimVerdict,
} from '@veritas/b2b-sdk';

// Use types for type safety
function processArticle(article: Article): void {
  const headline: string = article.headline;
  const entities: EntityMention[] = article.entities;
}
```

---

## Python SDK

### Installation

```bash
pip install veritas-sdk
```

### Quick Start

```python
import asyncio
from veritas_sdk import VeritasClient

async def main():
    async with VeritasClient(api_key="sk_live_your_api_key") as client:
        # List articles
        response = await client.feed.list(limit=10)
        for article in response["items"]:
            print(article["headline"])

        # Search articles
        results = await client.search.query(q="climate change")
        print(f"Found {results['total']} articles")

asyncio.run(main())
```

### Synchronous Client

```python
from veritas_sdk import SyncVeritasClient

with SyncVeritasClient(api_key="sk_live_your_api_key") as client:
    response = client.feed.list(limit=10)
    for article in response["items"]:
        print(article["headline"])
```

### Configuration

```python
client = VeritasClient(
    api_key="sk_live_your_api_key",  # Required
    base_url="https://api.veritas.news",  # Default
    timeout=30.0,    # 30 seconds (default)
    retry=True,      # Enable automatic retries (default)
    max_retries=3,   # Maximum retry attempts (default)
    sandbox=False,   # Force sandbox mode (auto-detected from key)
    headers={},      # Custom headers
)
```

### Feed API

```python
# List articles
response = await client.feed.list(
    limit=20,
    category="politics",
    topic="elections",
    lang="en",
    from_date="2024-01-01",
    to_date="2024-12-31",
)

# Get single article
result = await client.feed.get("article-uuid")
article = result["article"]

# Get trending
trending = await client.feed.trending(hours=24, limit=10)

# Auto-pagination iterator
async for article in client.feed.iterate(category="sports"):
    print(article["headline"])

# Collect all articles (with limit)
all_articles = await client.feed.all(category="tech", max_items=500)
```

### Search API

```python
# Search with filters
results = await client.search.query(
    q="climate change",
    page=1,
    page_size=20,
    category=["science", "politics"],
    bias=["center", "center-left"],
    sort_by="relevance",
)

# Access aggregations
print(results["aggregations"]["categories"])

# Autocomplete suggestions
suggestions = await client.search.suggest(q="presi", limit=5)

# Iterate through all search results
async for article in client.search.iterate(q="election"):
    print(article["headline"])
```

### Claims API

```python
# List claims
claims = await client.claims.list(verdict="false", limit=10)

# Get claim detail
result = await client.claims.get("claim-uuid")
claim = result["claim"]

# Search claims
results = await client.claims.search(q="vaccine safety")

# Quick verify a statement
claim = await client.claims.verify("The earth is flat")
if claim:
    print(f"Verdict: {claim['verdict']}")
    print(f"Evidence: {claim['evidenceSummary']}")
```

### Entities API

```python
# Search entities
result = await client.entities.search(q="Elon Musk", type="person")
entities = result["entities"]

# Get entity with relationships
data = await client.entities.get_with_relationships("entity-uuid")
entity = data["entity"]
relationships = data["relationships"]

# Create entity
result = await client.entities.create(
    name="New Organization",
    type="organization",
    description="Description...",
)

# Find or create
entity, created = await client.entities.find_or_create(
    name="John Doe",
    type="person",
)

# Get articles mentioning entity
articles = await client.entities.articles("entity-uuid", limit=20)

# Create relationship
await client.entities.create_relationship(
    source_entity_id="person-uuid",
    target_entity_id="org-uuid",
    relation_type="works_for",
    confidence=0.95,
)
```

### Media API

```python
# List media
media = await client.media.list(kind="image", role="featured_image")

# Get media for article
result = await client.media.for_article("article-uuid")
items = result["items"]

# Search media
results = await client.media.search(q="parliament", kind="video")

# Get best variant for responsive display
url = client.media.get_best_variant(media_asset, target_width=800)

# Convenience methods
images = await client.media.images(limit=10)
videos = await client.media.videos(limit=10)
```

### Alerts API

```python
# Create keyword alert
result = await client.alerts.create_keyword_alert(
    name="Election Alert",
    keywords=["election", "voting", "ballot"],
    categories=["politics"],
    webhook_url="https://your-server.com/webhook",
    frequency="instant",
)

# Create entity alert
await client.alerts.create_entity_alert(
    name="Track CEO",
    entity_ids=["entity-uuid"],
    email="alerts@example.com",
)

# Create breaking news alert
await client.alerts.create_breaking_news_alert(
    name="Breaking Politics",
    categories=["politics"],
)

# List subscriptions
subs = await client.alerts.list(is_active=True)

# Update subscription
await client.alerts.update(subscription_id, frequency="daily")

# Enable/disable
await client.alerts.enable(subscription_id)
await client.alerts.disable(subscription_id)

# Get notifications
notifications = await client.alerts.notifications(delivered=False)

# Get monitoring stats
stats = await client.alerts.stats()
```

### Sandbox API

```python
# Get status
status = await client.sandbox.status()

# Configure
await client.sandbox.configure(
    seed="my-test-seed",
    simulated_latency_ms=500,
    error_rate=0.1,
)

# Reset
await client.sandbox.reset(preserve_config=True)

# Force error
await client.sandbox.force_error(503)

# Convenience methods
await client.sandbox.set_seed("new-seed")
await client.sandbox.set_latency(1000)
await client.sandbox.set_error_rate(0.05)
```

### Error Handling

```python
from veritas_sdk import (
    VeritasError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    ServerError,
    TimeoutError,
    NetworkError,
)

try:
    await client.feed.get("invalid-id")
except AuthenticationError as e:
    # Handle auth error
    print(f"Auth failed: {e.message}")
except NotFoundError as e:
    # Handle not found
    print(f"Resource not found: {e.resource_id}")
except RateLimitError as e:
    # e.retry_after - seconds to wait
    # e.reset_at - when limit resets
    await asyncio.sleep(e.retry_after)
except ValidationError as e:
    # e.details - validation error details
    print(f"Validation failed: {e.details}")
except ServerError as e:
    # Retry with backoff
    print(f"Server error: {e.message}")
except TimeoutError as e:
    # e.timeout_seconds
    print(f"Request timed out after {e.timeout_seconds}s")
except NetworkError as e:
    # Check connectivity
    print(f"Network error: {e.message}")
except VeritasError as e:
    # Generic API error
    print(f"API error [{e.code}]: {e.message}")
```

### Type Hints

The Python SDK includes full TypedDict type hints:

```python
from veritas_sdk import (
    Article,
    Entity,
    Claim,
    MediaAsset,
    AlertSubscription,
    SearchResponse,
    PaginatedResponse,
    EntityType,
    ClaimVerdict,
)

def process_article(article: Article) -> None:
    headline: str = article["headline"]
    entities = article["entities"]  # List[EntityMention]
```

---

## Feature Comparison

| Feature             | JavaScript SDK        | Python SDK             |
| ------------------- | --------------------- | ---------------------- |
| Async Support       | Yes                   | Yes                    |
| Sync Support        | No                    | Yes                    |
| Auto Pagination     | Yes (async iterators) | Yes (async generators) |
| Type Safety         | Full TypeScript       | TypedDict hints        |
| Retry Logic         | Yes                   | Yes                    |
| Rate Limit Handling | Yes                   | Yes                    |
| Sandbox Detection   | Yes                   | Yes                    |
| Custom HTTP Client  | Yes (fetch)           | No (httpx built-in)    |

## Requirements

### JavaScript SDK

- Node.js 18+ or modern browser
- ES2020+ support
- Optional: TypeScript 4.7+

### Python SDK

- Python 3.9+
- httpx library (installed automatically)
