npm package: @nimba/api-client
Description: API client for Nimba API
Latest version: 0.1.8

# 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:
   ```json
   "dependencies": {
     "@nimba/api-client": "workspace:*"
   }
   ```

2. Ensure the TypeScript path mappings are correctly set up in `tsconfig.base.json`:
   ```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:

```typescript
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: 'user@example.com',
  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:
   
   ```typescript
   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:

```bash
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.