@mesalvo/api-client

Official Mesalvo library to sync frontend models with backend API definitions.

It uses Orval to automatically generate TypeScript clients from OpenAPI/Swagger specs.

📦 Installation

pnpm add @mesalvo/api-client

🚀 Usage

import { metadataClient, nlpClient, authClient } from '@mesalvo/api-client';

// Example: Create a form
const response = await metadataClient.createForm({
  name: 'Patient Intake Form',
  // ...
});

// Example: Chat with AI
const chatResponse = await nlpClient.chat({
  messages: [{ role: 'user', content: 'Hello' }]
});

🔄 Code Generation Workflow

Architecture

Backend Swagger → fetch-swagger.ts → openapi/*.json → Orval → clients/*/client.ts + models/
                                                              ↓
                                                         src/index.ts (exports)
                                                              ↓
                                                         tsup build → dist/

When to regenerate?

Regenerate clients when:

• ✅ Backend API changes (new endpoints, modified DTOs)
• ✅ New microservice is added
• ✅ Swagger specs are updated

DO NOT regenerate for:

• ❌ Every build (too slow, requires backend access)
• ❌ CI/CD builds (use committed files)
• ❌ Local development (unless API changed)

How to regenerate clients

# Full regeneration (requires backend access + credentials)
pnpm codegen

# Step by step:
pnpm codegen:fetch      # Download Swagger JSONs from backend
pnpm codegen:clients    # Generate client folder structure
pnpm codegen:orval      # Run Orval to generate TypeScript
pnpm codegen:fix        # Fix Orval quirks
pnpm codegen:index      # Generate index exports

Requirements:

• Backend must be running (or accessible)
• Environment variables: ACTUATOR_USERNAME, ACTUATOR_PASSWORD
• See src/config/api-config.ts for configuration

Generated files are NOT committed

Important: The clients/ and openapi/ directories are NOT committed to Git.

Why?

• ✅ Smaller repository size (~1000+ files avoided)
• ✅ No merge conflicts on generated code
• ✅ Cleaner PRs
• ✅ Always fresh from backend

Trade-offs:

• ❌ CI/CD must regenerate (adds ~30s to build)
• ❌ Requires backend access during build
• ❌ Cannot build offline

For local development:

# First time setup or when API changes
pnpm codegen:api

# Then build normally
pnpm build

🏗️ Build

# Build the package
pnpm build

# Watch mode for development
pnpm dev

The build uses tsup to bundle src/index.ts → dist/ (ESM + CJS + types).

🧪 Testing

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm coverage

📁 Project Structure

packages/api-client/
├── src/
│   ├── index.ts              # Main exports (generated)
│   ├── config/               # API configuration
│   ├── scripts/              # Codegen scripts
│   └── utils/                # Custom fetcher
├── clients/                  # Generated clients (COMMITTED)
│   ├── auth/
│   │   ├── client.ts
│   │   └── models/
│   ├── nlp/
│   ├── metadata/
│   └── ...
├── openapi/                  # Swagger JSONs (COMMITTED)
│   ├── auth.json
│   ├── nlp.json
│   └── ...
├── dist/                     # Build output (gitignored)
└── orval.config.ts           # Orval configuration

🔧 Configuration

Orval Config (orval.config.ts)

Automatically detects all openapi/*.json files and generates clients:

{
  input: './openapi/auth.json',
  output: {
    target: './clients/auth/client.ts',
    schemas: './clients/auth/models',
    client: 'fetch',
    mutator: './src/utils/fetcher.ts'  // Custom fetcher with auth
  }
}

API Config (src/config/api-config.ts)

Configure backend URL and services to fetch:

export const config = {
  domain: 'https://mesalvo.dev.mesalvo.com',
  services: ['auth', 'nlp', 'metadata', 'diagnostics', ...]
}

🤝 Contributing

When adding a new microservice:

1. Add service name to src/config/api-config.ts
2. Run pnpm codegen
3. Commit the generated files
4. Create PR with the changes

📝 Notes

• Custom Fetcher: All clients use src/utils/fetcher.ts which adds authentication
• TypeScript: Fully typed - all DTOs and endpoints have types
• Tree-shakeable: Import only what you need
• Monorepo: Uses workspace protocol for internal dependencies