@tammsyr/admin-api-client

TypeScript client for TAMM Admin Service API. Auto-generated from OpenAPI specification using swagger-typescript-api.

Table of Contents

• Installation
• Requirements
• Quick Start
• API Reference
• Authentication
• Configuration
• Error Handling
• Types
• Generation & Publishing
  • Prerequisites
  • Generating the Client
  • Publishing to npm
  • npm Authentication
• Troubleshooting

Installation

npm install @tammsyr/admin-api-client

Peer dependency: This package uses axios for HTTP requests. If your project doesn't already have it:

npm install axios

Requirements

• Node.js 18+
• TypeScript 5.x (optional, for type definitions)

Quick Start

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: '[email protected]',
    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.agentSettlements | Agent settlement management | | adminClient.kyc | KYC management | | adminClient.notifications | Notification management | | adminClient.activityLogs | Activity log queries | | adminClient.seed | Database seeding (dev only) |

Authentication

// 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

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

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:

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

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:

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.

npm run start:admin

Wait until the service is fully started before proceeding.

Step 2 — Fetch the OpenAPI Spec

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

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):

npm run generate:admin-typescript-client:full

Review Changes

git diff admin-openapi.json
git diff generated/admin-client/

Publishing to npm

1. Bump the version and publish

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:

npm run publish:admin-client -- --dry-run

3. Version and publish together

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)

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 with publish permissions for @tammsyr/*
2. Set it as an environment variable before publishing:

# PowerShell
$env:NPM_TOKEN="YOUR_TOKEN_HERE"
npm run publish:admin-client -- --version=1.0.6

# Bash / Linux / macOS
export NPM_TOKEN="YOUR_TOKEN_HERE"
npm run publish:admin-client -- --version=1.0.6

See docs/npm-2fa-setup.md for detailed 2FA and token configuration.

Full End-to-End Example

# 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.

License

MIT