TypeScript / JavaScript SDK
Установка
Заголовок раздела «Установка»npm install @flowworker/sdkАутентификация
Заголовок раздела «Аутентификация»API key
Заголовок раздела «API key»Самый простой способ - API-ключ уровня аккаунта. Создайте ключ в Team Settings → API & Integrations.
import { FlowWorker } from '@flowworker/sdk';
const fw = new FlowWorker({ apiKey: process.env.FW_KEY });
// Раздельные сервисы по доменамconst tasks = await fw.tasks.list();const projects = await fw.projects.list();const members = await fw.members.list();const events = await fw.events.list();console.log(tasks);OAuth 2.0 (с auto-refresh)
Заголовок раздела «OAuth 2.0 (с auto-refresh)»Для third-party интеграций, где ключ API недоступен или нужен доступ от имени конкретного пользователя, используйте OAuth. SDK автоматически обновляет access token по истечении и вызывает onTokenRefreshed для персистирования нового refresh token.
import { FlowWorker } from '@flowworker/sdk';
function loadFromStore(): string { return process.env.FW_REFRESH_TOKEN ?? '';}
function saveToStore(tokens: { accessToken: string; refreshToken: string; expiresAt: number }) { // Сохраните tokens.refreshToken в вашем хранилище (БД, файл, vault) console.log('Token refreshed, new refresh_token:', tokens.refreshToken);}
const fw = new FlowWorker({ oauth: { clientId: 'fw_oid_xxx', clientSecret: process.env.FW_SECRET, refreshToken: loadFromStore(), onTokenRefreshed: (t) => saveToStore(t), },});
const me = await fw.account.me();console.log(me);При истечении access token SDK сам вызывает POST /oauth/token с grant_type=refresh_token и обновляет кэш. Повторный вызов метода происходит прозрачно.
Webhook verify
Заголовок раздела «Webhook verify»Принимайте webhook-события безопасно с проверкой HMAC-подписи. Хелпер verifyWebhookSignature поддерживает dual-signature после rotation секрета.
import express from 'express';import { verifyWebhookSignature } from '@flowworker/sdk';
const app = express();
app.post('/hook', express.raw({ type: '*/*' }), (req, res) => { if ( !verifyWebhookSignature( req.body, req.header('X-FlowWorker-Signature')!, process.env.FW_HOOK_SECRET! ) ) { return res.status(401).end(); }
const event = JSON.parse(req.body.toString()); console.log('Event received:', event.eventType); // ... обработайте событие
res.status(200).end();});
app.listen(3000);Формат заголовка: t=<unix>,v1=<signature>[,v1=<old_signature>]. При rotation присутствуют два v1= - хелпер принимает запрос, если хотя бы одна подпись совпадает.
Пространства имён
Заголовок раздела «Пространства имён»SDK разделён на доменные сервисы:
| Сервис | Описание |
|---|---|
fw.tasks.* | Задачи: list, get, create, update, delete, search |
fw.projects.* | Проекты: list, get, create, search |
fw.members.* | Участники аккаунта: list, get |
fw.events.* | События календаря: list, get, create, update, delete |
fw.attachments.* | Вложения: list, upload, download, delete |
fw.account.* | Аккаунт: me |
Хелперы
Заголовок раздела «Хелперы»withRetry(operation, opts)
Заголовок раздела «withRetry(operation, opts)»Auto-retry на ошибки 5xx и 429 с exponential backoff. Поддерживает заголовок Retry-After.
import { withRetry } from '@flowworker/sdk';
const result = await withRetry( () => fw.tasks.list(), { maxAttempts: 5, initialDelayMs: 500 });paginate(fetchPage, opts)
Заголовок раздела «paginate(fetchPage, opts)»Async iterator, который проходит по всем страницам результатов.
import { paginate } from '@flowworker/sdk';
for await (const task of paginate((page) => fw.tasks.search({ page, pageSize: 100 }))) { console.log(task.id, task.title);}PKCE helpers (browser OAuth)
Заголовок раздела «PKCE helpers (browser OAuth)»import { generatePkceChallenge, buildAuthorizeUrl } from '@flowworker/sdk';
const { codeVerifier, codeChallenge } = await generatePkceChallenge();
const url = buildAuthorizeUrl({ clientId: 'fw_oid_xxx', redirectUri: 'https://your-app.io/callback', scopes: ['tasks:read', 'projects:read'], codeChallenge,});
window.location.href = url;// После редиректа: обменяйте code на токен с codeVerifierСм. также
Заголовок раздела «См. также»- OAuth 2.0 - детали Authorization Code + PKCE flow
- Безопасность webhooks - rotation, dual-signature, replay protection
- API Reference - полная справка всех 19 endpoints