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#
- Overview
- AI/ML Services
- Video/Media Services
- Social Media APIs
- Data/Content APIs
- Fact-Checking APIs
- Search Infrastructure
- Web Search APIs
- Storage Services
- Authentication & Push Notifications
- Monitoring & Observability
- Email Services
- Environment Variable Reference
- 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:
{
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:
{
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:
{
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_EVERYONEMUTUAL_FOLLOW_FRIENDSFOLLOWER_OF_CREATORSELF_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:
{
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- Timestamprates- 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:
{
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:
{
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_IDGOOGLE_CLIENT_SECRET
Facebook OAuth:
FACEBOOK_CLIENT_IDFACEBOOK_CLIENT_SECRET
Apple OAuth:
APPLE_CLIENT_IDAPPLE_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#
# 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:
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:
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:
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:
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