# @smartytalent/api-client

[![npm version](https://img.shields.io/npm/v/@smartytalent/api-client.svg)](https://www.npmjs.com/package/@smartytalent/api-client)
[![npm downloads](https://img.shields.io/npm/dm/@smartytalent/api-client.svg)](https://www.npmjs.com/package/@smartytalent/api-client)

TypeScript client for the **SmartyTalent** recruitment API, auto-generated from the OpenAPI spec using [`openapi-generator-cli`](https://openapi-generator.tech/) with the `typescript-fetch` template.

Fully typed requests, responses, and models. Works in Node.js 18+, modern browsers, and edge runtimes that support the Fetch API.

## Install

```bash
npm install @smartytalent/api-client
# or
pnpm add @smartytalent/api-client
# or
yarn add @smartytalent/api-client
```

## Quick start

```ts
import { Configuration, TenantsApi } from '@smartytalent/api-client'

const config = new Configuration({
  basePath: 'https://api.smartytalent.example.com',
  apiKey: `Bearer ${process.env.SMARTYTALENT_TOKEN}`,
})

const tenantsApi = new TenantsApi(config)

const tenants = await tenantsApi.listTenants({ filterStatus: 'active' })
console.log(tenants)
```

## Authentication

The API uses **Bearer token** auth. Pass the full `Authorization` header value (including the `Bearer ` prefix) as `apiKey`:

```ts
const config = new Configuration({
  basePath: 'https://api.smartytalent.example.com',
  apiKey: `Bearer ${accessToken}`,
})
```

`apiKey` also accepts a function for dynamic token resolution (useful for refresh flows):

```ts
const config = new Configuration({
  basePath: '...',
  apiKey: (name) => `Bearer ${getFreshToken()}`,
})
```

## API surface

The client exposes one class per API tag. Available API classes include:

`ActionsApi`, `AdsApi`, `ApikeysApi`, `AssessmentsApi`, `BrowsersApi`, `CallsApi`, `CandidatesApi`, `ChatsApi`, `ConversationsApi`, `EmailsApi`, `FilesApi`, `FindersApi`, `FormsApi`, `JobsApi`, `LinksApi`, `MeetingsApi`, `NotesApi`, `NotificationsApi`, `OperationsApi`, `PersonasApi`, `ReportsApi`, `RolesApi`, `RunsApi`, `TalentsApi`, `TenantsApi`, `TranslationsApi`, `TriggersApi`, `UsersApi`, `WebhooksApi`, `WorkflowsApi`.

All request/response DTOs are exported as TypeScript interfaces from the package root.

## Deep imports

Tree-shakeable deep imports are supported via the `exports` map:

```ts
import { JobsApi } from '@smartytalent/api-client/apis/JobsApi'
import type { Tenant } from '@smartytalent/api-client/models/Tenant'
```

## Configuration options

`Configuration` accepts:

| Option           | Type                                      | Description                                     |
| ---------------- | ----------------------------------------- | ----------------------------------------------- |
| `basePath`       | `string`                                  | API base URL                                    |
| `apiKey`         | `string \| (name: string) => string`      | `Authorization` header value                    |
| `accessToken`    | `string \| (name, scopes) => string`      | OAuth2 bearer token                             |
| `fetchApi`       | `typeof fetch`                            | Custom fetch implementation                     |
| `middleware`     | `Middleware[]`                            | Request/response interceptors                   |
| `headers`        | `Record<string, string>`                  | Default headers on every request                |
| `queryParamsStringify` | `(params) => string`                | Custom query-string serializer                  |
| `credentials`    | `RequestCredentials`                      | CORS credentials mode                           |

### Middleware

```ts
const config = new Configuration({
  basePath: '...',
  middleware: [{
    pre: async (ctx) => {
      console.log(ctx.url, ctx.init)
    },
    post: async (ctx) => {
      if (!ctx.response.ok) console.error('API error', ctx.response.status)
    },
  }],
})
```

## Error handling

Non-2xx responses throw a `ResponseError` (also exported from the package) that exposes the underlying `Response`:

```ts
import { ResponseError } from '@smartytalent/api-client'

try {
  await tenantsApi.getTenant({ id: '...' })
} catch (err) {
  if (err instanceof ResponseError) {
    console.error(err.response.status, await err.response.text())
  }
  throw err
}
```

## Versioning

This package is auto-published on every update to the OpenAPI spec. Version numbers are synchronized across all `@smartytalent/*` packages so you can safely pin them to the same version.

## License

Licensed under the [Apache License, Version 2.0](./LICENSE).

Copyright © 2026 SmartyTalent (SmartyMeet sp. z o.o.)