@sargonpiraev/hh-api-client 1.0.0

package/README.md

@@ -0,0 +1,261 @@
+# HeadHunter API Client
+
+A TypeScript client for the HeadHunter API, generated from the official OpenAPI specification.
+
+## Features
+
+- 🔥 **TypeScript first** - Full type safety with generated types
+- 🚀 **Modern SDK** - Built with `@hey-api/openapi-ts`
+- 📝 **Complete API coverage** - All HeadHunter API endpoints
+- 🛡️ **Built-in validation** - Request/response validation
+- 🎯 **Tree-shakeable** - Import only what you need
+- 📚 **Well documented** - JSDoc comments for all methods
+
+## Installation
+
+```bash
+npm install hh-api-client
+```
+
+## Quick Start
+
+```typescript
+import { createHeadHunterClient, getVacancies, getAreas, type GetVacanciesData } from 'hh-api-client'
+
+// Create a configured client
+const client = createHeadHunterClient({
+  userAgent: 'MyApp/1.0.0 (contact@example.com)',
+  accessToken: 'your-access-token', // optional
+})
+
+// Search for vacancies
+const searchParams: GetVacanciesData = {
+  query: {
+    text: 'JavaScript developer',
+    area: '1', // Moscow
+    per_page: 50,
+  },
+}
+
+const vacancies = await getVacancies({
+  client,
+  ...searchParams,
+})
+
+console.log(`Found ${vacancies.data.found} vacancies`)
+
+// Get dictionaries
+const areas = await getAreas({ client })
+console.log('Available areas:', areas.data)
+```
+
+## Usage Examples
+
+### Search Vacancies
+
+```typescript
+import { getVacancies, type GetVacanciesData } from 'hh-api-client'
+
+const searchParams: GetVacanciesData = {
+  query: {
+    text: 'Frontend Developer',
+    area: '1', // Moscow
+    professional_role: '96', // Developer role
+    experience: 'between1And3',
+    employment: 'full',
+    schedule: 'remote',
+    salary_from: 100000,
+    currency: 'RUR',
+    only_with_salary: true,
+  },
+}
+
+const result = await getVacancies({ client, ...searchParams })
+```
+
+### Get Vacancy Details
+
+```typescript
+import { getVacancy } from 'hh-api-client'
+
+const vacancy = await getVacancy({
+  client,
+  path: { vacancy_id: '12345' },
+})
+
+console.log(vacancy.data.name)
+console.log(vacancy.data.description)
+```
+
+### Apply to Vacancy
+
+```typescript
+import { applyToVacancy } from 'hh-api-client'
+
+await applyToVacancy({
+  client,
+  path: { vacancy_id: '12345' },
+  body: {
+    resume_id: 'resume-id',
+    message: 'I am interested in this position...',
+  },
+})
+```
+
+### Work with Dictionaries
+
+```typescript
+import { getAreas, getIndustries, getSkills, getProfessionalRolesDictionary } from 'hh-api-client'
+
+// Get all areas (cities/regions)
+const areas = await getAreas({ client })
+
+// Get industries
+const industries = await getIndustries({ client })
+
+// Get skills
+const skills = await getSkills({ client })
+
+// Get professional roles
+const roles = await getProfessionalRolesDictionary({ client })
+```
+
+### User Information
+
+```typescript
+import { getCurrentUserInfo, editCurrentUserInfo } from 'hh-api-client'
+
+// Get current user info
+const user = await getCurrentUserInfo({ client })
+
+// Update user info
+await editCurrentUserInfo({
+  client,
+  body: {
+    first_name: 'John',
+    last_name: 'Doe',
+    email: 'john.doe@example.com',
+  },
+})
+```
+
+## Configuration
+
+### Required User-Agent
+
+HeadHunter API requires a specific User-Agent format:
+
+```
+ApplicationName/Version (contact@example.com)
+```
+
+Example:
+
+```typescript
+const client = createHeadHunterClient({
+  userAgent: 'JobSearchApp/1.0.0 (support@jobsearch.com)',
+})
+```
+
+### Authentication
+
+For protected endpoints, provide an access token:
+
+```typescript
+const client = createHeadHunterClient({
+  userAgent: 'MyApp/1.0.0 (contact@example.com)',
+  accessToken: 'your-oauth-token',
+})
+```
+
+### Custom Base URL
+
+For testing or custom environments:
+
+```typescript
+const client = createHeadHunterClient({
+  userAgent: 'MyApp/1.0.0 (contact@example.com)',
+  baseURL: 'https://api.hh.ru', // default
+})
+```
+
+## API Reference
+
+### Most Used Functions
+
+- `getVacancies()` - Search vacancies
+- `getVacancy()` - Get vacancy details
+- `getAreas()` - Get areas/cities
+- `getIndustries()` - Get industries
+- `getCurrentUserInfo()` - Get user info
+- `applyToVacancy()` - Apply to vacancy
+
+### All Available Functions
+
+The client exports all generated SDK functions. See the [HeadHunter API documentation](https://api.hh.ru/openapi/redoc) for complete reference.
+
+```typescript
+// Import everything
+import * as HHApi from 'hh-api-client'
+
+// Or import specific functions
+import {
+  getVacancies,
+  getNegotiations,
+  createResume,
+  // ... etc
+} from 'hh-api-client'
+```
+
+## TypeScript Support
+
+Full TypeScript support with generated types:
+
+```typescript
+import type { GetVacanciesData, GetVacanciesResponses, Vacancy, Area, Industry } from 'hh-api-client'
+
+const handleVacancy = (vacancy: Vacancy) => {
+  console.log(vacancy.name)
+  console.log(vacancy.salary?.from)
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await getVacancies({ client, query: { text: 'Developer' } })
+  console.log(result.data)
+} catch (error) {
+  if (error.status === 400) {
+    console.error('Bad request:', error.data)
+  } else if (error.status === 403) {
+    console.error('Forbidden:', error.data)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Generate types from OpenAPI spec
+npm run openapi-ts
+
+# Build
+npm run build
+
+# Test
+npm run test
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT

package/build/src/generated/client/client.d.ts

@@ -0,0 +1,2 @@
+import type { Client, Config } from './types.js';
+export declare const createClient: (config?: Config) => Client;

package/build/src/generated/client/client.js

@@ -0,0 +1,143 @@
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from './utils.js';
+export const createClient = (config = {}) => {
+    let _config = mergeConfigs(createConfig(), config);
+    const getConfig = () => ({ ..._config });
+    const setConfig = (config) => {
+        _config = mergeConfigs(_config, config);
+        return getConfig();
+    };
+    const interceptors = createInterceptors();
+    const request = async (options) => {
+        const opts = {
+            ..._config,
+            ...options,
+            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+            headers: mergeHeaders(_config.headers, options.headers),
+        };
+        if (opts.security) {
+            await setAuthParams({
+                ...opts,
+                security: opts.security,
+            });
+        }
+        if (opts.requestValidator) {
+            await opts.requestValidator(opts);
+        }
+        if (opts.body && opts.bodySerializer) {
+            opts.body = opts.bodySerializer(opts.body);
+        }
+        // remove Content-Type header if body is empty to avoid sending invalid requests
+        if (opts.body === undefined || opts.body === '') {
+            opts.headers.delete('Content-Type');
+        }
+        const url = buildUrl(opts);
+        const requestInit = {
+            redirect: 'follow',
+            ...opts,
+        };
+        let request = new Request(url, requestInit);
+        for (const fn of interceptors.request._fns) {
+            if (fn) {
+                request = await fn(request, opts);
+            }
+        }
+        // fetch must be assigned here, otherwise it would throw the error:
+        // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+        const _fetch = opts.fetch;
+        let response = await _fetch(request);
+        for (const fn of interceptors.response._fns) {
+            if (fn) {
+                response = await fn(response, request, opts);
+            }
+        }
+        const result = {
+            request,
+            response,
+        };
+        if (response.ok) {
+            if (response.status === 204 ||
+                response.headers.get('Content-Length') === '0') {
+                return opts.responseStyle === 'data'
+                    ? {}
+                    : {
+                        data: {},
+                        ...result,
+                    };
+            }
+            const parseAs = (opts.parseAs === 'auto'
+                ? getParseAs(response.headers.get('Content-Type'))
+                : opts.parseAs) ?? 'json';
+            let data;
+            switch (parseAs) {
+                case 'arrayBuffer':
+                case 'blob':
+                case 'formData':
+                case 'json':
+                case 'text':
+                    data = await response[parseAs]();
+                    break;
+                case 'stream':
+                    return opts.responseStyle === 'data'
+                        ? response.body
+                        : {
+                            data: response.body,
+                            ...result,
+                        };
+            }
+            if (parseAs === 'json') {
+                if (opts.responseValidator) {
+                    await opts.responseValidator(data);
+                }
+                if (opts.responseTransformer) {
+                    data = await opts.responseTransformer(data);
+                }
+            }
+            return opts.responseStyle === 'data'
+                ? data
+                : {
+                    data,
+                    ...result,
+                };
+        }
+        let error = await response.text();
+        try {
+            error = JSON.parse(error);
+        }
+        catch {
+            // noop
+        }
+        let finalError = error;
+        for (const fn of interceptors.error._fns) {
+            if (fn) {
+                finalError = (await fn(error, response, request, opts));
+            }
+        }
+        finalError = finalError || {};
+        if (opts.throwOnError) {
+            throw finalError;
+        }
+        // TODO: we probably want to return error and improve types
+        return opts.responseStyle === 'data'
+            ? undefined
+            : {
+                error: finalError,
+                ...result,
+            };
+    };
+    return {
+        buildUrl,
+        connect: (options) => request({ ...options, method: 'CONNECT' }),
+        delete: (options) => request({ ...options, method: 'DELETE' }),
+        get: (options) => request({ ...options, method: 'GET' }),
+        getConfig,
+        head: (options) => request({ ...options, method: 'HEAD' }),
+        interceptors,
+        options: (options) => request({ ...options, method: 'OPTIONS' }),
+        patch: (options) => request({ ...options, method: 'PATCH' }),
+        post: (options) => request({ ...options, method: 'POST' }),
+        put: (options) => request({ ...options, method: 'PUT' }),
+        request,
+        setConfig,
+        trace: (options) => request({ ...options, method: 'TRACE' }),
+    };
+};

package/build/src/generated/client/index.d.ts

@@ -0,0 +1,7 @@
+export type { Auth } from '../core/auth.js';
+export type { QuerySerializerOptions } from '../core/bodySerializer.js';
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.js';
+export { buildClientParams } from '../core/params.js';
+export { createClient } from './client.js';
+export type { Client, ClientOptions, Config, CreateClientConfig, Options, OptionsLegacyParser, RequestOptions, RequestResult, ResponseStyle, TDataShape, } from './types.js';
+export { createConfig, mergeHeaders } from './utils.js';

package/build/src/generated/client/index.js

@@ -0,0 +1,4 @@
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.js';
+export { buildClientParams } from '../core/params.js';
+export { createClient } from './client.js';
+export { createConfig, mergeHeaders } from './utils.js';

package/build/src/generated/client/types.d.ts

@@ -0,0 +1,119 @@
+import type { Auth } from '../core/auth.js';
+import type { Client as CoreClient, Config as CoreConfig } from '../core/types.js';
+import type { Middleware } from './utils.js';
+export type ResponseStyle = 'data' | 'fields';
+export interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, CoreConfig {
+    /**
+     * Base URL for all requests made by this client.
+     */
+    baseUrl?: T['baseUrl'];
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: (request: Request) => ReturnType<typeof fetch>;
+    /**
+     * Please don't use the Fetch client for Next.js applications. The `next`
+     * options won't have any effect.
+     *
+     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
+     */
+    next?: never;
+    /**
+     * Return the response data parsed in a specified format. By default, `auto`
+     * will infer the appropriate method from the `Content-Type` response header.
+     * You can override this behavior with any of the {@link Body} methods.
+     * Select `stream` if you don't want to parse response data at all.
+     *
+     * @default 'auto'
+     */
+    parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
+    /**
+     * Should we return only data or multiple fields (data, error, response, etc.)?
+     *
+     * @default 'fields'
+     */
+    responseStyle?: ResponseStyle;
+    /**
+     * Throw an error instead of returning it in the response?
+     *
+     * @default false
+     */
+    throwOnError?: T['throwOnError'];
+}
+export interface RequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+    responseStyle: TResponseStyle;
+    throwOnError: ThrowOnError;
+}> {
+    /**
+     * Any body that you want to add to your request.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+     */
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Security mechanism(s) to use for the request.
+     */
+    security?: ReadonlyArray<Auth>;
+    url: Url;
+}
+export type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    request: Request;
+    response: Response;
+}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    error: undefined;
+} | {
+    data: undefined;
+    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+}) & {
+    request: Request;
+    response: Response;
+}>;
+export interface ClientOptions {
+    baseUrl?: string;
+    responseStyle?: ResponseStyle;
+    throwOnError?: boolean;
+}
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type BuildUrlFn = <TData extends {
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    url: string;
+}>(options: Pick<TData, 'url'> & Options<TData>) => string;
+export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn> & {
+    interceptors: Middleware<Request, Response, unknown, RequestOptions>;
+};
+/**
+ * The `createClientConfig()` function will be called on client initialization
+ * and the returned object will become the client's initial configuration.
+ *
+ * You may want to initialize your client this way instead of calling
+ * `setConfig()`. This is useful for example if you're using Next.js
+ * to ensure your client always has the correct values.
+ */
+export type CreateClientConfig<T extends ClientOptions = ClientOptions> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
+export interface TDataShape {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+    url: string;
+}
+type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & Omit<TData, 'url'>;
+export type OptionsLegacyParser<TData = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = TData extends {
+    body?: any;
+} ? TData extends {
+    headers?: any;
+} ? OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'body' | 'headers' | 'url'> & TData : OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'body' | 'url'> & TData & Pick<RequestOptions<TResponseStyle, ThrowOnError>, 'headers'> : TData extends {
+    headers?: any;
+} ? OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'headers' | 'url'> & TData & Pick<RequestOptions<TResponseStyle, ThrowOnError>, 'body'> : OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'url'> & TData;
+export {};

package/build/src/generated/client/types.js

@@ -0,0 +1 @@
+export {};

package/build/src/generated/client/utils.d.ts

@@ -0,0 +1,45 @@
+import type { QuerySerializer, QuerySerializerOptions } from '../core/bodySerializer.js';
+import type { Client, ClientOptions, Config, RequestOptions } from './types.js';
+export declare const createQuerySerializer: <T = unknown>({ allowReserved, array, object, }?: QuerySerializerOptions) => (queryParams: T) => string;
+/**
+ * Infers parseAs value from provided Content-Type header.
+ */
+export declare const getParseAs: (contentType: string | null) => Exclude<Config["parseAs"], "auto">;
+export declare const setAuthParams: ({ security, ...options }: Pick<Required<RequestOptions>, "security"> & Pick<RequestOptions, "auth" | "query"> & {
+    headers: Headers;
+}) => Promise<void>;
+export declare const buildUrl: Client['buildUrl'];
+export declare const getUrl: ({ baseUrl, path, query, querySerializer, url: _url, }: {
+    baseUrl?: string;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    querySerializer: QuerySerializer;
+    url: string;
+}) => string;
+export declare const mergeConfigs: (a: Config, b: Config) => Config;
+export declare const mergeHeaders: (...headers: Array<Required<Config>["headers"] | undefined>) => Headers;
+type ErrInterceptor<Err, Res, Req, Options> = (error: Err, response: Res, request: Req, options: Options) => Err | Promise<Err>;
+type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
+type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
+declare class Interceptors<Interceptor> {
+    _fns: (Interceptor | null)[];
+    constructor();
+    clear(): void;
+    getInterceptorIndex(id: number | Interceptor): number;
+    exists(id: number | Interceptor): boolean;
+    eject(id: number | Interceptor): void;
+    update(id: number | Interceptor, fn: Interceptor): number | false | Interceptor;
+    use(fn: Interceptor): number;
+}
+export interface Middleware<Req, Res, Err, Options> {
+    error: Pick<Interceptors<ErrInterceptor<Err, Res, Req, Options>>, 'eject' | 'use'>;
+    request: Pick<Interceptors<ReqInterceptor<Req, Options>>, 'eject' | 'use'>;
+    response: Pick<Interceptors<ResInterceptor<Res, Req, Options>>, 'eject' | 'use'>;
+}
+export declare const createInterceptors: <Req, Res, Err, Options>() => {
+    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
+    request: Interceptors<ReqInterceptor<Req, Options>>;
+    response: Interceptors<ResInterceptor<Res, Req, Options>>;
+};
+export declare const createConfig: <T extends ClientOptions = ClientOptions>(override?: Config<Omit<ClientOptions, keyof T> & T>) => Config<Omit<ClientOptions, keyof T> & T>;
+export {};