Standards

// Base response wrapper with discriminated union
type ApiResponse<T, M = {}> =
  | { success: true; data: T; meta: BaseMeta & M } // Success with extendable meta
  | { success: false; error: ApiErrorBody; meta: BaseMeta } // Error with fixed meta

// Base meta - always present in all responses
interface BaseMeta {
  requestId: string // Required: for log correlation
  timestamp: string // Required: ISO 8601, for distributed debugging
}

// Pagination meta (for list responses)
interface PaginationMeta {
  pagination: {
    total: number
    page: number
    pageSize: number
    hasMore: boolean
    nextCursor?: string // For cursor-based pagination
  }
}

// Workflow meta (for long-running tasks via Trigger.dev)
interface WorkflowMeta {
  workflowId?: string // Trigger.dev run ID for polling status
  estimatedDuration?: number // Hint for UI progress (ms)
}

// Debug meta (development/troubleshooting)
interface DebugMeta {
  duration: number // Request duration in milliseconds
}

// Deprecation warnings
interface DeprecationMeta {
  warnings: DeprecationWarning[]
}

interface DeprecationWarning {
  code: 'DEPRECATED_FIELD' | 'DEPRECATED_ENDPOINT'
  message: string
  field?: string
  sunset?: string // ISO 8601 date when feature will be removed
  migration?: string // URL to migration guide
}

interface ApiErrorBody {
  code: string // Machine-readable: "VALIDATION_ERROR", "NOT_FOUND"
  message: string // Human-readable description
  details?: Record<string, unknown> // Additional error context
}

// ❌ Will require breaking change
interface Server {
  status: 'available' | 'provisioning' | 'error'
  bmcAddress: string
}

// ✅ Extensible
interface Server {
  status: {
    state: 'available' | 'provisioning' | 'error'
    reason?: string
    since?: string
    conditions?: Condition[]
  }
  bmc: {
    address: string
    protocol?: 'ipmi' | 'redfish'
    vendor?: string
  }
}

// ❌ Trouble waiting to happen
interface Server {
  isOnline: boolean
  isHealthy: boolean
}

// ✅ Extensible
interface Server {
  power: {
    state: 'on' | 'off' | 'unknown'
  }
  health: {
    state: 'healthy' | 'degraded' | 'unhealthy' | 'unknown'
  }
}

// ❌ Embedded - can't change cardinality later
{
  "id": "srv_123",
  "cluster": {
    "id": "cls_456",
    "name": "prod-cluster"
  }
}

# Atlas APIs (api.internal.example.com)
https://api.internal.example.com/v1/region/global/compute/servers
https://api.internal.example.com/v1/region/global/compute/clusters
https://api.internal.example.com/v1/region/global/organizations

# Arc APIs (api.example.com)
https://api.example.com/v1/region/{region}/projects
https://api.example.com/v1/region/{region}/compute/clusters
https://api.example.com/v1/region/{region}/stacks

# Shared Services (both domains)
/v1/region/global/auth
/v1/region/global/notifications
/v1/region/global/webhooks

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "...",
    "timestamp": "...",
    "warnings": [
      {
        "code": "DEPRECATED_ENDPOINT",
        "message": "This endpoint is deprecated. Use /v2/servers instead.",
        "sunset": "2026-06-01",
        "migration": "https://docs.example.com/migration/v2-servers"
      }
    ]
  }
}

GET /v1/compute/servers?limit=50&offset=0
GET /v1/compute/servers?limit=50&cursor=srv_abc123

interface PaginatedResponse<T> {
  success: true
  data: T[]
  meta: {
    requestId: string
    timestamp: string
    pagination: {
      total: number
      limit: number
      offset?: number
      cursor?: string
      nextCursor?: string
      hasMore: boolean
    }
  }
}

GET /v1/compute/servers?status=available&sort=-createdAt&limit=50

export const listQuerySchema = z.object({
  // Filtering
  status: z.string().optional(),
  type: z.string().optional(),

  // Sorting
  sort: z.string().optional(),

  // Pagination
  limit: z.coerce.number().min(1).max(100).default(25),
  offset: z.coerce.number().min(0).default(0),
  cursor: z.string().optional(),
})

POST /v1/compute/servers/:serverId/actions     # Actions: power, provision, deprovision, inspect, maintenance

// Base action schema with discriminated union for type safety
export const serverActionBodySchema = z.discriminatedUnion('type', [
  // Power actions
  z.object({
    type: z.literal('power'),
    action: z.enum(['on', 'off', 'reboot', 'cycle']),
    force: z.boolean().default(false),
  }),

  // Provision actions
  z.object({
    type: z.literal('provision'),
    imageUrl: z.string().url(),
    imageChecksum: z.string().optional(),
    checksumType: z.enum(['md5', 'sha256', 'sha512']).optional(),
    rootDeviceHints: z
      .object({
        deviceName: z.string().optional(),
        minSizeGiB: z.number().optional(),
      })
      .optional(),
  }),

  // Deprovision actions
  z.object({
    type: z.literal('deprovision'),
    wipeDisks: z.boolean().default(true),
  }),

  // Inspect actions
  z.object({
    type: z.literal('inspect'),
    full: z.boolean().default(false),
  }),

  // Maintenance mode actions
  z.object({
    type: z.literal('maintenance'),
    enabled: z.boolean(),
    reason: z.string().optional(),
  }),
])

POST /v1/compute/servers/bulk                     # Atlas API
POST /v1/notifications/inbox/bulk          # Shared service
POST /v1/webhooks/subscriptions/bulk       # Shared service

export const bulkRequestSchema = z.object({
  // Action type
  action: z.enum([
    'register',
    'power',
    'provision',
    'deprovision',
    'delete',
  ]),

  // Explicit resource IDs
  ids: z.array(z.string()).min(1).max(1000),

  // Optional dry-run mode
  dryRun: z.boolean().optional(),

  // Action-specific configuration
  params: z.record(z.unknown()).optional(),
})

interface BulkOperationResponse {
  success: true // Always true for bulk ops
  data: {
    action: string
    requested: number
    succeeded: number
    failed: number
    dryRun?: boolean
    wouldAffect?: number // Dry-run only
    results: Array<{
      id: string
      status: 'success' | 'failed'
      error?: {
        code: string
        message: string
      }
    }>
  }
  meta: {
    requestId: string
    timestamp: string
  }
}

POST /v1/servers/bulk
Content-Type: application/json

{
  "action": "power",
  "ids": ["srv_123", "srv_456"],
  "dryRun": true,
  "params": { "action": "off" }
}

{
  "success": true,
  "data": {
    "action": "power",
    "dryRun": true,
    "wouldAffect": 2,
    "preview": [
      { "id": "srv_123", "name": "node-01", "state": "on" },
      { "id": "srv_456", "name": "node-02", "state": "on" }
    ]
  },
  "meta": {
    "requestId": "kl4c6-1766196422377-0f705e3ef475",
    "timestamp": "2025-01-13T12:00:00.000Z"
  }
}

app.get('/servers/:id', async (c) => {
  const { id } = c.req.param()

  const server = await db.query.servers.findFirst({
    where: eq(schema.servers.id, id),
  })

  if (!server) {
    throw new NotFoundError('Server', id)
  }

  return success(c, server)
})

app.post('/servers/:id/provision', async (c) => {
  const { id } = c.req.param()
  const body = c.req.valid('json')

  const server = await db.query.servers.findFirst({
    where: eq(schema.servers.id, id),
    with: { inventory: true },
  })

  if (server.inventory.state !== 'available') {
    throw new InvalidStateTransitionError(
      'server',
      server.inventory.state,
      'provisioning'
    )
  }

  // ... continue with provisioning
})

interface AuditEvent {
  id: string // evt_<nanoid>
  timestamp: string // ISO 8601
  requestId: string // Correlation ID

  // Actor
  actor: {
    type: 'user' | 'service' | 'system'
    id: string
    email?: string // For user actors
    service?: string // For service actors
  }

  // Action
  action: string // e.g., "server.provision", "api_key.created"
  method: string // HTTP method
  path: string // Request path

  // Resource
  resource: {
    type: string // e.g., "server", "cluster", "api_key"
    id: string
    name?: string
  }

  // Context
  organizationId: string | null

  // Outcome
  outcome: 'success' | 'failure'
  statusCode: number
  errorCode?: string

  // Changes (for mutations)
  changes?: {
    before?: Record<string, unknown>
    after?: Record<string, unknown>
  }

  // Request metadata
  ip: string
  userAgent: string
  duration: number // ms
}

# Resource lifecycle
server.created
server.updated
server.deleted

# State transitions
server.provisioned
server.deprovisioned
cluster.scaled

# Access events
api_key.created
api_key.accessed
api_key.revoked
cluster_credential.downloaded
secret.accessed

# Security events
member.invited
member.role_changed
member.removed
auth.login_failed
auth.login_success

-- Enable RLS on multi-tenant tables
ALTER TABLE atlas.clusters ENABLE ROW LEVEL SECURITY;

-- Policy: Users see only their org's data
CREATE POLICY clusters_org_isolation ON atlas.clusters
  FOR ALL
  USING (organization_id = current_setting('app.current_org_id')::TEXT);

-- Policy: Service accounts bypass RLS (for background jobs)
CREATE POLICY clusters_service_bypass ON atlas.clusters
  FOR ALL
  USING (current_setting('app.is_service', true)::BOOLEAN = true);

// tests/api/servers.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { createTestClient } from '../helpers/api'

describe('Servers API', () => {
  let client: ReturnType<typeof createTestClient>

  beforeAll(async () => {
    client = createTestClient({ roles: ['provider_operator'] })
  })

  it('lists available servers', async () => {
    const res = await client.get('https://api.internal.example.com/v1/compute/servers?state=available')
    expect(res.status).toBe(200)

    const body = await res.json()
    expect(body.success).toBe(true)
    expect(body.data).toBeInstanceOf(Array)
    expect(body.meta.requestId).toBeDefined()
  })

  it('rejects invalid state filter', async () => {
    const res = await client.get('https://api.internal.example.com/v1/compute/servers?state=invalid')
    expect(res.status).toBe(400)

    const body = await res.json()
    expect(body.success).toBe(false)
    expect(body.error.code).toBe('VALIDATION_ERROR')
  })
})