# Yaa External API Integrations

This document provides a comprehensive mapping of all external API integrations
used in the Yaa codebase, including authentication methods, endpoints, and
configuration requirements.

---

## Table of Contents

1. [Overview](#overview)
2. [AI/ML Services](#aiml-services)
3. [Video/Media Services](#videomedia-services)
4. [Social Media APIs](#social-media-apis)
5. [Data/Content APIs](#datacontent-apis)
6. [Fact-Checking APIs](#fact-checking-apis)
7. [Search Infrastructure](#search-infrastructure)
8. [Web Search APIs](#web-search-apis)
9. [Storage Services](#storage-services)
10. [Authentication & Push Notifications](#authentication--push-notifications)
11. [Monitoring & Observability](#monitoring--observability)
12. [Email Services](#email-services)
13. [Environment Variable Reference](#environment-variable-reference)
14. [Integration Patterns](#integration-patterns)

---

## Overview

The Yaa codebase integrates with 25+ external services across multiple
categories:

| Category       | Service Count | Primary Purpose                |
| -------------- | ------------- | ------------------------------ |
| AI/ML Services | 3             | Content generation, embeddings |
| Video/Media    | 4             | Video synthesis, TTS           |
| Social Media   | 8             | Distribution, publishing       |
| Data APIs      | 3             | Market data, events            |
| Fact-Checking  | 2             | Claim verification             |
| Search/Storage | 3             | Indexing, media storage        |
| Web Search     | 2             | Evidence retrieval             |
| Authentication | 5+            | User auth, push notifications  |
| Monitoring     | 2             | Error tracking, tracing        |

---

## AI/ML Services

### Anthropic Claude API

**Location:** `packages/ai/agents/core/llm-client.ts`

**Purpose:** Content analysis, headline generation, agent orchestration

| Configuration | Environment Variable | Default                     |
| ------------- | -------------------- | --------------------------- |
| API Key       | `ANTHROPIC_API_KEY`  | Required                    |
| Model         | Configurable         | `claude-3-5-haiku-20241022` |

**Authentication:** Bearer token in Authorization header

**Use Cases:**

- YouTube metadata optimization
- AI-powered headline generation
- Content summarization
- Agent task orchestration

**Error Handling:**

- HTTP error class with retry mechanisms
- Exponential backoff for rate limits

---

### OpenAI API

**Location:** `packages/nlp/embedding-service/src/openai.ts`

**Purpose:** Text embeddings for semantic similarity

| Configuration | Environment Variable     | Default                  |
| ------------- | ------------------------ | ------------------------ |
| API Key       | `OPENAI_API_KEY`         | Required                 |
| Base URL      | `OPENAI_BASE_URL`        | `https://api.openai.com` |
| Model         | `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` |

**Endpoint:** `POST /v1/embeddings`

**Authentication:** Bearer token in Authorization header

**Request Structure:**

```typescript
{
  model: string;
  input: string;
}
```

**Retry Strategy:** Up to 4 attempts with 250ms \* attempt delay

---

### Cohere API

**Location:** `packages/nlp/embedding-service/src/cohere.ts`

**Purpose:** Alternative embedding provider

| Configuration | Environment Variable     | Default                 |
| ------------- | ------------------------ | ----------------------- |
| API Key       | `COHERE_API_KEY`         | Required                |
| Base URL      | `COHERE_BASE_URL`        | `https://api.cohere.ai` |
| Model         | `COHERE_EMBEDDING_MODEL` | `embed-english-v3.0`    |
| Input Type    | `COHERE_INPUT_TYPE`      | `search_document`       |

**Endpoint:** `POST /v1/embed`

**Authentication:** Bearer token in Authorization header

**Request Structure:**

```typescript
{
  model: string;
  texts: string[];
  input_type: 'search_document' | 'search_query';
  embedding_types: ['float'];
}
```

---

## Video/Media Services

### HeyGen API

**Location:** `packages/video/heygen-service/src/client.ts`

**Purpose:** AI avatar video generation

| Configuration | Environment Variable  | Default                  |
| ------------- | --------------------- | ------------------------ |
| API Key       | `HEYGEN_API_KEY`      | Required                 |
| Base URL      | `HEYGEN_BASE_URL`     | `https://api.heygen.com` |
| Auth Header   | `HEYGEN_AUTH_HEADER`  | `X-Api-Key`              |
| Timeout       | `HEYGEN_TIMEOUT_MS`   | `60000`                  |
| Max Attempts  | `HEYGEN_MAX_ATTEMPTS` | `4`                      |

**Endpoints:**

| Method | Path                   | Purpose      |
| ------ | ---------------------- | ------------ |
| POST   | `/v2/video/generate`   | Create video |
| GET    | `/v1/video_status.get` | Check status |
| GET    | `/v2/avatars`          | List avatars |

**Authentication:** Custom header (X-Api-Key)

**Features:**

- Avatar-based video synthesis
- Status polling for async generation
- Multiple avatar endpoint paths for resilience

**Rate Limiting:** HTTP 429 handling with `retry-after` header parsing

---

### Shotstack API

**Location:** `packages/video/video-rendering-service/src/shotstackClient.ts`

**Purpose:** Video rendering and composition

| Configuration | Environment Variable     | Default                    |
| ------------- | ------------------------ | -------------------------- |
| API Key       | `SHOTSTACK_API_KEY`      | Required                   |
| Base URL      | `SHOTSTACK_BASE_URL`     | `https://api.shotstack.io` |
| Render Path   | `SHOTSTACK_RENDER_PATH`  | `/edit/stage/render`       |
| Timeout       | `SHOTSTACK_TIMEOUT_MS`   | `60000`                    |
| Max Attempts  | `SHOTSTACK_MAX_ATTEMPTS` | `4`                        |

**Endpoints:**

| Method | Path                      | Purpose           |
| ------ | ------------------------- | ----------------- |
| POST   | `/edit/stage/render`      | Create render job |
| GET    | `/edit/stage/render/{id}` | Get render status |

**Authentication:** `x-api-key` header

---

### ElevenLabs API

**Location:** `packages/audio/elevenlabs-service/src/client.ts`

**Purpose:** Text-to-speech for English content

| Configuration | Environment Variable      | Default                     |
| ------------- | ------------------------- | --------------------------- |
| API Key       | `ELEVENLABS_API_KEY`      | Required                    |
| Base URL      | `ELEVENLABS_BASE_URL`     | `https://api.elevenlabs.io` |
| Model         | `ELEVENLABS_MODEL_ID`     | `eleven_multilingual_v2`    |
| Timeout       | `ELEVENLABS_TIMEOUT_MS`   | `30000`                     |
| Max Attempts  | `ELEVENLABS_MAX_ATTEMPTS` | `4`                         |

**Endpoints:**

| Method | Path                           | Purpose         |
| ------ | ------------------------------ | --------------- |
| GET    | `/v1/voices`                   | List voices     |
| POST   | `/v1/text-to-speech/{voiceId}` | Generate speech |

**Authentication:** `xi-api-key` header

**Voice Settings:**

```typescript
{
  stability: number; // 0-1
  similarity_boost: number; // 0-1
  style: number; // 0-1
  use_speaker_boost: boolean;
}
```

**Cost:** ~$0.00003 per character

---

### Ghana NLP API

**Location:** `packages/nlp/ghana-nlp/src/hybrid-tts.ts`

**Purpose:** Local language TTS (Ghanaian languages)

**Supported Languages:**

- Twi (tw)
- Ewe (ee)
- Ga (gaa)
- Dagbani (dag)
- Hausa (ha)
- Fante (fat)
- Dagaare (dga)
- Nzema (nzi)

**Cost:** ~$0.000015 per character

**Hybrid TTS Routing:**

| Priority Mode      | Behavior                                              |
| ------------------ | ----------------------------------------------------- |
| `elevenlabs-first` | ElevenLabs for all, fallback to Ghana NLP             |
| `ghana-nlp-first`  | Ghana NLP for local languages, ElevenLabs for English |
| `cost-optimized`   | Cheapest provider per language                        |
| `quality-first`    | Best quality per language                             |

---

## Social Media APIs

### YouTube Data API v3

**Location:** `packages/video/youtube-upload-service/src/uploader.ts`

**Purpose:** Video upload and channel management

| Configuration       | Environment Variable          | Default  |
| ------------------- | ----------------------------- | -------- |
| OAuth Client ID     | `YOUTUBE_OAUTH_CLIENT_ID`     | Required |
| OAuth Client Secret | `YOUTUBE_OAUTH_CLIENT_SECRET` | Required |
| Refresh Token       | `YOUTUBE_REFRESH_TOKEN`       | Required |
| Privacy Status      | `YOUTUBE_PRIVACY_STATUS`      | `public` |
| Category ID         | `YOUTUBE_CATEGORY_ID`         | `25`     |
| Tags                | `YOUTUBE_TAGS`                | Empty    |
| Notify Subscribers  | `YOUTUBE_NOTIFY_SUBSCRIBERS`  | `true`   |

**AI Metadata Optimization:**

| Configuration | Environment Variable           | Default      |
| ------------- | ------------------------------ | ------------ |
| Model         | `YOUTUBE_METADATA_MODEL`       | Claude       |
| Max Tokens    | `YOUTUBE_METADATA_MAX_TOKENS`  | Configurable |
| Temperature   | `YOUTUBE_METADATA_TEMPERATURE` | Configurable |

**Authentication:** OAuth 2.0 with refresh token

**Features:**

- Resumable video uploads
- Thumbnail generation and upload
- AI-optimized metadata (title, description, tags)
- Subscriber notification control

---

### TikTok Business API v2

**Location:** `packages/social/tiktok-business-setup/src/tiktok.ts`

**Purpose:** TikTok video publishing and analytics

| Configuration | Environment Variable         | Default           |
| ------------- | ---------------------------- | ----------------- |
| Client Key    | `TIKTOK_CLIENT_KEY`          | Required          |
| Client Secret | `TIKTOK_CLIENT_SECRET`       | Required          |
| Scopes        | `TIKTOK_SCOPES`              | `user.info.basic` |
| OAuth Port    | `TIKTOK_OAUTH_PORT`          | `8434`            |
| Redirect Path | `TIKTOK_OAUTH_REDIRECT_PATH` | `/oauth2callback` |
| Refresh Token | `TIKTOK_REFRESH_TOKEN`       | Required          |

**Base URL:** `https://open-api.tiktok.com/v2`

**Endpoints:**

| Method | Path                          | Purpose           |
| ------ | ----------------------------- | ----------------- |
| GET    | `/user/info/`                 | Get user info     |
| POST   | `/post/publish/video/init/`   | Initialize upload |
| POST   | `/post/publish/status/fetch/` | Check status      |

**Authentication:** Bearer token in Authorization header

**Privacy Levels:**

- `PUBLIC_TO_EVERYONE`
- `MUTUAL_FOLLOW_FRIENDS`
- `FOLLOWER_OF_CREATOR`
- `SELF_ONLY`

**Additional Packages:**

- `@yaa/video-tiktok-analytics` - Performance metrics
- `@yaa/video-tiktok-sound-trends` - Audio trend tracking

---

### Instagram/Meta Graph API

**Location:** `packages/social/instagram-business-setup/src/meta.ts`

**Purpose:** Instagram Business publishing

| Configuration       | Environment Variable         | Default           |
| ------------------- | ---------------------------- | ----------------- |
| OAuth Client ID     | `META_OAUTH_CLIENT_ID`       | Required          |
| OAuth Client Secret | `META_OAUTH_CLIENT_SECRET`   | Required          |
| Scopes              | `META_OAUTH_SCOPES`          | See below         |
| API Version         | `META_GRAPH_API_VERSION`     | `v20.0`           |
| OAuth Port          | `META_OAUTH_PORT`            | `8436`            |
| Redirect Path       | `META_OAUTH_REDIRECT_PATH`   | `/oauth2callback` |
| User Token          | `META_LONG_LIVED_USER_TOKEN` | Required          |
| Page ID             | `META_PAGE_ID`               | Required          |

**Default Scopes:**

```
pages_show_list,pages_read_engagement,pages_manage_metadata,instagram_basic
```

**Base URL:** `https://graph.facebook.com/{version}`

**Endpoints:**

| Method | Path                 | Purpose        |
| ------ | -------------------- | -------------- |
| GET    | `/me/accounts`       | List pages     |
| GET    | `/{pageId}`          | Get page info  |
| GET    | `/{instagramUserId}` | Get IG account |

**Authentication:** Access token in query parameter

**Pagination:** 100 items per request, max 20 pages

---

### WhatsApp Business Cloud API

**Location:** `packages/social/whatsapp-business-service/src/client.ts`

**Purpose:** WhatsApp broadcast messaging

| Configuration   | Environment Variable            | Default  |
| --------------- | ------------------------------- | -------- |
| Access Token    | `WHATSAPP_ACCESS_TOKEN`         | Required |
| Phone Number ID | `WHATSAPP_PHONE_NUMBER_ID`      | Required |
| Webhook Token   | `WHATSAPP_WEBHOOK_VERIFY_TOKEN` | Required |
| App Secret      | `WHATSAPP_APP_SECRET`           | Required |
| API Version     | `WHATSAPP_GRAPH_API_VERSION`    | `v20.0`  |

**Base URL:** `https://graph.facebook.com/{version}`

**Endpoint:** `POST /{phoneNumberId}/messages`

**Message Structure:**

```typescript
{
  messaging_product: 'whatsapp';
  to: string;
  type: 'text';
  text: {
    body: string;
    preview_url?: boolean;
  };
}
```

**Authentication:** Bearer token in Authorization header

---

### X/Twitter API

**Location:** `packages/social/x-account-setup/src/oauth1.ts`

**Purpose:** X/Twitter account integration

| Configuration       | Environment Variable          | Default           |
| ------------------- | ----------------------------- | ----------------- |
| Consumer Key        | `TWITTER_CONSUMER_KEY`        | Required          |
| Consumer Secret     | `TWITTER_CONSUMER_SECRET`     | Required          |
| OAuth Port          | `TWITTER_OAUTH_PORT`          | `8437`            |
| Redirect Path       | `TWITTER_OAUTH_REDIRECT_PATH` | `/oauth1callback` |
| Access Token        | `TWITTER_ACCESS_TOKEN`        | Required          |
| Access Token Secret | `TWITTER_ACCESS_TOKEN_SECRET` | Required          |

**Authentication:** OAuth 1.0a with HMAC-SHA1 signature

**Signature Components:**

- Consumer key and secret
- Token and token secret
- Request method, URL, and parameters
- Nonce and timestamp
- RFC 3986 percent encoding

---

### Telegram Bot API

**Location:** `packages/social/telegram-channel-setup/src/telegram.ts`

**Purpose:** Telegram channel management

| Configuration | Environment Variable          | Default  |
| ------------- | ----------------------------- | -------- |
| Bot Token     | `TELEGRAM_BOT_TOKEN`          | Required |
| Channel       | `TELEGRAM_CHANNEL`            | Required |
| Channel Photo | `TELEGRAM_CHANNEL_PHOTO_PATH` | Optional |

**Base URL:** `https://api.telegram.org/bot{botToken}`

**Endpoints:**

| Method | Path                    | Purpose            |
| ------ | ----------------------- | ------------------ |
| POST   | `/getMe`                | Get bot info       |
| POST   | `/getChat`              | Get chat info      |
| POST   | `/getChatMember`        | Check member       |
| POST   | `/setChatTitle`         | Update title       |
| POST   | `/setChatDescription`   | Update description |
| POST   | `/setChatPhoto`         | Update photo       |
| POST   | `/createChatInviteLink` | Create invite      |
| POST   | `/sendMessage`          | Send message       |
| POST   | `/pinChatMessage`       | Pin message        |

**Authentication:** Bot token in URL

---

### LinkedIn Company Page

**Location:** `packages/social/linkedin-company-page-setup/`

| Configuration | Environment Variable           | Default                |
| ------------- | ------------------------------ | ---------------------- |
| Client ID     | `LINKEDIN_CLIENT_ID`           | Required               |
| Client Secret | `LINKEDIN_CLIENT_SECRET`       | Required               |
| Scopes        | `LINKEDIN_SCOPES`              | `openid profile email` |
| OAuth Port    | `LINKEDIN_OAUTH_PORT`          | `8438`                 |
| Redirect Path | `LINKEDIN_OAUTH_REDIRECT_PATH` | `/oauth2callback`      |
| Access Token  | `LINKEDIN_ACCESS_TOKEN`        | Required               |

---

## Data/Content APIs

### Ghana Stock Exchange (GSE)

**Location:** `packages/ai/market-summary-generator/src/gse.ts`

**Integration Type:** Web scraping (HTML parsing)

**URL:** Ghana Stock Exchange equities table

**Parsing:** Cheerio HTML parser

**Data Extracted:**

- Trading day
- Date (DMY → ISO format)
- Trading volume
- GSE Composite Index
- Market capitalization (GHc Million)
- Financial Stock Index

**Features:**

- Weekly equities snapshot
- Latest and previous data comparison
- Configurable timeout

---

### Forex Rates (Open Exchange Rates)

**Location:** `packages/ai/market-summary-generator/src/forex.ts`

**API Provider:** Open Exchange Rates

**Base URL:** `https://openexchangerates.org`

**Data Extracted:**

- Base currency (USD)
- GHS (Ghanaian Cedis) per USD
- GBP per USD
- EUR per USD
- Cross rates (GHS per GBP, GHS per EUR)

**Response Fields:**

- `time_last_update_utc` - Timestamp
- `rates` - Currency rates object

---

### Event Calendar (Nager.Date)

**Location:** `packages/ai/event-calendar-updater/src/nager.ts`

**Purpose:** Holiday and event data for Ghana

**Use Cases:**

- Public holiday awareness
- Event calendar updates
- Content scheduling

---

## Fact-Checking APIs

### Google Fact Check Tools API

**Location:** `packages/ai/fact-check-integrations/src/google-factcheck.ts`

| Configuration | Environment Variable       | Default  |
| ------------- | -------------------------- | -------- |
| API Key       | `GOOGLE_FACTCHECK_API_KEY` | Required |

**Base URL:** `https://factchecktools.googleapis.com/v1alpha1`

**Endpoint:** `GET /claims:search`

**Query Parameters:**

| Parameter                   | Description                |
| --------------------------- | -------------------------- |
| `key`                       | API key                    |
| `query`                     | Search query               |
| `languageCode`              | Language filter            |
| `pageSize`                  | Results per page (max 100) |
| `pageToken`                 | Pagination token           |
| `maxAgeDays`                | Maximum age of results     |
| `reviewPublisherSiteFilter` | Filter by publisher        |

**IFCN Certified Publishers:**

- PolitiFact
- Snopes
- FactCheck.org
- AP News
- Reuters
- AFP
- Full Fact
- Africa Check

**Features:**

- Multi-language searching
- Pagination support
- Publisher filtering
- Rating score normalization (0-1)

---

### ClaimBuster API

**Location:** `packages/ai/fact-check-integrations/src/claimbuster.ts`

| Configuration | Environment Variable  | Default  |
| ------------- | --------------------- | -------- |
| API Key       | `CLAIMBUSTER_API_KEY` | Required |

**Base URL:** `https://idir.uta.edu/claimbuster/api/v2`

**Endpoints:**

| Method | Path                | Purpose               |
| ------ | ------------------- | --------------------- |
| POST   | `/score/text/`      | Score checkworthiness |
| POST   | `/query/termmatch/` | Search similar claims |
| POST   | `/query/kgmatch/`   | Knowledge graph match |

**Request Structure:**

```typescript
{
  input_text: string;  // Text to analyze
  input_claim?: string; // Claim to match
  top_n?: number;      // Number of results
}
```

**Response:**

- Checkworthiness scores (0-1)
- Matching claims with similarity
- Sentence-level analysis

---

## Search Infrastructure

### Elasticsearch

**Location:** `packages/api/src/infrastructure/elasticsearch/createClient.ts`

| Configuration | Environment Variable | Default                 |
| ------------- | -------------------- | ----------------------- |
| URL           | `ELASTICSEARCH_URL`  | `http://localhost:9200` |

**Features:**

- Full-text article search
- Search suggestions
- Personalized ranking
- Article indexing via outbox pattern

---

## Web Search APIs

### Brave Search API

**Location:** `packages/nlp/evidence-retrieval-service/src/brave.ts`

| Configuration | Environment Variable    | Default                        |
| ------------- | ----------------------- | ------------------------------ |
| API Key       | `BRAVE_SEARCH_API_KEY`  | Required                       |
| Base URL      | `BRAVE_SEARCH_BASE_URL` | `https://api.search.brave.com` |

**Features:**

- Web search for evidence retrieval
- Freshness filtering (day, week, month, year)
- Language and country parameters
- Customizable result count

**Response Format:**

```typescript
{
  url: string;
  title: string;
  snippet: string;
  source?: string;
  publishDate?: string;
}
```

---

### Serper API

**Location:** `packages/nlp/evidence-retrieval-service/src/serper.ts`

| Configuration | Environment Variable | Default                     |
| ------------- | -------------------- | --------------------------- |
| API Key       | `SERPER_API_KEY`     | Required                    |
| Base URL      | `SERPER_BASE_URL`    | `https://google.serper.dev` |

**Endpoint:** `POST /search`

**Request Parameters:**

| Parameter | Description               |
| --------- | ------------------------- |
| `q`       | Search query              |
| `num`     | Results (1-20)            |
| `gl`      | Country code              |
| `hl`      | Language code             |
| `tbs`     | Time filter (qdr:d/w/m/y) |

**Retry Logic:** Up to 6 attempts with timeout handling

---

## Storage Services

### S3/MinIO

**Location:** Multiple packages

| Configuration | Environment Variable | Default                 |
| ------------- | -------------------- | ----------------------- |
| Bucket        | `S3_BUCKET`          | `yaa-dev`               |
| Region        | `S3_REGION`          | `us-east-1`             |
| Endpoint      | `S3_ENDPOINT`        | `http://localhost:9000` |
| Access Key    | `S3_ACCESS_KEY`      | `minioadmin`            |
| Secret Key    | `S3_SECRET_KEY`      | `minioadmin`            |

**Use Cases:**

- Video HLS segment storage
- Media file storage
- Content delivery

---

### Redis

**Location:** Multiple packages

| Configuration | Environment Variable  | Default                  |
| ------------- | --------------------- | ------------------------ |
| URL           | `REDIS_URL`           | `redis://localhost:6379` |
| Sentinels     | `REDIS_SENTINELS`     | Optional                 |
| Sentinel Name | `REDIS_SENTINEL_NAME` | `yaa-master`             |

**Use Cases:**

- BullMQ job queues
- Session caching
- Rate limiting
- Real-time pub/sub

---

## Authentication & Push Notifications

### Firebase Cloud Messaging (FCM)

**Location:**

- Admin: `packages/web/src/lib/server/fcmAdmin.ts`
- Client: `packages/web/src/lib/push/fcmClient.ts`

**Admin Configuration:**

| Configuration            | Environment Variable                         |
| ------------------------ | -------------------------------------------- |
| Service Account JSON     | `FIREBASE_ADMIN_SERVICE_ACCOUNT_JSON`        |
| Service Account (Base64) | `FIREBASE_ADMIN_SERVICE_ACCOUNT_JSON_BASE64` |
| Project ID               | `FIREBASE_ADMIN_PROJECT_ID`                  |
| Client Email             | `FIREBASE_ADMIN_CLIENT_EMAIL`                |
| Private Key              | `FIREBASE_ADMIN_PRIVATE_KEY`                 |

**Client Configuration:**

| Configuration | Environment Variable                       |
| ------------- | ------------------------------------------ |
| API Key       | `NEXT_PUBLIC_FIREBASE_API_KEY`             |
| Auth Domain   | `NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN`         |
| Project ID    | `NEXT_PUBLIC_FIREBASE_PROJECT_ID`          |
| Sender ID     | `NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID` |
| App ID        | `NEXT_PUBLIC_FIREBASE_APP_ID`              |
| VAPID Key     | `NEXT_PUBLIC_FIREBASE_VAPID_KEY`           |

**Features:**

- Push notifications to device tokens
- Batch token handling
- Invalid token detection
- Web push subscription

---

### OAuth Providers

**Google OAuth 2.0:**

- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`

**Facebook OAuth:**

- `FACEBOOK_CLIENT_ID`
- `FACEBOOK_CLIENT_SECRET`

**Apple OAuth:**

- `APPLE_CLIENT_ID`
- `APPLE_CLIENT_SECRET` (signed JWT with ES256)

---

### NextAuth

**Location:** Web application authentication

| Configuration | Environment Variable      | Default                 |
| ------------- | ------------------------- | ----------------------- |
| URL           | `NEXTAUTH_URL`            | `http://localhost:3000` |
| Secret        | `NEXTAUTH_SECRET`         | Required                |
| Token Secret  | `YAA_ACCESS_TOKEN_SECRET` | Required                |

---

### Phone OTP (SMS)

| Configuration | Environment Variable | Default   |
| ------------- | -------------------- | --------- |
| OTP Secret    | `PHONE_OTP_SECRET`   | Required  |
| SMS Transport | `SMS_TRANSPORT`      | `console` |
| Twilio SID    | `TWILIO_ACCOUNT_SID` | Optional  |
| Twilio Token  | `TWILIO_AUTH_TOKEN`  | Optional  |
| Twilio Number | `TWILIO_FROM_NUMBER` | Optional  |

---

## Monitoring & Observability

### Sentry

| Configuration | Environment Variable        | Default       |
| ------------- | --------------------------- | ------------- |
| DSN           | `SENTRY_DSN`                | Optional      |
| Environment   | `SENTRY_ENVIRONMENT`        | `development` |
| Sample Rate   | `SENTRY_TRACES_SAMPLE_RATE` | `0`           |

---

### OpenTelemetry

| Configuration | Environment Variable          | Default                 |
| ------------- | ----------------------------- | ----------------------- |
| OTLP Endpoint | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` |
| Protocol      | `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf`         |

---

## Email Services

### SMTP (Mailpit for Development)

| Configuration | Environment Variable | Default              |
| ------------- | -------------------- | -------------------- |
| Host          | `SMTP_HOST`          | `localhost`          |
| Port          | `SMTP_PORT`          | `1025`               |
| Secure        | `SMTP_SECURE`        | `false`              |
| User          | `SMTP_USER`          | Optional             |
| Password      | `SMTP_PASS`          | Optional             |
| From Address  | `SMTP_FROM`          | `no-reply@yaa.local` |

---

## Environment Variable Reference

### Complete List

```bash
# AI/ML Services
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
COHERE_API_KEY=
COHERE_BASE_URL=https://api.cohere.ai
COHERE_EMBEDDING_MODEL=embed-english-v3.0
COHERE_INPUT_TYPE=search_document

# Video/Media Services
HEYGEN_API_KEY=
HEYGEN_BASE_URL=https://api.heygen.com
HEYGEN_AUTH_HEADER=X-Api-Key
HEYGEN_TIMEOUT_MS=60000
HEYGEN_MAX_ATTEMPTS=4
SHOTSTACK_API_KEY=
SHOTSTACK_BASE_URL=https://api.shotstack.io
ELEVENLABS_API_KEY=
ELEVENLABS_BASE_URL=https://api.elevenlabs.io
ELEVENLABS_MODEL_ID=eleven_multilingual_v2

# YouTube
YOUTUBE_OAUTH_CLIENT_ID=
YOUTUBE_OAUTH_CLIENT_SECRET=
YOUTUBE_REFRESH_TOKEN=
YOUTUBE_PRIVACY_STATUS=public
YOUTUBE_CATEGORY_ID=25
YOUTUBE_NOTIFY_SUBSCRIBERS=true

# TikTok
TIKTOK_CLIENT_KEY=
TIKTOK_CLIENT_SECRET=
TIKTOK_SCOPES=user.info.basic
TIKTOK_OAUTH_PORT=8434
TIKTOK_REFRESH_TOKEN=

# Instagram/Meta
META_OAUTH_CLIENT_ID=
META_OAUTH_CLIENT_SECRET=
META_GRAPH_API_VERSION=v20.0
META_LONG_LIVED_USER_TOKEN=
META_PAGE_ID=

# WhatsApp
WHATSAPP_ACCESS_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_WEBHOOK_VERIFY_TOKEN=
WHATSAPP_APP_SECRET=
WHATSAPP_GRAPH_API_VERSION=v20.0

# X/Twitter
TWITTER_CONSUMER_KEY=
TWITTER_CONSUMER_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_TOKEN_SECRET=

# Telegram
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHANNEL=

# LinkedIn
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=
LINKEDIN_ACCESS_TOKEN=

# Fact-Checking
GOOGLE_FACTCHECK_API_KEY=
CLAIMBUSTER_API_KEY=

# Web Search
BRAVE_SEARCH_API_KEY=
SERPER_API_KEY=

# Storage
S3_BUCKET=yaa-dev
S3_REGION=us-east-1
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
REDIS_URL=redis://localhost:6379
ELASTICSEARCH_URL=http://localhost:9200

# Firebase
FIREBASE_ADMIN_PROJECT_ID=
FIREBASE_ADMIN_CLIENT_EMAIL=
FIREBASE_ADMIN_PRIVATE_KEY=
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=

# OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=
APPLE_CLIENT_ID=
APPLE_CLIENT_SECRET=

# Auth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=
YAA_ACCESS_TOKEN_SECRET=

# SMS
PHONE_OTP_SECRET=
SMS_TRANSPORT=console
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_FROM_NUMBER=

# Monitoring
SENTRY_DSN=
SENTRY_ENVIRONMENT=development
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Email
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=no-reply@yaa.local

# Database
DATABASE_URL=postgresql://yaa:yaa_dev@localhost:5432/yaa_dev
```

---

## Integration Patterns

### Retry Logic

All API clients implement consistent retry patterns:

```typescript
async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxAttempts: number = 4,
  baseDelayMs: number = 250
): Promise<Response> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await fetch(url, {
        ...options,
        signal: AbortSignal.timeout(timeoutMs),
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('retry-after');
        const delayMs = retryAfter
          ? parseInt(retryAfter) * 1000
          : baseDelayMs * attempt;
        await sleep(delayMs);
        continue;
      }

      if (response.status >= 500) {
        await sleep(baseDelayMs * attempt);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      await sleep(baseDelayMs * attempt);
    }
  }
  throw new Error('Max retry attempts exceeded');
}
```

### OAuth 2.0 Flow

Standard OAuth 2.0 implementation for social platforms:

```typescript
interface OAuth2Config {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
  scopes: string[];
  authorizationUrl: string;
  tokenUrl: string;
}

async function refreshAccessToken(
  config: OAuth2Config,
  refreshToken: string
): Promise<TokenResponse> {
  const response = await fetch(config.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: config.clientId,
      client_secret: config.clientSecret,
      refresh_token: refreshToken,
    }),
  });
  return response.json();
}
```

### OAuth 1.0a Signature (X/Twitter)

HMAC-SHA1 signature for OAuth 1.0a:

```typescript
function generateOAuth1Signature(
  method: string,
  url: string,
  params: Record<string, string>,
  consumerSecret: string,
  tokenSecret: string
): string {
  const signatureBase = [
    method.toUpperCase(),
    percentEncode(url),
    percentEncode(sortedParamString(params)),
  ].join('&');

  const signingKey = [
    percentEncode(consumerSecret),
    percentEncode(tokenSecret),
  ].join('&');

  return crypto
    .createHmac('sha1', signingKey)
    .update(signatureBase)
    .digest('base64');
}
```

### Hybrid Provider Routing (TTS)

Language-based provider selection:

```typescript
const LANGUAGE_ROUTING: Record<string, 'elevenlabs' | 'ghana-nlp'> = {
  en: 'elevenlabs',
  tw: 'ghana-nlp', // Twi
  ee: 'ghana-nlp', // Ewe
  gaa: 'ghana-nlp', // Ga
  dag: 'ghana-nlp', // Dagbani
  ha: 'ghana-nlp', // Hausa
};

function selectTTSProvider(
  languageCode: string,
  mode: RoutingMode
): TTSProvider {
  const defaultProvider = LANGUAGE_ROUTING[languageCode] || 'elevenlabs';

  switch (mode) {
    case 'cost-optimized':
      return cheapestProvider(languageCode);
    case 'quality-first':
      return bestQualityProvider(languageCode);
    default:
      return defaultProvider;
  }
}
```

---

_Last Updated: January 2026_

_Part of the Veritas domain integration documentation_
