TypeScript SDK

SDK для Node.js 22+ реализован и проверен локально. Публикации в npm пока нет, production API ещё не открыт для общего доступа. Не проси агента устанавливать выдуманную публичную версию пакета. MCP и устанавливаемый skill — отдельные компоненты, не часть этого SDK.

Скачать и установить

Сборка документации включает архивы SDK и MCP и машиночитаемый манифест. Они станут публичными после деплоя этой версии документации; это не публикация в npm. Выбери @csfolder/sdk в манифесте, скачай его url с того же доверенного домена документации и проверь SHA-256 и размер файла перед установкой в серверный проект:

npm install --ignore-scripts /absolute/path/to/downloaded-sdk.tgz

URL содержит хеш содержимого. Сохрани архив и lockfile: доступность старых URL после обновления документации не гарантируется. Манифест также содержит хеш точных байтов /openapi.json. Контрольная сумма защищает от повреждения файла, но не от взлома домена; криптографической подписи манифеста нет. При установке могут скачиваться закреплённые публичные runtime-зависимости.

Собрать из исходников (для разработчиков CSFolder)

В доверенной копии репозитория CSFolder:

pnpm --filter @csfolder/sdk pack --out /absolute/path/csfolder-sdk-0.1.0.tgz

Упаковка собирает SDK и генерирует типы из актуального OpenAPI-контракта. Установи полученный архив в серверную часть своего приложения:

pnpm add /absolute/path/csfolder-sdk-0.1.0.tgz

Первый типизированный запрос

Задай CSFOLDER_API_KEY через хранилище секретов серверного окружения. Ключ нельзя вставлять в промпт, URL, браузерный компонент или публичную переменную окружения.

import { CSFolderClient } from '@csfolder/sdk';

const api = new CSFolderClient();
const { data: items } = await api.request('listItems', {
  query: { q: 'AK-47', limit: 10 },
});
if (items[0]) {
  const quotes = await api.request('getMarketPrices', {
    params: { item_id: items[0].item_id },
  });
  // quotes.data.asks / bids: целые центы USD, время источника может быть null.
}

JSON-операции доступны через request(operationId, input). SDK проверяет вход и ответ по общему контракту; поля смотри в OpenAPI. Пропуски и десятичные строки сохраняются. Для приватных портфелей по-прежнему нужен персональный токен с разрешением владельца.

По умолчанию используется https://api.csfolder.com. Для локального API явно задай baseUrl: 'http://127.0.0.1:PORT' и allowLocalhost: true. Другие удалённые адреса и редиректы запрещены.

Пагинация с бюджетом

for await (const page of api.pages(
  'listItems',
  { query: { limit: 100 } },
  { maxPages: 5 },
)) {
  // Обработай page.data; сохрани page.meta.next_cursor, если остались данные.
}

maxPages обязателен: от 1 до 100. Достижение лимита страниц не означает, что каталог выгружен полностью. Фильтры сохраняются; повторяющийся курсор вызывает ошибку. У каждой страницы свой таймаут. Через AbortSignal можно отменить весь обход. Общего кэша в SDK нет; приватные ответы нельзя кэшировать между разными ключами.

Полная выгрузка цен

Для снимка всех маркетов используй api.streamMarketSnapshot({ signal }). Итератор отдаёт типизированные записи start, item, end. Записывай строки во временный набор; заменяй рабочую базу только после успешного завершения цикла. Ранний break, отмена или исключение требуют отбросить временный набор.

Клиент проверяет схему, UTF‑8, возрастающие ID, поколение/ID запроса/число предметов, лимит строки 256 КиБ и корректный конец потока. Запись end отдаётся только после EOF. Автоматических повторов потока нет. Общий таймаут — 120 секунд, включая обработку записей потребителем; через timeoutMs его можно уменьшить.

Ошибки и лимиты запросов

У JSON-запросов по умолчанию таймаут 15 секунд и лимит распакованного ответа 8 МиБ. Повторы выключены; maxRetries: 1 или 2 разрешает ограниченные повторы 429/503 с учётом Retry-After и оставшегося времени. Исчерпанная месячная квота автоматически не повторяется. Каждый повтор может расходовать квоту.

Лови CSFolderError и проверяй code, status, requestId, retryAfterSeconds. Сообщения очищены и не копируют внутренние подробности сервера. Подробнее: лимиты и ошибки.

Для AI-сборки продукта попроси агента использовать SDK на сервере, сохранять смысл данных и проверить пустую историю, отказ в доступе, исчерпанную квоту и обрыв выгрузки. Сгенерированный интерфейс не создаёт отсутствующую историю и не даёт разрешения на деплой.