Eve library

Yaa External API Integrations

Guide

Revision 1

On this page

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
  2. AI/ML Services
  3. Video/Media Services
  4. Social Media APIs
  5. Data/Content APIs
  6. Fact-Checking APIs
  7. Search Infrastructure
  8. Web Search APIs
  9. Storage Services
  10. Authentication & Push Notifications
  11. Monitoring & Observability
  12. Email Services
  13. Environment Variable Reference
  14. 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:

text
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