# @itfin/nomi-sdk

A robust, type-safe TypeScript SDK for integrating with the Nomi Finance API. 

## Features

- **Full Type Safety:** Exhaustive TypeScript interfaces generated directly from the official OpenAPI documentation.
- **Multiple Auth Strategies:** Supports `in-app` (Bearer tokens) and `ppt` (Basic Auth via email/token).
- **Auto-Pagination:** Uses `AsyncGenerator` to effortlessly iterate through multiple pages using `for await...of`.
- **Automatic Rate Limiting:** Built-in rate limiter ensuring no more than 1 request per second to prevent API throttling.
- **Bulk Chunking:** Safely save large arrays of data using `bulkSave()`, which automatically chunks requests into optimal limits (default 100).
- **Complete Domain Coverage:** Fully supports all 6 core Nomi domains:
  - `Accounts`
  - `Projects`
  - `Counterparties`
  - `Transactions`
  - `Nomenclature`
  - `Nomenclature Movements`
  - `Property Bags` (Application configuration registry)

## Installation

```bash
npm install @itfin/nomi-sdk
```

## Quick Start

### 1. Initialize the Client

You can initialize the client using either the `in-app` or `ppt` authentication strategy.

#### In-App Authentication

The SDK automatically picks up the `NOMI_TOKEN` environment variable if not provided explicitly.

```typescript
import { NomiClient } from '@itfin/nomi-sdk';

const client = new NomiClient({
  authStrategy: 'in-app',
  token: 'YOUR_API_TOKEN', // Optional: defaults to process.env.NOMI_TOKEN
});
```

#### PPT Authentication

```typescript
import { NomiClient } from '@itfin/nomi-sdk';

const client = new NomiClient({
  authStrategy: 'ppt',
  email: 'your-email@example.com',
  pptToken: 'YOUR_PPT_TOKEN'
});
```

### 2. Usage Examples

#### Auto-Pagination with Async Generators

```typescript
async function fetchAllAccounts() {
  // Automatically fetches all pages without manually passing offsets/pages
  for await (const account of client.accounts.getAll({ with: 'totals' })) {
    console.log(`${account.name}: ${account.balance} ${account.currency}`);
  }
}
```

#### Bulk Saving with Chunking

```typescript
async function bulkUpdateProjects() {
  const massiveArray = [ /* ... 500+ projects ... */ ];
  
  // The SDK automatically splits this array into chunks of `defaultLimit` (e.g. 100)
  // and aggregates the IDs from all network requests.
  const { ids } = await client.projects.bulkSave(massiveArray);
  console.log(`Successfully saved ${ids.length} projects!`);
}
```

## Available Domains

- `client.accounts.*`
- `client.projects.*`
- `client.counterparties.*`
- `client.transactions.*`
- `client.nomenclature.*` (Including `categories` and `units`)
- `client.nomenclatureMovements.*`
- `client.propertyBags.*`
