Перейти к содержимому
Последнее обновление

TypeScript SDK

Официальный TypeScript SDK для Vilna API. Предоставляет полностью типизированный клиент, сгенерированный из OpenAPI-спецификации, поэтому каждый эндпоинт, тело запроса и ответ проверяются на этапе компиляции.

  • Пакет: @vilna/sdk
  • Лицензия: Apache-2.0
  • Node.js: >= 18

Установка

npm install @vilna/sdk

Создание клиента

import { createVilnaClient } from "@vilna/sdk";

const client = createVilnaClient({
  apiKey: "your-api-key",
  namespace: "your-namespace", // по умолчанию: "demo"
  // baseUrl: "https://custom.vilna.app", // необязательное переопределение
  // headers: { "Custom-Header": "value" }, // необязательные дополнительные заголовки
});

Параметр namespace определяет базовый URL вашего API (https://{namespace}.vilna.app). Если вам нужен полностью кастомный URL, передайте baseUrl.

Под капотом SDK использует openapi-fetch и предоставляет те же методы GET, POST, PUT, DELETE с полным автодополнением путей.

Примеры использования

Список блокчейнов

const { data, error } = await client.GET("/blockchains");

if (data) {
  for (const chain of data.items) {
    console.log(chain.gid, chain.name, chain.is_active);
  }
}

Получение деталей адреса

const { data } = await client.GET("/addresses/{address}", {
  params: {
    path: { address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123" },
  },
});

Создание внешнего адреса

const { data } = await client.POST("/addresses/external", {
  body: {
    value: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    chainFamily: "evm",
    label: "Treasury",
  },
});

Запрос балансов

const { data } = await client.GET("/balances", {
  params: { query: { limit: 50 } },
});

Постраничная навигация

Эндпоинты списков возвращают ответы с пагинацией, содержащие items и meta. Используйте параметры page и limit для перебора всех страниц:

// Paginate through addresses
let page = 1;
let hasMore = true;

while (hasMore) {
  const { data } = await client.GET("/addresses", {
    params: { query: { page, limit: 100 } },
  });
  // process data.items
  hasMore = page < data.meta.total_pages;
  page++;
}

Создание вебхук-канала уведомлений

const { data } = await client.POST("/notification_channels", {
  body: {
    name: "My Webhook",
    config: {
      kind: "webhook",
      url: "https://example.com/webhook",
      headers: {
        Authorization: "Bearer secret",
      },
    },
  },
});

Экспортируемые типы

SDK реэкспортирует несколько псевдонимов типов для удобства:

ЭкспортОписание
VilnaClientТип экземпляра клиента, возвращаемого createVilnaClient
VilnaPathsОбъединение всех строк путей API
VilnaComponentsВсе схемы компонентов из OpenAPI-спецификации
CreateVilnaClientOptionsОпции, принимаемые createVilnaClient
pathsНеобработанные определения путей (то же, что VilnaPaths)
componentsНеобработанные определения компонентов (то же, что VilnaComponents)
operationsТипы на уровне операций для пар запрос/ответ

Вы можете использовать VilnaComponents для ссылки на конкретные типы схем:

import type { VilnaComponents } from "@vilna/sdk";

type Address = VilnaComponents["schemas"]["Address"];
type Transaction = VilnaComponents["schemas"]["Transaction"];

Обработка ошибок

Каждый вызов возвращает { data, error }. При неудачном запросе error соответствует формату RFC 7807 Problem Details:

const { data, error } = await client.GET("/blockchains");

if (error) {
  // error.type    - URI типа проблемы
  // error.title   - краткое описание (например, "Not Found")
  // error.status  - HTTP-код статуса
  // error.detail  - человекочитаемое объяснение
  console.error(error.title, error.detail);
}

Для ошибок валидации (400) ответ включает массив fields с деталями по каждому полю:

const { data, error } = await client.POST("/addresses/external", {
  body: { /* ... */ },
});

if (error && error.status === 400) {
  for (const field of error.fields ?? []) {
    console.error(`${field.name}: ${field.reason}`);
  }
}

Полный справочник по ошибкам см. в разделе Ошибки и устранение неполадок.

Дополнительные экспорты

SDK также экспортирует два вспомогательных значения:

import { DEFAULT_NAMESPACE, API_KEY_HEADER, getVilnaBaseUrl } from "@vilna/sdk";

console.log(DEFAULT_NAMESPACE);           // "demo"
console.log(API_KEY_HEADER);              // "X-Api-Key"
console.log(getVilnaBaseUrl("acme"));     // "https://acme.vilna.app"

Дополнительные материалы

Предыдущая страница
Следующая страница