Быстрый старт для TypeScript

Обращайтесь к инфраструктурному API /platform/v1 с помощью генерируемого TypeScript-клиента @forestvpn/console-api.

@forestvpn/console-api — это генерируемый TypeScript-клиент для плоскости /platform/v1: типизированные модели запросов и ответов прямо из того же OpenAPI-документа, из которого построен справочник API.

Честно о распространении: пакет пока не опубликован в npm. Он находится в packages/forestvpn/console-api репозитория ForestVPN как пакет pnpm-воркспейса — вы используете его изнутри локальной копии.

Что понадобится

Node.js 20+ и pnpm
Локальная копия репозитория ForestVPN с выполненным pnpm install в его корне
API-ключ проекта (fvpn_v1_…) — см. API-ключи

1. Добавьте зависимость из воркспейса

Внутри воркспейса локальной копии подключите пакет через протокол workspace:

package.json (yours)

{
  "dependencies": {
    "@forestvpn/console-api": "workspace:*"
  }
}

2. Соберите dist клиента

Приложения используют собранный dist/ пакета, поэтому соберите его один раз (и после каждой регенерации спецификации) локальным для пакета компилятором TypeScript:

pnpm -C packages/forestvpn/console-api build

3. Первый вызов: получите список API-ключей

first-call.ts

import { Configuration, PlatformApiKeysApi } from "@forestvpn/console-api";

// Authenticate with a project API key (fvpn_v1_…) minted in the console.
// The key is project-bound: it only authenticates inside its own project.
export async function listApiKeys(apiKey: string, projectId: string) {
  const api = new PlatformApiKeysApi(
    new Configuration({
      basePath: "https://api.fvpn.net",
      accessToken: apiKey,
    }),
  );

  const { data: keys } = await api.listPlatformApiKeys(projectId);
  for (const key of keys) {
    console.log(
      `${key.name} (${key.key_prefix}) last used: ${key.last_used_at ?? "never"}`,
    );
  }
  return keys;
}

Два момента, на которые стоит обратить внимание:

Аутентификация — это только ключ. accessToken отправляет Authorization: Bearer fvpn_v1_…; без cookie, без сессии.
Идентификатор проекта задаётся явно. Каждая операция /platform/v1 принимает UUID проекта первым аргументом (он отправляется в заголовке X-Project-Id). Сам ключ привязан к проекту, поэтому оба значения должны совпадать — несоответствие даёт 401.

4. Запуск

Вызовите её с вашим ключом и идентификатором проекта — например, из небольшого входного файла, запускаемого через tsx или скомпилированного с помощью tsc:

import { listApiKeys } from "./first-call";

await listApiKeys(process.env.FVPN_API_KEY!, process.env.FVPN_PROJECT_ID!);

Ожидаемый вывод: по строке на каждый ключ — имя, отображаемый префикс и время, когда ключ в последний раз аутентифицировал запрос.

Чем проверяется

scripts/quickstart-verify/ts-client.sh — собирает dist пакета и проверяет типами сниппет с этой страницы против настоящего пакета при каждом прогоне CI.