Fathom Production Checklist

Overview

Complete checklist for deploying Fathom integrations to production.

Prerequisites

• Staging environment tested and verified
• Production API keys available
• Deployment pipeline configured
• Monitoring and alerting ready

Instructions

Step 1: Pre-Deployment Configuration

• [ ] Production API keys in secure vault
• [ ] Environment variables set in deployment platform
• [ ] API key scopes are minimal (least privilege)
• [ ] Webhook endpoints configured with HTTPS
• [ ] Webhook secrets stored securely

Step 2: Code Quality Verification

• [ ] All tests passing (npm test)
• [ ] No hardcoded credentials
• [ ] Error handling covers all Fathom error types
• [ ] Rate limiting/backoff implemented
• [ ] Logging is production-appropriate

Step 3: Infrastructure Setup

• [ ] Health check endpoint includes Fathom connectivity
• [ ] Monitoring/alerting configured
• [ ] Circuit breaker pattern implemented
• [ ] Graceful degradation configured

Step 4: Documentation Requirements

• [ ] Incident runbook created
• [ ] Key rotation procedure documented
• [ ] Rollback procedure documented
• [ ] On-call escalation path defined

Step 5: Deploy with Gradual Rollout

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

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/fathom-integration app=image:new --record
kubectl rollout pause deployment/fathom-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/fathom-integration
kubectl rollout pause deployment/fathom-integration
sleep 300

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

Output

• Deployed Fathom integration
• Health checks passing
• Monitoring active
• Rollback procedure documented

Error Handling

Examples

Health Check Implementation

async function healthCheck(): Promise<{ status: string; fathom: any }> {
  const start = Dat

Fathom Rate Limits

Overview

Handle Fathom rate limits gracefully with exponential backoff and idempotency.

Prerequisites

• Fathom SDK installed
• Understanding of async/await patterns
• Access to rate limit headers

Instructions

Step 1: Understand Rate Limit Tiers

Step 2: Implement Exponential Backoff with Jitter

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');
}

Step 3: Add Idempotency Keys

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: FathomClient,
  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 },
  });
}

Output

• Reliable API calls with automatic retry
• Idempotent requests preventing duplicates
• Rate limit headers properly handled

Error Handling

my-fathom-project/
├── src/
│   ├── fathom/
│   │   ├── 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/
│   │   └── fathom/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── fathom/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── fathom/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── fathom/
│   └── integration/
│       └── fathom/
├── config/
│   ├── fathom.development.json
│   ├── fathom.staging.json
│   └── fathom.production.json
└── docs/
    └── fathom/
        ├── SETUP.md
        └── RUNBOOK.md

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

// src/fathom/client.ts
export class FathomService {
  private client: FathomClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: FathomConfig) {
    this.client = new FathomClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('fathom');
  }

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

// src/fathom/errors.ts
export class FathomServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'FathomServiceError';
  }
}

export function wrapF

// src/fathom/client.ts
import { FathomClient } from '@fathom/sdk';

let instance: FathomClient | null = null;

export function getFathomClient(): FathomClient {
  if (!instance) {
    instance = new FathomClient({
      apiKey: process.env.FATHOM_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { FathomError } from '@fathom/sdk';

async function safeFathomCall<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 FathomError) {
      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, FathomClient>();

export function getClientForTenant(tenantId: string): FathomClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new FathomClient({ apiKey }));
  }
  return clients.get(tenantId)!;
}

Fathom Security Basics

Overview

Security best practices for Fathom API keys, tokens, and access control.

Prerequisites

• Fathom SDK installed
• Understanding of environment variables
• Access to Fathom dashboard

Instructions

Step 1: Configure Environment Variables

# .env (NEVER commit to git)
FATHOM_API_KEY=sk_live_***
FATHOM_SECRET=***

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

Step 2: Implement Secret Rotation

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

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

# 4. Revoke old key in dashboard

Step 3: Apply Least Privilege

Output

• Secure API key storage
• Environment-specific access controls
• Audit logging enabled

Error Handling

Examples

Service Account Pattern

const clients = {
  reader: new FathomClient({
    apiKey: process.env.FATHOM_READ_KEY,
  }),
  writer: new FathomClient({
    apiKey: process.env.FATHOM_WRITE_KEY,
  }),
};

Webhook Signature Verification

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));
}

Security Checklist

• [ ] API keys in environment variables
• [ ] .env files in .gitignore
• [ ] Different keys for dev/staging/prod
• [ ] Minimal scopes per environment
• [ ] Webhook signatures validated
• [ ] Audit logging enabled

Audit Logging

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success' | 'failure';
  metadata?: Record<string

Fathom Upgrade & Migration

Overview

Guide for upgrading Fathom SDK versions and handling breaking changes.

Prerequisites

• Current Fathom SDK installed
• Git for version control
• Test suite available
• Staging environment

Instructions

Step 1: Check Current Version

npm list @fathom/sdk
npm view @fathom/sdk version

Step 2: Review Changelog

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

Step 3: Create Upgrade Branch

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

Step 4: Handle Breaking Changes

Update import statements, configuration, and method signatures as needed.

Output

• Updated SDK version
• Fixed breaking changes
• Passing test suite
• Documented rollback procedure

Error Handling

Examples

Import Changes

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

// After (v2.x)
import { FathomClient } from '@fathom/sdk';

Configuration Changes

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

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

Rollback Procedure

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

Deprecation Handling

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Fathom]', 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

Resources

• Fathom Changelog
• Fathom Migration Guide

Next Steps

For CI integration during upgrades, see fathom-ci-integration.