Nimba API Client Usage Guide

This document provides guidance on using the auto-generated Nimba API client.

Overview

The @nimba/api-client package provides a strongly-typed TypeScript client for interacting with the Nimba API. It's generated from the OpenAPI schema and includes clean method names without controller prefixes.

Setup

The API client is available as a workspace package in the Nimba monorepo. To use it in another project within the monorepo:

1. Add the dependency to your project's package.json:

   "dependencies": {
     "@nimba/api-client": "workspace:*"
   }

2. Ensure the TypeScript path mappings are correctly set up in tsconfig.base.json:

   "paths": {
     "@nimba/api-client": ["libs/api-client/src"],
     "@nimba/api-client/*": ["libs/api-client/src/*"],
     // ... other paths
   }

Usage

The API client provides a clean, type-safe interface for accessing all the API endpoints. Here's an example:

import { client } from '@nimba/api-client';

// Set base URL if needed (defaults to http://localhost:3000)
client.setBaseUrl('http://api.example.com');

// Authentication
await client.auth.login({
  email: '[email protected]',
  password: 'password123'
});

// Get user profile
const profile = await client.auth.getProfile();
console.log('User profile:', profile);

// Get all users
const users = await client.users.findAll();
console.log('All users:', users);

// Get specific user
const user = await client.users.findOne('123');
console.log('User details:', user);

// Health check
const health = await client.health.check();
console.log('API health:', health);

// Logout
await client.auth.logout();
console.log('Logged out successfully');

Available Services

The client provides access to the following services:

• client.apppreferences - App preferences API
• client.app - App API
• client.auth - Authentication API
• client.health - Health check API
• client.users - Users API

Known Issues

1. Module Compatibility

   The API client uses ES module syntax (export/import) and may not be compatible with CommonJS environments using require(). When integrating with projects that use CommonJS, you may need to:

   • Use esModuleInterop in your TypeScript configuration
   • Set up proper transpilation or bundling to handle ES modules
   • Use dynamic imports if needed: const { client } = await import('@nimba/api-client')

2. NestJS Integration

   For NestJS applications, use the provided module:

   import { ApiClientModule } from '@nimba/api-client';
      
   @Module({
     imports: [
       ApiClientModule.forRoot({
         baseUrl: 'http://api.example.com',
       }),
     ],
   })
   export class AppModule {}

CLI Integration

When integrating with the CLI app, ensure that:

1. The @nimba/api-client is properly listed as a dependency in the CLI's package.json
2. TypeScript is configured to handle ES modules correctly
3. The CLI is using a compatible module system

Troubleshooting

If you encounter errors like:

Cannot find module '@nimba/api-client' or its corresponding type declarations

Ensure that:

1. The path mappings are correctly set up in tsconfig.base.json
2. The library is built or properly linked

For module errors like:

SyntaxError: Unexpected token 'export'

Ensure that your environment is configured to handle ES modules correctly.

Generating the Client

The API client can be regenerated using:

cd nimba
pnpm --filter @nimba/api-client run client:generate

This will fetch the latest OpenAPI schema from the running API server and regenerate the client code.