Flexport Multi-Environment Setup Skill

Flexport Multi-Environment Setup

Overview

Configure isolated Flexport environments for development, staging, and production with separate API keys, webhook endpoints, and safety guards to prevent production data access from dev.

Instructions

Environment Configuration

// src/config/flexport.ts
interface FlexportConfig {
  apiKey: string;
  baseUrl: string;
  webhookSecret: string;
  cacheTtlMs: number;
  logLevel: 'debug' | 'info' | 'warn';
}

const configs: Record<string, FlexportConfig> = {
  development: {
    apiKey: process.env.FLEXPORT_API_KEY_DEV!,
    baseUrl: 'https://api.flexport.com',  // Same base, different key scope
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET_DEV!,
    cacheTtlMs: 30_000,   // 30s in dev for fast iteration
    logLevel: 'debug',
  },
  staging: {
    apiKey: process.env.FLEXPORT_API_KEY_STAGING!,
    baseUrl: 'https://api.flexport.com',
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET_STAGING!,
    cacheTtlMs: 60_000,
    logLevel: 'info',
  },
  production: {
    apiKey: process.env.FLEXPORT_API_KEY!,
    baseUrl: 'https://api.flexport.com',
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET!,
    cacheTtlMs: 300_000,  // 5min in prod
    logLevel: 'warn',
  },
};

export function getFlexportConfig(): FlexportConfig {
  const env = process.env.NODE_ENV || 'development';
  const config = configs[env];
  if (!config) throw new Error(`No Flexport config for env: ${env}`);
  if (!config.apiKey) throw new Error(`Missing FLEXPORT_API_KEY for ${env}`);
  return config;
}

Environment Variable Template

# .env.example
# Development (read-only scope, limited data access)
FLEXPORT_API_KEY_DEV=fp_dev_...
FLEXPORT_WEBHOOK_SECRET_DEV=whsec_dev_...

# Staging (read-write scope, test data)
FLEXPORT_API_KEY_STAGING=fp_stg_...
FLEXPORT_WEBHOOK_SECRET_STAGING=whsec_stg_...

# Production (full scope, real shipments)
FLEXPORT_API_KEY=fp_prod_...
FLEXPORT_WEBHOOK_SECRET=whsec_prod_...

Production Safety Guard

// Prevent accidental production API calls from dev/test
function assertNotProduction(operation: string) {
  if (process.env.NODE_ENV === 'production') return;
  const config = getFlexportConfig();
  if (config.apiKey.startsWith('fp_prod_')) {
    throw new Error(`SAFETY: ${operation} blocked — production key detected in ${process.env.NODE_ENV}`);
  }
}

// Usage in destructive operations
async function deleteProduct(id: string) {
  assertNotProduction('deleteProduct');
  await flexport(`/products/${id}`, { method: 'DELETE' });
}

Environment Matrix

| Aspect | Dev | Staging | Production | |--------|-----|---------|------------| | API key scope | Read-only | Read-write | Full | | Webhook endpoint | localhost:3000 | staging.app.com | app.com | | Cache TTL | 30s | 60s | 5min | | Rate limit budget | 10/min | 50/min | 100/min | | Logging | Debug (all) | Info | Warn + errors |

Resources

Flexport Developer Portal

Next Steps

For observability setup, see flexport-observability.

Agent Skills: Flexport Multi-Environment Setup

Install this agent skill to your local

Skill Files