@tammsyr/admin-api-client 1.0.15 → 1.0.17

package/README.md

@@ -1,341 +1,341 @@
-# @tammsyr/admin-api-client
-
-TypeScript client for TAMM Admin Service API. Auto-generated from OpenAPI specification using [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api).
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Requirements](#requirements)
-- [Quick Start](#quick-start)
-- [API Reference](#api-reference)
-- [Authentication](#authentication)
-- [Configuration](#configuration)
-- [Error Handling](#error-handling)
-- [Types](#types)
-- [Generation & Publishing](#generation--publishing)
-  - [Prerequisites](#prerequisites)
-  - [Generating the Client](#generating-the-client)
-  - [Publishing to npm](#publishing-to-npm)
-  - [npm Authentication](#npm-authentication)
-- [Troubleshooting](#troubleshooting)
-
-## Installation
-
-```bash
-npm install @tammsyr/admin-api-client
-```
-
-**Peer dependency:** This package uses [axios](https://www.npmjs.com/package/axios) for HTTP requests. If your project doesn't already have it:
-
-```bash
-npm install axios
-```
-
-## Requirements
-
-- Node.js 18+
-- TypeScript 5.x (optional, for type definitions)
-
-## Quick Start
-
-```typescript
-import { AdminApiClient } from '@tammsyr/admin-api-client';
-
-async function main() {
-  const adminClient = new AdminApiClient({
-    baseURL: 'http://localhost:3006/admin/v1',
-  });
-
-  const loginResponse = await adminClient.auth.login({
-    email: 'admin@example.com',
-    password: 'password123',
-  });
-
-  adminClient.setToken(loginResponse.data.accessToken);
-
-  const admins = await adminClient.admins.getAll();
-  const roles = await adminClient.roles.getAll();
-}
-
-main().catch(console.error);
-```
-
-**Important:** The `baseURL` must include the `/admin/v1` path. The Admin Service serves all routes under that prefix.
-
-## API Reference
-
-### Available APIs
-
-| Property                       | Description                             |
-| ------------------------------ | --------------------------------------- |
-| `adminClient.auth`             | Authentication (login, logout, refresh) |
-| `adminClient.admins`           | Admin user management                   |
-| `adminClient.roles`            | Role management                         |
-| `adminClient.permissions`      | Permission management                   |
-| `adminClient.agents`           | Agent management                        |
-| `adminClient.agentBranches`    | Agent branch management                 |
-| `adminClient.agentSettlements` | Agent settlement management             |
-| `adminClient.kyc`              | KYC management                          |
-| `adminClient.notifications`    | Notification management                 |
-| `adminClient.activityLogs`     | Activity log queries                    |
-| `adminClient.seed`             | Database seeding (dev only)             |
-
-## Authentication
-
-```typescript
-// Set token during initialization
-const client = new AdminApiClient({
-  baseURL: 'http://localhost:3006/admin/v1',
-  token: 'your-token',
-});
-
-// Or set token after login
-const res = await client.auth.login({ email, password });
-client.setToken(res.data.accessToken);
-
-// Update token later
-client.setToken('new-token');
-
-// Clear token
-client.clearToken();
-```
-
-### Using Individual API Classes
-
-```typescript
-import { Admins, HttpClient } from '@tammsyr/admin-api-client';
-
-const httpClient = new HttpClient({
-  baseURL: 'http://localhost:3006/admin/v1',
-  securityWorker: async (authData) => {
-    const token = authData?.token ?? localStorage.getItem('admin_token');
-    if (token) {
-      return { headers: { Authorization: `Bearer ${token}` } };
-    }
-  },
-  secure: true,
-});
-
-const adminsApi = new Admins(httpClient);
-const allAdmins = await adminsApi.getAll();
-```
-
-## Configuration
-
-```typescript
-const client = new AdminApiClient({
-  baseURL: 'http://localhost:3006/admin/v1',
-  timeout: 10000,
-  token: 'your-jwt-token',
-  headers: {
-    'X-Custom-Header': 'value',
-  },
-});
-```
-
-| Option    | Type                     | Default                            | Description                                       |
-| --------- | ------------------------ | ---------------------------------- | ------------------------------------------------- |
-| `baseURL` | `string`                 | `'http://localhost:3006/admin/v1'` | Admin Service base URL (must include `/admin/v1`) |
-| `timeout` | `number`                 | `10000`                            | Request timeout in ms                             |
-| `token`   | `string`                 | —                                  | JWT token for authenticated requests              |
-| `headers` | `Record<string, string>` | `{}`                               | Additional request headers                        |
-
-**Environment-based URL example:**
-
-```typescript
-const baseURL = process.env.NODE_ENV === 'production' ? 'https://admin.tamm.com/admin/v1' : 'http://localhost:3006/admin/v1';
-
-const client = new AdminApiClient({ baseURL });
-```
-
-## Error Handling
-
-```typescript
-try {
-  const response = await adminClient.admins.create(adminData);
-  console.log('Success:', response.data);
-} catch (err: any) {
-  if (err.response) {
-    console.error('API Error:', err.response.status, err.response.data);
-  } else {
-    console.error('Network Error:', err.message);
-  }
-}
-```
-
-## Types
-
-All request/response types are exported:
-
-```typescript
-import type {
-  AdminLoginRequestDto,
-  AdminUserDto,
-  AdminRoleDto,
-  AdminPermissionDto,
-  LoginData,
-  // ... other types
-} from '@tammsyr/admin-api-client';
-```
-
----
-
-## Generation & Publishing
-
-This section covers how to regenerate the client when the Admin Service API changes and how to publish a new version to npm.
-
-### Prerequisites
-
-All commands are run from the **monorepo root** (`tamm-microservices/`).
-
-| Tool                     | Purpose                 |
-| ------------------------ | ----------------------- |
-| `swagger-typescript-api` | Generates the TS client |
-| `typescript`             | Compiles for publishing |
-| `npm` account            | Required for publishing |
-
-Both tools are already listed in the root `devDependencies` — just run `npm install`.
-
-### Generating the Client
-
-#### Step 1 — Start the Admin Service
-
-The OpenAPI spec is fetched from the running server's Swagger endpoint at `http://localhost:3006/admin/docs-json`.
-
-```bash
-npm run start:admin
-```
-
-Wait until the service is fully started before proceeding.
-
-#### Step 2 — Fetch the OpenAPI Spec
-
-```bash
-npm run generate:admin-openapi-spec
-```
-
-This saves the spec to `admin-openapi.json` at the monorepo root. You can also set a custom URL via the `ADMIN_SERVICE_URL` environment variable.
-
-#### Step 3 — Generate the TypeScript Client
-
-```bash
-npm run generate:admin-typescript-client
-```
-
-Output is written to `generated/admin-client/`.
-
-#### Combined Shortcut
-
-Run Steps 2 and 3 together (Admin Service must already be running):
-
-```bash
-npm run generate:admin-typescript-client:full
-```
-
-#### Review Changes
-
-```bash
-git diff admin-openapi.json
-git diff generated/admin-client/
-```
-
-### Publishing to npm
-
-#### 1. Bump the version and publish
-
-```bash
-npm run publish:admin-client -- --version=<new-version>
-```
-
-The script will:
-
-1. Update the version in `generated/admin-client/package.json`
-2. Run `tsc` to build the `dist/` folder
-3. Publish `@tammsyr/admin-api-client` to the public npm registry
-
-#### 2. Dry-run first (recommended)
-
-Verify everything looks correct without actually publishing:
-
-```bash
-npm run publish:admin-client -- --dry-run
-```
-
-#### 3. Version and publish together
-
-```bash
-npm run publish:admin-client -- --version=1.0.6 --dry-run   # verify
-npm run publish:admin-client -- --version=1.0.6              # publish for real
-```
-
-### npm Authentication
-
-You must be authenticated with npm to publish. There are two options:
-
-#### Option A — npm login (interactive)
-
-```bash
-npm login
-```
-
-If 2FA is enabled on your account, you'll be prompted for a one-time password.
-
-#### Option B — Access token (CI / non-interactive)
-
-1. Create a **Granular Access Token** on [npmjs.com](https://www.npmjs.com) with publish permissions for `@tammsyr/*`
-2. Set it as an environment variable before publishing:
-
-```powershell
-# PowerShell
-$env:NPM_TOKEN="YOUR_TOKEN_HERE"
-npm run publish:admin-client -- --version=1.0.6
-```
-
-```bash
-# Bash / Linux / macOS
-export NPM_TOKEN="YOUR_TOKEN_HERE"
-npm run publish:admin-client -- --version=1.0.6
-```
-
-See [`docs/npm-2fa-setup.md`](../../docs/npm-2fa-setup.md) for detailed 2FA and token configuration.
-
-### Full End-to-End Example
-
-```bash
-# 1. Start the Admin Service
-npm run start:admin
-
-# 2. (in another terminal) Generate the client
-npm run generate:admin-typescript-client:full
-
-# 3. Review changes
-git diff admin-openapi.json generated/admin-client/
-
-# 4. Dry-run publish
-npm run publish:admin-client -- --version=1.0.6 --dry-run
-
-# 5. Publish for real
-npm run publish:admin-client -- --version=1.0.6
-
-# 6. Commit
-git add admin-openapi.json generated/admin-client/
-git commit -m "chore: regenerate and publish admin client v1.0.6"
-```
-
-## Troubleshooting
-
-| Problem                              | Solution                                                                                                |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `generate:admin-openapi-spec` fails  | Make sure the Admin Service is running (`npm run start:admin`) and reachable at `http://localhost:3006` |
-| Generated code has TypeScript errors | Verify the OpenAPI spec is valid — check Swagger UI at `http://localhost:3006/admin/docs`               |
-| `403 Forbidden` on publish           | Check npm auth (`npm whoami`), org membership (`npm org ls tammsyr`), and 2FA/token setup               |
-| `Two-factor authentication required` | Enable 2FA on npmjs.com or use a granular access token with bypass-2FA enabled                          |
-| Version conflict on publish          | Ensure the `--version` you're publishing doesn't already exist on the registry                          |
-
-## Versioning
-
-This package follows [semantic versioning](https://semver.org/).
-
-## License
-
-MIT
+# @tammsyr/admin-api-client
+
+TypeScript client for TAMM Admin Service API. Auto-generated from OpenAPI specification using [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Authentication](#authentication)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Types](#types)
+- [Generation & Publishing](#generation--publishing)
+  - [Prerequisites](#prerequisites)
+  - [Generating the Client](#generating-the-client)
+  - [Publishing to npm](#publishing-to-npm)
+  - [npm Authentication](#npm-authentication)
+- [Troubleshooting](#troubleshooting)
+
+## Installation
+
+```bash
+npm install @tammsyr/admin-api-client
+```
+
+**Peer dependency:** This package uses [axios](https://www.npmjs.com/package/axios) for HTTP requests. If your project doesn't already have it:
+
+```bash
+npm install axios
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.x (optional, for type definitions)
+
+## Quick Start
+
+```typescript
+import { AdminApiClient } from '@tammsyr/admin-api-client';
+
+async function main() {
+  const adminClient = new AdminApiClient({
+    baseURL: 'http://localhost:3006/admin/v1',
+  });
+
+  const loginResponse = await adminClient.auth.login({
+    email: 'admin@example.com',
+    password: 'password123',
+  });
+
+  adminClient.setToken(loginResponse.data.accessToken);
+
+  const admins = await adminClient.admins.getAll();
+  const roles = await adminClient.roles.getAll();
+}
+
+main().catch(console.error);
+```
+
+**Important:** The `baseURL` must include the `/admin/v1` path. The Admin Service serves all routes under that prefix.
+
+## API Reference
+
+### Available APIs
+
+| Property                       | Description                             |
+| ------------------------------ | --------------------------------------- |
+| `adminClient.auth`             | Authentication (login, logout, refresh) |
+| `adminClient.admins`           | Admin user management                   |
+| `adminClient.roles`            | Role management                         |
+| `adminClient.permissions`      | Permission management                   |
+| `adminClient.agents`           | Agent management                        |
+| `adminClient.agentBranches`    | Agent branch management                 |
+| `adminClient.agentSettlements` | Agent settlement management             |
+| `adminClient.kyc`              | KYC management                          |
+| `adminClient.notifications`    | Notification management                 |
+| `adminClient.activityLogs`     | Activity log queries                    |
+| `adminClient.seed`             | Database seeding (dev only)             |
+
+## Authentication
+
+```typescript
+// Set token during initialization
+const client = new AdminApiClient({
+  baseURL: 'http://localhost:3006/admin/v1',
+  token: 'your-token',
+});
+
+// Or set token after login
+const res = await client.auth.login({ email, password });
+client.setToken(res.data.accessToken);
+
+// Update token later
+client.setToken('new-token');
+
+// Clear token
+client.clearToken();
+```
+
+### Using Individual API Classes
+
+```typescript
+import { Admins, HttpClient } from '@tammsyr/admin-api-client';
+
+const httpClient = new HttpClient({
+  baseURL: 'http://localhost:3006/admin/v1',
+  securityWorker: async (authData) => {
+    const token = authData?.token ?? localStorage.getItem('admin_token');
+    if (token) {
+      return { headers: { Authorization: `Bearer ${token}` } };
+    }
+  },
+  secure: true,
+});
+
+const adminsApi = new Admins(httpClient);
+const allAdmins = await adminsApi.getAll();
+```
+
+## Configuration
+
+```typescript
+const client = new AdminApiClient({
+  baseURL: 'http://localhost:3006/admin/v1',
+  timeout: 10000,
+  token: 'your-jwt-token',
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
+```
+
+| Option    | Type                     | Default                            | Description                                       |
+| --------- | ------------------------ | ---------------------------------- | ------------------------------------------------- |
+| `baseURL` | `string`                 | `'http://localhost:3006/admin/v1'` | Admin Service base URL (must include `/admin/v1`) |
+| `timeout` | `number`                 | `10000`                            | Request timeout in ms                             |
+| `token`   | `string`                 | —                                  | JWT token for authenticated requests              |
+| `headers` | `Record<string, string>` | `{}`                               | Additional request headers                        |
+
+**Environment-based URL example:**
+
+```typescript
+const baseURL = process.env.NODE_ENV === 'production' ? 'https://admin.tamm.com/admin/v1' : 'http://localhost:3006/admin/v1';
+
+const client = new AdminApiClient({ baseURL });
+```
+
+## Error Handling
+
+```typescript
+try {
+  const response = await adminClient.admins.create(adminData);
+  console.log('Success:', response.data);
+} catch (err: any) {
+  if (err.response) {
+    console.error('API Error:', err.response.status, err.response.data);
+  } else {
+    console.error('Network Error:', err.message);
+  }
+}
+```
+
+## Types
+
+All request/response types are exported:
+
+```typescript
+import type {
+  AdminLoginRequestDto,
+  AdminUserDto,
+  AdminRoleDto,
+  AdminPermissionDto,
+  LoginData,
+  // ... other types
+} from '@tammsyr/admin-api-client';
+```
+
+---
+
+## Generation & Publishing
+
+This section covers how to regenerate the client when the Admin Service API changes and how to publish a new version to npm.
+
+### Prerequisites
+
+All commands are run from the **monorepo root** (`tamm-microservices/`).
+
+| Tool                     | Purpose                 |
+| ------------------------ | ----------------------- |
+| `swagger-typescript-api` | Generates the TS client |
+| `typescript`             | Compiles for publishing |
+| `npm` account            | Required for publishing |
+
+Both tools are already listed in the root `devDependencies` — just run `npm install`.
+
+### Generating the Client
+
+#### Step 1 — Start the Admin Service
+
+The OpenAPI spec is fetched from the running server's Swagger endpoint at `http://localhost:3006/admin/docs-json`.
+
+```bash
+npm run start:admin
+```
+
+Wait until the service is fully started before proceeding.
+
+#### Step 2 — Fetch the OpenAPI Spec
+
+```bash
+npm run generate:admin-openapi-spec
+```
+
+This saves the spec to `admin-openapi.json` at the monorepo root. You can also set a custom URL via the `ADMIN_SERVICE_URL` environment variable.
+
+#### Step 3 — Generate the TypeScript Client
+
+```bash
+npm run generate:admin-typescript-client
+```
+
+Output is written to `generated/admin-client/`.
+
+#### Combined Shortcut
+
+Run Steps 2 and 3 together (Admin Service must already be running):
+
+```bash
+npm run generate:admin-typescript-client:full
+```
+
+#### Review Changes
+
+```bash
+git diff admin-openapi.json
+git diff generated/admin-client/
+```
+
+### Publishing to npm
+
+#### 1. Bump the version and publish
+
+```bash
+npm run publish:admin-client -- --version=<new-version>
+```
+
+The script will:
+
+1. Update the version in `generated/admin-client/package.json`
+2. Run `tsc` to build the `dist/` folder
+3. Publish `@tammsyr/admin-api-client` to the public npm registry
+
+#### 2. Dry-run first (recommended)
+
+Verify everything looks correct without actually publishing:
+
+```bash
+npm run publish:admin-client -- --dry-run
+```
+
+#### 3. Version and publish together
+
+```bash
+npm run publish:admin-client -- --version=1.0.6 --dry-run   # verify
+npm run publish:admin-client -- --version=1.0.6              # publish for real
+```
+
+### npm Authentication
+
+You must be authenticated with npm to publish. There are two options:
+
+#### Option A — npm login (interactive)
+
+```bash
+npm login
+```
+
+If 2FA is enabled on your account, you'll be prompted for a one-time password.
+
+#### Option B — Access token (CI / non-interactive)
+
+1. Create a **Granular Access Token** on [npmjs.com](https://www.npmjs.com) with publish permissions for `@tammsyr/*`
+2. Set it as an environment variable before publishing:
+
+```powershell
+# PowerShell
+$env:NPM_TOKEN="YOUR_TOKEN_HERE"
+npm run publish:admin-client -- --version=1.0.6
+```
+
+```bash
+# Bash / Linux / macOS
+export NPM_TOKEN="YOUR_TOKEN_HERE"
+npm run publish:admin-client -- --version=1.0.6
+```
+
+See [`docs/npm-2fa-setup.md`](../../docs/npm-2fa-setup.md) for detailed 2FA and token configuration.
+
+### Full End-to-End Example
+
+```bash
+# 1. Start the Admin Service
+npm run start:admin
+
+# 2. (in another terminal) Generate the client
+npm run generate:admin-typescript-client:full
+
+# 3. Review changes
+git diff admin-openapi.json generated/admin-client/
+
+# 4. Dry-run publish
+npm run publish:admin-client -- --version=1.0.6 --dry-run
+
+# 5. Publish for real
+npm run publish:admin-client -- --version=1.0.6
+
+# 6. Commit
+git add admin-openapi.json generated/admin-client/
+git commit -m "chore: regenerate and publish admin client v1.0.6"
+```
+
+## Troubleshooting
+
+| Problem                              | Solution                                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `generate:admin-openapi-spec` fails  | Make sure the Admin Service is running (`npm run start:admin`) and reachable at `http://localhost:3006` |
+| Generated code has TypeScript errors | Verify the OpenAPI spec is valid — check Swagger UI at `http://localhost:3006/admin/docs`               |
+| `403 Forbidden` on publish           | Check npm auth (`npm whoami`), org membership (`npm org ls tammsyr`), and 2FA/token setup               |
+| `Two-factor authentication required` | Enable 2FA on npmjs.com or use a granular access token with bypass-2FA enabled                          |
+| Version conflict on publish          | Ensure the `--version` you're publishing doesn't already exist on the registry                          |
+
+## Versioning
+
+This package follows [semantic versioning](https://semver.org/).
+
+## License
+
+MIT