HeadHunter API SDK for Node.js

In Development

A lightweight TypeScript/JavaScript SDK for HeadHunter API.

📦 Installation

npm install node-hhru-api

or with yarn:

yarn add node-hhru-api

⚡ Quick Start

import { getUserToken, getResume, setHttpConfig } from 'node-hhru-api'

setHttpConfig({
  locale: 'RU',
  host: 'hh.ru',
  userAgent: 'MyApp/1.0 ([email protected])',
})

const userTokenResponse = await getUserToken(
  clientId,
  clientSecret,
  code // received from OAuth redirect
)

const resume = await getResume(userTokenResponse.access_token)
console.log(resume.id)

🛠 Usage

You can import methods in two ways:

1. Direct imports (tree-shaking friendly)
2. Grouped namespaces (Common, Applicant, Employer)

1. Direct Imports

import { getUserToken, getResume } from 'node-hhru-api'

const userTokenResponse = await getUserToken(
  clientId,
  clientSecret,
  code // received from OAuth redirect
)

const resume = await getResume(userTokenResponse.access_token)
console.log(resume.id)

2. Using Namespaces

import { Common, Employer } from 'node-hhru-api'

const userTokenResponse = await Common.getUserToken(
  clientId,
  clientSecret,
  code // received from OAuth redirect
)

const me = await Employer.getCurrentUser(userTokenResponse.access_token)
console.log(me.email)

🔑 Authentication Flows

Application Token (Client Credentials)

import { getAppToken } from 'node-hhru-api'

const appTokenResponse = await getAppToken(clientId, clientSecret)
console.log(appTokenResponse.access_token)

User Token (Authorization Code)

import { getUserToken } from 'node-hhru-api'

const userTokenResponse = await getUserToken(
  clientId,
  clientSecret,
  code, // received from OAuth redirect
  redirectUri // optional
)
console.log(userTokenResponse.access_token)
console.log(userTokenResponse.refresh_token)

Refresh User Token

import { refreshUserToken } from 'node-hhru-api'

const refreshed = await refreshUserToken(clientId, clientSecret, refreshToken)
console.log(refreshed.access_token)

⚙️ Configuration

You can customize HTTP client (headers, locale, etc.):

import { setHttpConfig } from 'node-hhru-api'

setHttpConfig({
  locale: 'RU',
  host: 'hh.ru',
  userAgent: 'MyApp/1.0 ([email protected])',
}) // Use this at the beginning of your code

⚠️ HeadHunter requires a valid HH-User-Agent. It should be in the format:

AppName/Version ([email protected])

📂 Types

All response objects are fully typed:

import {
  Resume,
  CurrentUser,
  AppTokenResponse,
  UserTokenResponse,
} from 'node-hhru-api'

🧪 Tests

The project includes tests with Vitest:

Before running, make sure to set environment variables:

export HH_CLIENT_ID=your_client_id
export HH_CLIENT_SECRET=your_client_secret
export HH_AUTH_CODE=your_auth_code
export HH_REDIRECT_URI=your_redirect_uri

npm run test

📜 License

MIT © 2025 Zoomish