Ramp CI Integration

Overview

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

Prerequisites

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

Instructions

Step 1: Create GitHub Actions Workflow

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

name: Ramp Integration Tests

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

env:
  RAMP_API_KEY: ${{ secrets.RAMP_API_KEY }}

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      RAMP_API_KEY: ${{ secrets.RAMP_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 RAMP_API_KEY --body "sk_test_***"

Step 3: Add Integration Tests

describe('Ramp Integration', () => {
  it.skipIf(!process.env.RAMP_API_KEY)('should connect', async () => {
    const client = getRampClient();
    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:
      RAMP_API_KEY: ${{ secrets.RAMP_API_KEY_PROD }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Verify Ramp production readiness
        run: npm run test:integration
      - run: npm run build
      - run: npm publish

Branch Protection

required_status_checks:
  - "test"
  - "ramp-integration"

Resources

• GitHub Actions Documentation
• Ramp CI Guide

Next Steps

For deployment patterns, see ramp-deploy-integration.

Ramp Common Errors

Overview

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

Prerequisites

• Ramp 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 $RAMP_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 ramp-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 Ramp status
curl -s https://status.ramp.com

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

# Check local configuration
env | grep RAMP

Escalation Path

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

Resources

• Ramp Status Page
• Ramp Support
• Ramp Error Codes

Next Steps

For comprehensive debugging, see ramp-debug-bundle.

Ramp Core Workflow A

Overview

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

Prerequisites

• Completed ramp-install-auth setup
• Understanding of Ramp 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 Ramp API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Common Variations

• Variation 1: Description
• Variation 2: Description

Resources

• Ramp Documentation
• Ramp API Reference

Next Steps

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

Ramp Core Workflow B

Overview

Secondary workflow for Ramp. Complements the primary workflow.

Prerequisites

• Completed ramp-install-auth setup
• Familiarity with ramp-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 Ramp API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Error Recovery

// Error handling code

Resources

• Ramp Documentation
• Ramp API Reference

Next Steps

For common errors, see ramp-common-errors.

Ramp Cost Tuning

Overview

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

Prerequisites

• Access to Ramp 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 estimateRampCost(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 RampUsageMonitor {
  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 Ramp budget limit');
    }
  }

  estimatedCost(): number {
    return estimateRampCost(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 rampClient.trackEvent(event);
}

Step 2: Batching Requests

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

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

Step 3: Caching (from P16)

• Cache frequently accessed data
• Use cache invalidation webhooks
• Set

Ramp Data Handling

Overview

Handle sensitive data correctly when integrating with Ramp.

Prerequisites

• Understanding of GDPR/CCPA requirements
• Ramp SDK with data export capabilities
• Database for audit logging
• Scheduled job infrastructure for cleanup

Data Classification

PII Detection

const PII_PATTERNS = [
  { type: 'email', regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
  { type: 'phone', regex: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g },
  { type: 'ssn', regex: /\b\d{3}-\d{2}-\d{4}\b/g },
  { type: 'credit_card', regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g },
];

function detectPII(text: string): { type: string; match: string }[] {
  const findings: { type: string; match: string }[] = [];

  for (const pattern of PII_PATTERNS) {
    const matches = text.matchAll(pattern.regex);
    for (const match of matches) {
      findings.push({ type: pattern.type, match: match[0] });
    }
  }

  return findings;
}

Data Redaction

function redactPII(data: Record<string, any>): Record<string, any> {
  const sensitiveFields = ['email', 'phone', 'ssn', 'password', 'apiKey'];
  const redacted = { ...data };

  for (const field of sensitiveFields) {
    if (redacted[field]) {
      redacted[field] = '[REDACTED]';
    }
  }

  return redacted;
}

// Use in logging
console.log('Ramp request:', redactPII(requestData));

Data Retention Policy

Retention Periods

Automatic Cleanup

async function cleanupRampData(retentionDays: number): Promise<void> {
  const cutoff = new Date();
  cutoff.setDate(cutoff.getDate() - retentionDays);

  await db.rampLogs.deleteMany({
    createdAt: { $lt: cutoff },
    type: { $nin: ['audit', 'compliance'] },
  });
}

// Schedule daily cleanup
cron.schedule('0 3 * * *', () => cleanupRampData(30));

GDPR/CC

Ramp Debug Bundle

Overview

Collect all necessary diagnostic information for Ramp support tickets.

Prerequisites

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

Instructions

Step 1: Create Debug Bundle Script

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

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

echo "=== Ramp 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 "RAMP_API_KEY: ${RAMP_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 3: Gather SDK and Logs

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

# Recent logs (redacted)
grep -i "ramp" ~/.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.ramp.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

• ramp-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 Ramp secrets to Vercel
vercel secrets add ramp_api_key sk_live_***
vercel secrets add ramp_webhook_secret whsec_***

# Link to project
vercel link

# Deploy preview
vercel

# Deploy production
vercel --prod

{
  "env": {
    "RAMP_API_KEY": "@ramp_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

app = "my-ramp-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 Ramp secrets
fly secrets set RAMP_API_KEY=sk_live_***
fly secrets set RAMP_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="ramp-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=RAMP_API_KEY=ramp-api-key:latest

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

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

  return {
    apiKey: process.env.RAMP_API_KEY!,
    environment: env as RampConfig['environment'],
    webhookSecret: process.env.RAMP_WEBHOOK_SECRET,
  };
}

// api/health.ts
export async function GET() {
  const rampStatus = await checkRampConnection();

  return Response.json({
    status: rampStatus ? 'healthy' : 'degraded',
    servic

enum RampRole {
  Admin = 'admin',
  Developer = 'developer',
  Viewer = 'viewer',
  Service = 'service',
}

interface RampPermissions {
  read: boolean;
  write: boolean;
  delete: boolean;
  admin: boolean;
}

const ROLE_PERMISSIONS: Record<RampRole, RampPermissions> = {
  admin: { read: true, write: true, delete: true, admin: true },
  developer: { read: true, write: true, delete: false, admin: false },
  viewer: { read: true, write: false, delete: false, admin: false },
  service: { read: true, write: true, delete: false, admin: false },
};

function checkPermission(
  role: RampRole,
  action: keyof RampPermissions
): boolean {
  return ROLE_PERMISSIONS[role][action];
}

// Ramp SAML setup
const samlConfig = {
  entryPoint: 'https://idp.company.com/saml/sso',
  issuer: 'https://ramp.com/saml/metadata',
  cert: process.env.SAML_CERT,
  callbackUrl: 'https://app.yourcompany.com/auth/ramp/callback',
};

// Map IdP groups to Ramp roles
const groupRoleMapping: Record<string, RampRole> = {
  'Engineering': RampRole.Developer,
  'Platform-Admins': RampRole.Admin,
  'Data-Team': RampRole.Viewer,
};

import { OAuth2Client } from '@ramp/sdk';

const oauthClient = new OAuth2Client({
  clientId: process.env.RAMP_OAUTH_CLIENT_ID!,
  clientSecret: process.env.RAMP_OAUTH_CLIENT_SECRET!,
  redirectUri: 'https://app.yourcompany.com/auth/ramp/callback',
  scopes: ['read', 'write'],
});

interface RampOrganization {
  id: string;
  name: string;
  ssoEnabled: boolean;
  enforceSso: boolean;
  allowedDomains: string[];
  defaultRole: RampRole;
}

async function createOrganization(
  config: RampOrganization
): Promise<void> {
  await rampClient.organizations.create({
    ...config,
    settings: {
      sso: {
        ena

import { RampClient } from '@ramp/sdk';

const client = new RampClient({
  apiKey: process.env.RAMP_API_KEY,
});

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

main().catch(console.error);

Success! Your Ramp connection is working.

import { RampClient } from '@ramp/sdk';

const client = new RampClient({
  apiKey: process.env.RAMP_API_KEY,
});

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

main().catch(console.error);

from ramp import RampClient

client = RampClient()

# Your first API call here

# 1. Check Ramp status
curl -s https://status.ramp.com | jq

# 2. Check our integration health
curl -s https://api.yourapp.com/health | jq '.services.ramp'

# 3. Check error rate (last 5 min)
curl -s localhost:9090/api/v1/query?query=rate(ramp_errors_total[5m])

# 4. Recent error logs
kubectl logs -l app=ramp-integration --since=5m | grep -i error | tail -20

Ramp API returning errors?
├─ YES: Is status.ramp.com showing incident?
│   ├─ YES → Wait for Ramp to resolve. Enable fallback.
│   └─ NO → Our integration issue. Check credentials, config.
└─ NO: Is our service healthy?
    ├─ YES → Likely resolved or intermittent. Monitor.
    └─ NO → Our infrastructure issue. Check pods, memory, network.

# Verify API key is set
kubectl get secret ramp-secrets -o jsonpath='{.data.api-key}' | base64 -d

# Check if key was rotated
# → Verify in Ramp dashboard

# Remediation: Update secret and restart pods
kubectl create secret generic ramp-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/ramp-integration

# Check rate limit headers
curl -v https://api.ramp.com 2>&1 | grep -i rate

# Enable request queuing
kubectl set env deployment/ramp-integration RATE_LIMIT_MODE=queue

# Long-term: Contact Ramp for limit increase

# Enable graceful degradation
kubectl set env deployment/ramp-integration RAMP_FALLBACK=true

# Notify users of degraded service
# Update status page

# Monitor Ramp status for resolution

🔴 P1 INCIDENT: Ramp Integration
Status: INVESTIGATING
Impact: [Describe user impact]
Current action: [What you're doing]
Next update: [Time]
I

# Node.js
npm install @ramp/sdk

# Python
pip install ramp

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

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

// Test connection code here

import { RampClient } from '@ramp/sdk';

const client = new RampClient({
  apiKey: process.env.RAMP_API_KEY,
});

from ramp import RampClient

client = RampClient(
    api_key=os.environ.get('RAMP_API_KEY')
)

my-ramp-project/
├── src/
│   ├── ramp/
│   │   ├── client.ts       # Ramp client wrapper
│   │   ├── config.ts       # Configuration management
│   │   └── utils.ts        # Helper functions
│   └── index.ts
├── tests/
│   └── ramp.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 { RampClient } from '../src/ramp/client';

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

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

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

# Document current implementation
find . -name "*.ts" -o -name "*.py" | xargs grep -l "ramp" > ramp-files.txt

# Count integration points
wc -l ramp-files.txt

# Identify dependencies
npm list | grep ramp
pip freeze | grep ramp

interface MigrationInventory {
  dataTypes: string[];
  recordCounts: Record<string, number>;
  dependencies: string[];
  integrationPoints: string[];
  customizations: string[];
}

async function assessRampMigration(): Promise<MigrationInventory> {
  return {
    dataTypes: await getDataTypes(),
    recordCounts: await getRecordCounts(),
    dependencies: await analyzeDependencies(),
    integrationPoints: await findIntegrationPoints(),
    customizations: await documentCustomizations(),
  };
}

Phase 1: Parallel Run
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   System    │ ──▶ │  Ramp   │
│   (100%)    │     │   (0%)      │
└─────────────┘     └─────────────┘

Phase 2: Gradual Shift
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (50%)     │ ──▶ │   (50%)     │
└─────────────┘     └─────────────┘

Phase 3: Complete
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (0%)      │ ──▶ │   (100%)    │
└─────────────┘     └─────────────┘

# Install Ramp SDK
npm install @ramp/sdk

# Configure credentials
cp .env.example .env.ramp
# Edit with new credentials

# Verify connectivity
node -e "require('@ramp/sdk').ping()"

// src/adapters/ramp.ts
interface ServiceAdapter {
  create(data: CreateInput): Promise<Resource>;
  read(id: string): Promise<Resource>;
  update(id: string, data: UpdateInput): Promise<Resource>;
  delete(id: string): Promise<void>;
}

cl

config/
├── ramp/
│   ├── base.json           # Shared config
│   ├── development.json    # Dev overrides
│   ├── staging.json        # Staging overrides
│   └── production.json     # Prod overrides

{
  "timeout": 30000,
  "retries": 3,
  "cache": {
    "enabled": true,
    "ttlSeconds": 60
  }
}

{
  "apiKey": "${RAMP_API_KEY}",
  "baseUrl": "https://api-sandbox.ramp.com",
  "debug": true,
  "cache": {
    "enabled": false
  }
}

{
  "apiKey": "${RAMP_API_KEY_STAGING}",
  "baseUrl": "https://api-staging.ramp.com",
  "debug": false
}

{
  "apiKey": "${RAMP_API_KEY_PROD}",
  "baseUrl": "https://api.ramp.com",
  "debug": false,
  "retries": 5
}

// src/ramp/config.ts
import baseConfig from '../../config/ramp/base.json';

type Environment = 'development' | 'staging' | 'production';

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  const validEnvs: Environment[] = ['development', 'staging', 'production'];
  return validEnvs.includes(env as Environment)
    ? (env as Environment)
    : 'development';
}

export function getRampConfig() {
  const env = detectEnvironment();
  const envConfig = require(`../../config/ramp/${env}.json`);

  return {
    ...baseConfig,
    ...envConfig,
    environment: env,
  };
}

# .env.local (git-ignored)
RAMP_API_KEY=sk_test_dev_***

import { Registry, Counter, Histogram, Gauge } from 'prom-client';

const registry = new Registry();

const requestCounter = new Counter({
  name: 'ramp_requests_total',
  help: 'Total Ramp API requests',
  labelNames: ['method', 'status'],
  registers: [registry],
});

const requestDuration = new Histogram({
  name: 'ramp_request_duration_seconds',
  help: 'Ramp request duration',
  labelNames: ['method'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

const errorCounter = new Counter({
  name: 'ramp_errors_total',
  help: 'Ramp errors by type',
  labelNames: ['error_type'],
  registers: [registry],
});

async function instrumentedRequest<T>(
  method: string,
  operation: () => Promise<T>
): Promise<T> {
  const timer = requestDuration.startTimer({ method });

  try {
    const result = await operation();
    requestCounter.inc({ method, status: 'success' });
    return result;
  } catch (error: any) {
    requestCounter.inc({ method, status: 'error' });
    errorCounter.inc({ error_type: error.code || 'unknown' });
    throw error;
  } finally {
    timer();
  }
}

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('ramp-client');

async function tracedRampCall<T>(
  operationName: string,
  operation: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(`ramp.${operationName}`, async (span) => {
    try {
      const result = await operation();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error: any) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);
      throw err

import { LRUCache } from 'lru-cache';

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

async function cachedRampRequest<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 rampLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from Ramp
    const results = await rampClient.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([
  rampLoader.load('id-1'),
  rampLoader.load('id-2'),
  rampLoader.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 RampClient({
  apiKey: process.env.RAMP_API_KEY!,
  httpAgent: agent,
});

async function* paginatedRampList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T> {
  let cursor: string | undefined

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

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

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

async function healthCheck(): Promise<{ status: string; ramp: any }> {
  const start = Date.now();
  try {
    await

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

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

// src/ramp/client.ts
export class RampService {
  private client: RampClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: RampConfig) {
    this.client = new RampClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('ramp');
  }

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

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

export function wrapRampError(error: unknown): RampServiceError {
  /

// src/ramp/client.ts
import { RampClient } from '@ramp/sdk';

let instance: RampClient | null = null;

export function getRampClient(): RampClient {
  if (!instance) {
    instance = new RampClient({
      apiKey: process.env.RAMP_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { RampError } from '@ramp/sdk';

async function safeRampCall<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 RampError) {
      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, RampClient>();

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

# .env (NEVER commit to git)
RAMP_API_KEY=sk_live_***
RAMP_SECRET=***

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

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

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

# 4. Revoke old key in dashboard

const clients = {
  reader: new RampClient({
    apiKey: process.env.RAMP_READ_KEY,
  }),
  writer: new RampClient({
    apiKey: process.env.RAMP_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' | 'failure';
  metadata?: Record<string, any>;
}

async function

npm list @ramp/sdk
npm view @ramp/sdk version

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

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

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

// After (v2.x)
import { RampClient } from '@ramp/sdk';

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

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

npm install @ramp/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('[Ramp]', 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/ramp',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-ramp-signature'] as string;
    const timestamp = req.headers['x-ramp-timestamp'] as string;

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

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

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

function verifyRampSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.RAMP_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 RampEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface RampEvent {
  id: string;
  type: RampEventType;
  data: Record<string, any>;
  created: string;
}

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

async function handleRampEvent(event: RampEvent): 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}`);
  } catch (error) {
    console.error(`Failed to process ${event.type}: ${event.id}`, error);
    thr