Перейти к содержимому

TypeScript / JavaScript SDK

Окно терминала
npm install @flowworker/sdk

Самый простой способ - 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);

Для 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-события безопасно с проверкой 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

Auto-retry на ошибки 5xx и 429 с exponential backoff. Поддерживает заголовок Retry-After.

import { withRetry } from '@flowworker/sdk';
const result = await withRetry(
() => fw.tasks.list(),
{ maxAttempts: 5, initialDelayMs: 500 }
);

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);
}
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