Migration guide: v1 to v2

# V1 - no idempotency support at all
curl -X POST /v1/brokerage/org-123/trade \
  -H "x-auth-token: ${TOKEN}" \
  -d '{"quoteId": "abc-123"}'
# Idempotency headers ignored even if provided - no duplicate protection

# V2 - idempotency key REQUIRED
curl -X POST /v2/brokerage/org-123/trade \
  -H "x-auth-token: ${TOKEN}" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"quoteId": "abc-123"}'

{
  "status": "error",
  "message": "Idempotency key is required for this endpoint",
  "error": {
    "code": "IDEMPOTENCY_KEY_REQUIRED",
    "details": "Please provide an Idempotency-Key header with a unique value (UUID recommended)"
  }
}

const BASE_URL = 'https://api.legacy-domain.com/v1/brokerage'
// or
const BASE_URL = 'https://api.other-domain.com/v1/brokerage'

const BASE_URL = 'https://api.openfx.com/v2/brokerage'

async function executeTrade(quoteId) {
  try {
    return await fetch(`${BASE_URL}/${orgId}/trade`, {
      method: 'POST',
      headers: { 'x-auth-token': authToken },
      body: JSON.stringify({ quoteId })
    })
  } catch (error) {
    // Retry with NEW request (risk of duplicate)
    return await fetch(`${BASE_URL}/${orgId}/trade`, {
      method: 'POST',
      headers: { 'x-auth-token': authToken },
      body: JSON.stringify({ quoteId })
    })
  }
}

async function executeTrade(quoteId, maxRetries = 3) {
  const idempotencyKey = uuidv4()  // Generate ONCE

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(`${BASE_URL}/${orgId}/trade`, {
        method: 'POST',
        headers: {
          'x-auth-token': authToken,
          'Idempotency-Key': idempotencyKey,  // ← SAME key on retry
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ quoteId })
      })

      if (response.ok) {
        return await response.json()
      }

      // Handle 409 Conflict (in-flight request)
      if (response.status === 409) {
        const retryAfter = response.headers.get('Retry-After') || 5
        await sleep(retryAfter * 1000)
        continue  // Retry with same key
      }

      throw new Error(`Trade failed: ${response.status}`)

    } catch (error) {
      if (attempt === maxRetries - 1) throw error
      await sleep(1000 * (attempt + 1))  // Exponential backoff
    }
  }
}

// Old endpoint
const response = await fetch(`${BASE_URL}/${orgId}/orders`)

// New endpoint
const response = await fetch(`${BASE_URL}/${orgId}/trades`)

async function handleResponse(response) {
  const data = await response.json()

  switch (response.status) {
    case 400:
      if (data.error?.code === 'IDEMPOTENCY_KEY_REQUIRED') {
        throw new Error('Idempotency key is required')
      }
      if (data.error?.code === 'INVALID_IDEMPOTENCY_KEY') {
        throw new Error('Invalid idempotency key format')
      }
      break

    case 409:
      // Concurrent request with same key
      if (data.error?.code === 'IDEMPOTENCY_IN_FLIGHT') {
        const retryAfter = response.headers.get('Retry-After') || 5
        await sleep(retryAfter * 1000)
        // Retry with same key
        return retry()
      }
      break

    case 422:
      // Same key used with different parameters
      if (data.error?.code === 'IDEMPOTENCY_MISMATCH') {
        throw new Error('Idempotency key reused with different parameters')
      }
      break

    case 503:
      // Idempotency service unavailable
      if (data.error?.code === 'IDEMPOTENCY_SERVICE_UNAVAILABLE') {
        throw new Error('Service temporarily unavailable')
      }
      break
  }

  return data
}

// UUID v4 (recommended)
'550e8400-e29b-41d4-a716-446655440000'

// UUID without hyphens
'550e8400e29b41d4a716446655440000'

// Custom format (alphanumeric + hyphens/underscores)
'trade_2024_abc123def456'

// Sequential (predictable)
'trade-1', 'trade-2', 'trade-3'

// Timestamp only (collisions)
'1234567890'

// Contains sensitive data
'user-john-smith-trade-100'

class TradeClient {
  constructor() {
    this.pendingOperations = new Map()
  }

  async executeTrade(quoteId) {
    // Generate key
    const idempotencyKey = uuidv4()

    // Store operation metadata
    this.pendingOperations.set(idempotencyKey, {
      operation: 'trade',
      quoteId,
      timestamp: Date.now(),
      status: 'pending'
    })

    try {
      const result = await this.api.post('/trade', {
        headers: { 'Idempotency-Key': idempotencyKey },
        body: { quoteId }
      })

      // Mark as completed
      this.pendingOperations.get(idempotencyKey).status = 'completed'

      return result
    } catch (error) {
      // Mark as failed
      this.pendingOperations.get(idempotencyKey).status = 'failed'
      throw error
    }
  }

  // Cleanup old operations (optional)
  cleanupOldOperations(maxAge = 24 * 60 * 60 * 1000) {
    const now = Date.now()
    for (const [key, op] of this.pendingOperations) {
      if (now - op.timestamp > maxAge) {
        this.pendingOperations.delete(key)
      }
    }
  }
}

async function executeWithRetry(operation, maxRetries = 3) {
  const idempotencyKey = uuidv4()
  let lastError

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation(idempotencyKey)
    } catch (error) {
      lastError = error

      // Don't retry on client errors (except 409)
      if (error.status >= 400 && error.status < 500 && error.status !== 409) {
        throw error
      }

      // Handle 409 (in-flight)
      if (error.status === 409) {
        const retryAfter = error.headers.get('Retry-After') || 5
        await sleep(retryAfter * 1000)
        continue
      }

      // Exponential backoff for other errors
      const backoff = Math.min(1000 * Math.pow(2, attempt), 10000)
      await sleep(backoff)
    }
  }

  throw lastError
}