AssemblyAI CI Integration

Overview

Set up CI/CD pipelines for AssemblyAI integrations with automated testing.

Prerequisites

• GitHub repository with Actions enabled
• AssemblyAI test API key
• npm/pnpm project configured

Instructions

Step 1: Create GitHub Actions Workflow

Create .github/workflows/assemblyai-integration.yml:

name: AssemblyAI Integration Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  ASSEMBLYAI_API_KEY: ${{ secrets.ASSEMBLYAI_API_KEY }}

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      ASSEMBLYAI_API_KEY: ${{ secrets.ASSEMBLYAI_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run test:integration

Step 2: Configure Secrets

gh secret set ASSEMBLYAI_API_KEY --body "sk_test_***"

Step 3: Add Integration Tests

describe('AssemblyAI Integration', () => {
  it.skipIf(!process.env.ASSEMBLYAI_API_KEY)('should connect', async () => {
    const client = getAssemblyAIClient();
    const result = await client.healthCheck();
    expect(result.status).toBe('ok');
  });
});

Output

• Automated test pipeline
• PR checks configured
• Coverage reports uploaded
• Release workflow ready

Error Handling

Examples

Release Workflow

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      ASSEMBLYAI_API_KEY: ${{ secrets.ASSEMBLYAI_API_KEY_PROD }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Verify AssemblyAI production readiness
        run: npm run test:integration
      - run: npm run build
      - run: npm publish

Branch Protection

required_status_checks:
  - "test"
  - "assemblyai-integration"

Resources

• GitHub Actions Documentation
• AssemblyAI CI Guide

Next St

AssemblyAI Common Errors

Overview

Quick reference for the top 10 most common AssemblyAI errors and their solutions.

Prerequisites

• AssemblyAI SDK installed
• API credentials configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message and code in your logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Output

• Identified error cause
• Applied fix
• Verified resolution

Error Handling

Authentication Failed

Error Message:

Authentication error: Invalid API key

Cause: API key is missing, expired, or invalid.

Solution:

# Verify API key is set
echo $ASSEMBLYAI_API_KEY

Rate Limit Exceeded

Error Message:

Rate limit exceeded. Please retry after X seconds.

Cause: Too many requests in a short period.

Solution:

Implement exponential backoff. See assemblyai-rate-limits skill.

Network Timeout

Error Message:

Request timeout after 30000ms

Cause: Network connectivity or server latency issues.

Solution:

// Increase timeout
const client = new Client({ timeout: 60000 });

Examples

Quick Diagnostic Commands

# Check AssemblyAI status
curl -s https://status.assemblyai.com

# Verify API connectivity
curl -I https://api.assemblyai.com

# Check local configuration
env | grep ASSEMBLYAI

Escalation Path

1. Collect evidence with assemblyai-debug-bundle
2. Check AssemblyAI status page
3. Contact support with request ID

Resources

• AssemblyAI Status Page
• AssemblyAI Support
• AssemblyAI Error Codes

Next Steps

For comprehensive debugging, see assemblyai-debug-bundle.

AssemblyAI Core Workflow A

Overview

Primary money-path workflow for AssemblyAI. This is the most common use case.

Prerequisites

• Completed assemblyai-install-auth setup
• Understanding of AssemblyAI core concepts
• Valid API credentials configured

Instructions

Step 1: Initialize

// Step 1 implementation

Step 2: Execute

// Step 2 implementation

Step 3: Finalize

// Step 3 implementation

Output

• Completed Core Workflow A execution
• Expected results from AssemblyAI API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Common Variations

• Variation 1: Description
• Variation 2: Description

Resources

• AssemblyAI Documentation
• AssemblyAI API Reference

Next Steps

For secondary workflow, see assemblyai-core-workflow-b.

AssemblyAI Core Workflow B

Overview

Secondary workflow for AssemblyAI. Complements the primary workflow.

Prerequisites

• Completed assemblyai-install-auth setup
• Familiarity with assemblyai-core-workflow-a
• Valid API credentials configured

Instructions

Step 1: Setup

// Step 1 implementation

Step 2: Process

// Step 2 implementation

Step 3: Complete

// Step 3 implementation

Output

• Completed Core Workflow B execution
• Results from AssemblyAI API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Error Recovery

// Error handling code

Resources

• AssemblyAI Documentation
• AssemblyAI API Reference

Next Steps

For common errors, see assemblyai-common-errors.

AssemblyAI Cost Tuning

Overview

Optimize AssemblyAI costs through smart tier selection, sampling, and usage monitoring.

Prerequisites

• Access to AssemblyAI billing dashboard
• Understanding of current usage patterns
• Database for usage tracking (optional)
• Alerting system configured (optional)

Pricing Tiers

Cost Estimation

interface UsageEstimate {
  requestsPerMonth: number;
  tier: string;
  estimatedCost: number;
  recommendation?: string;
}

function estimateAssemblyAICost(requestsPerMonth: number): UsageEstimate {
  if (requestsPerMonth <= 1000) {
    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
  }

  if (requestsPerMonth <= 100000) {
    return { requestsPerMonth, tier: 'Pro', estimatedCost: 99 };
  }

  const proOverage = (requestsPerMonth - 100000) * 0.001;
  const proCost = 99 + proOverage;

  return {
    requestsPerMonth,
    tier: 'Pro (with overage)',
    estimatedCost: proCost,
    recommendation: proCost > 500
      ? 'Consider Enterprise tier for volume discounts'
      : undefined,
  };
}

Usage Monitoring

class AssemblyAIUsageMonitor {
  private requestCount = 0;
  private bytesTransferred = 0;
  private alertThreshold: number;

  constructor(monthlyBudget: number) {
    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
  }

  track(request: { bytes: number }) {
    this.requestCount++;
    this.bytesTransferred += request.bytes;

    if (this.estimatedCost() > this.alertThreshold) {
      this.sendAlert('Approaching AssemblyAI budget limit');
    }
  }

  estimatedCost(): number {
    return estimateAssemblyAICost(this.requestCount).estimatedCost;
  }

  private sendAlert(message: string) {
    // Send to Slack, email, PagerDuty, etc.
  }
}

Cost Reduction Strategies

Step 1: Request Sampling

function shouldSample(samplingRate = 0.1): boolean {
  return Math.random() < samplingRate;
}

// Use for non-critical telemetry
if (shouldSample(0.1)) { // 10% sample
  await assemblyaiClient.trackEvent(event);
}

Step 2: Batching Requests

// Instead of N individual calls
await Promise.all(ids.map(id => assemblyaiClient.get(id)));

// Use batch endpoint (1 call)
await assemblyaiClient.batchGet(ids);

Step 3: Caching (from P16)

• Cache frequently accesse

AssemblyAI Debug Bundle

Overview

Collect all necessary diagnostic information for AssemblyAI support tickets.

Prerequisites

• AssemblyAI SDK installed
• Access to application logs
• Permission to collect environment info

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# assemblyai-debug-bundle.sh

BUNDLE_DIR="assemblyai-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== AssemblyAI Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment Info

# Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "ASSEMBLYAI_API_KEY: ${ASSEMBLYAI_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 3: Gather SDK and Logs

# SDK version
npm list @assemblyai/sdk 2>/dev/null >> "$BUNDLE_DIR/summary.txt"

# Recent logs (redacted)
grep -i "assemblyai" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"

# Configuration (redacted - secrets masked)
echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
cat .env 2>/dev/null | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE_DIR/config-redacted.txt"

# Network connectivity test
echo "--- Network Test ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "API Health: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code}" https://api.assemblyai.com/health >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 4: Package Bundle

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Output

• assemblyai-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
• summary.txt - Environment and SDK info
• logs.txt - Recent redacted logs
• config-redacted.txt - Configuration (secrets removed)

Error Handling

# Add AssemblyAI secrets to Vercel
vercel secrets add assemblyai_api_key sk_live_***
vercel secrets add assemblyai_webhook_secret whsec_***

# Link to project
vercel link

# Deploy preview
vercel

# Deploy production
vercel --prod

{
  "env": {
    "ASSEMBLYAI_API_KEY": "@assemblyai_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

app = "my-assemblyai-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

# Set AssemblyAI secrets
fly secrets set ASSEMBLYAI_API_KEY=sk_live_***
fly secrets set ASSEMBLYAI_WEBHOOK_SECRET=whsec_***

# Deploy
fly deploy

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]

#!/bin/bash
# deploy-cloud-run.sh

PROJECT_ID="${GOOGLE_CLOUD_PROJECT}"
SERVICE_NAME="assemblyai-service"
REGION="us-central1"

# Build and push image
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME

# Deploy to Cloud Run
gcloud run deploy $SERVICE_NAME \
  --image gcr.io/$PROJECT_ID/$SERVICE_NAME \
  --region $REGION \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets=ASSEMBLYAI_API_KEY=assemblyai-api-key:latest

// config/assemblyai.ts
interface AssemblyAIConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  webhookSecret?: string;
}

export function getAssemblyAIConfig(): AssemblyAIConfig {
  const env = process.env.NODE_ENV || 'development';

  return {
    apiKey: process.env.ASSEMBLYAI_API_KEY!,
    environment: env as AssemblyAIConfig['environment'],
    webhookSecret: process.env.ASSEMBLYAI_WEBHOOK_SECRET,
  };
}

// api/health.ts
export async function GET() {
  const assemblyaiS

import { AssemblyAIClient } from '@assemblyai/sdk';

const client = new AssemblyAIClient({
  apiKey: process.env.ASSEMBLYAI_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

Success! Your AssemblyAI connection is working.

import { AssemblyAIClient } from '@assemblyai/sdk';

const client = new AssemblyAIClient({
  apiKey: process.env.ASSEMBLYAI_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

from assemblyai import AssemblyAIClient

client = AssemblyAIClient()

# Your first API call here

# Node.js
npm install @assemblyai/sdk

# Python
pip install assemblyai

# Set environment variable
export ASSEMBLYAI_API_KEY="your-api-key"

# Or create .env file
echo 'ASSEMBLYAI_API_KEY=your-api-key' >> .env

// Test connection code here

import { AssemblyAIClient } from '@assemblyai/sdk';

const client = new AssemblyAIClient({
  apiKey: process.env.ASSEMBLYAI_API_KEY,
});

from assemblyai import AssemblyAIClient

client = AssemblyAIClient(
    api_key=os.environ.get('ASSEMBLYAI_API_KEY')
)

my-assemblyai-project/
├── src/
│   ├── assemblyai/
│   │   ├── client.ts       # AssemblyAI client wrapper
│   │   ├── config.ts       # Configuration management
│   │   └── utils.ts        # Helper functions
│   └── index.ts
├── tests/
│   └── assemblyai.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
└── package.json

# Copy environment template
cp .env.example .env.local

# Install dependencies
npm install

# Start development server
npm run dev

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

import { describe, it, expect, vi } from 'vitest';
import { AssemblyAIClient } from '../src/assemblyai/client';

describe('AssemblyAI Client', () => {
  it('should initialize with API key', () => {
    const client = new AssemblyAIClient({ apiKey: 'test-key' });
    expect(client).toBeDefined();
  });
});

vi.mock('@assemblyai/sdk', () => ({
  AssemblyAIClient: vi.fn().mockImplementation(() => ({
    // Mock methods here
  })),
}));

# Enable verbose logging
DEBUG=ASSEMBLYAI=* npm run dev

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedAssemblyAIRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

import DataLoader from 'dataloader';

const assemblyaiLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from AssemblyAI
    const results = await assemblyaiClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  assemblyaiLoader.load('id-1'),
  assemblyaiLoader.load('id-2'),
  assemblyaiLoader.load('id-3'),
]);

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new AssemblyAIClient({
  apiKey: process.env.ASSEMBLYAI_API_KEY!,
  httpAgent: agent,
});

async function* paginatedAssemblyAIList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCurso

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.assemblyai.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/assemblyai-integration app=image:new --record
kubectl rollout pause deployment/assemblyai-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/assemblyai-integration
kubectl rollout pause deployment/assemblyai-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/assemblyai-integration
kubectl rollout status deployment/assemblyai-integration

async function healthCheck(): Promise<{ status:

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: AssemblyAIClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

my-assemblyai-project/
├── src/
│   ├── assemblyai/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── assemblyai/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── assemblyai/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── assemblyai/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── assemblyai/
│   └── integration/
│       └── assemblyai/
├── config/
│   ├── assemblyai.development.json
│   ├── assemblyai.staging.json
│   └── assemblyai.production.json
└── docs/
    └── assemblyai/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          AssemblyAI Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/assemblyai/client.ts
export class AssemblyAIService {
  private client: AssemblyAIClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: AssemblyAIConfig) {
    this.client = new AssemblyAIClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('assemblyai');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/assemblyai/errors.ts
export class AssemblyAIServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
  

// src/assemblyai/client.ts
import { AssemblyAIClient } from '@assemblyai/sdk';

let instance: AssemblyAIClient | null = null;

export function getAssemblyAIClient(): AssemblyAIClient {
  if (!instance) {
    instance = new AssemblyAIClient({
      apiKey: process.env.ASSEMBLYAI_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { AssemblyAIError } from '@assemblyai/sdk';

async function safeAssemblyAICall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof AssemblyAIError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, AssemblyAIClient>();

export function getClientForTenant(tenantId: string): AssemblyAIClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, n

# .env (NEVER commit to git)
ASSEMBLYAI_API_KEY=sk_live_***
ASSEMBLYAI_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

# 1. Generate new key in AssemblyAI dashboard
# 2. Update environment variable
export ASSEMBLYAI_API_KEY="new_key_here"

# 3. Verify new key works
curl -H "Authorization: Bearer ${ASSEMBLYAI_API_KEY}" \
  https://api.assemblyai.com/health

# 4. Revoke old key in dashboard

const clients = {
  reader: new AssemblyAIClient({
    apiKey: process.env.ASSEMBLYAI_READ_KEY,
  }),
  writer: new AssemblyAIClient({
    apiKey: process.env.ASSEMBLYAI_WRITE_KEY,
  }),
};

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success

npm list @assemblyai/sdk
npm view @assemblyai/sdk version

open https://github.com/assemblyai/sdk/releases

git checkout -b upgrade/assemblyai-sdk-vX.Y.Z
npm install @assemblyai/sdk@latest
npm test

// Before (v1.x)
import { Client } from '@assemblyai/sdk';

// After (v2.x)
import { AssemblyAIClient } from '@assemblyai/sdk';

// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new AssemblyAIClient({
  apiKey: 'xxx',
});

npm install @assemblyai/sdk@1.x.x --save-exact

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[AssemblyAI]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/assemblyai',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-assemblyai-signature'] as string;
    const timestamp = req.headers['x-assemblyai-timestamp'] as string;

    if (!verifyAssemblyAISignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleAssemblyAIEvent(event);

    res.status(200).json({ received: true });
  }
);

function verifyAssemblyAISignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.ASSEMBLYAI_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

type AssemblyAIEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface AssemblyAIEvent {
  id: string;
  type: AssemblyAIEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<AssemblyAIEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handleAssemblyAIEvent(event: AssemblyAIEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.id}`);
  } c