@arythmatic/flow-client

Official JavaScript client for Arythmatic Flow — the API platform for testing, workflows, AI, monitoring, and security scanning.

Install

npm install @arythmatic/flow-client

Quick Start

import { FlowClient } from '@arythmatic/flow-client';

const flow = new FlowClient();

// Authenticate
await flow.login({ email: '[email protected]', password: 'secret' });

// Set active team
flow.setTeamId('your-team-id');

// Run a stored collection
const collections = await flow.collections.list();
const result = await flow.collections.run(collections[0].id);
console.log(result);

Features

• HTTP Client — axios-like interface with interceptors, timeouts, and auto-auth headers.
• Collections — list, run, and inspect stored request collections.
• Workflows — execute DAG-based workflows with custom inputs.
• AI — generate requests from descriptions, suggest assertions, manage conversations.
• Monitoring — create uptime/performance monitors and trigger on-demand checks.
• Security Scanning — run OWASP-style vulnerability scans on requests, collections, or URLs.
• Proxy Execution — send arbitrary HTTP requests through Flow's engine (CORS-free, with variables, scripts, and assertions).

Configuration

const flow = new FlowClient({
  baseURL: 'https://flow.arythmatic.cloud', // or your self-hosted instance
  accessToken: '...',   // optional: pre-authenticated
  refreshToken: '...',  // optional
  teamId: '...',        // optional: default team
  timeout: 30000,       // request timeout in ms
  headers: {},          // extra default headers
});

Authentication

// Login (stores tokens automatically)
const { user, teams } = await flow.login({ email, password });

// Register
const { user, team } = await flow.register({ email, password, name });

// Refresh
await flow.refresh();

// Get current user
const me = await flow.auth.me();

Collections

const collections = await flow.collections.list();

// Run the entire collection
const run = await flow.collections.run(collectionId, {
  mode: 'sequential',        // or 'parallel'
  environmentId: 'env-id',
  stopOnFailure: true,
});

// Run only specific requests from the collection
const runSubset = await flow.collections.run(collectionId, {
  requestIds: ['req-id-1', 'req-id-2'],
});

// Run a single request from a collection
const runOne = await flow.collections.runOne(collectionId, 'req-id-1');

const runs = await flow.collections.runs(collectionId);

Workflows

const workflows = await flow.workflows.list();
const result = await flow.workflows.run(workflowId, {
  environmentId: 'env-id',
  input: { userId: '123' },
});
const history = await flow.workflows.runs(workflowId);

AI

// Generate request definitions from text
const { requests } = await flow.ai.generate({
  input: 'A todo list API with CRUD',
  type: 'description',
});

// Suggest assertions
const { assertions } = await flow.ai.suggestAssertions({ status, headers, body, url, method });

// Token usage
const usage = await flow.ai.usage();

Monitors

const monitor = await flow.monitors.create({
  name: 'API Health',
  type: 'standalone',
  url: 'https://api.example.com/health',
  method: 'GET',
  expectedStatus: 200,
  interval: '30m',
});
await flow.monitors.check(monitor.id);

Security Scans

// Scan a stored request
await flow.scans.scanRequest(requestId);

// Scan a collection
await flow.scans.scanCollection(collectionId);

// Scan any URL
await flow.scans.scanUrl('https://api.example.com/users');

// Get results
const report = await flow.scans.get(scanId);

Environments

const envs = await flow.environments.list();
const env = await flow.environments.create({ name: 'Staging', color: '#3b82f6' });
await flow.environments.setVars(env.id, [{ k: 'BASE_URL', v: 'https://staging.example.com' }]);

Data Tables

const tables = await flow.dataTables.list();
const table = await flow.dataTables.create({ name: 'Users', columns: ['id', 'name', 'role'] });
await flow.dataTables.update(table.id, { rows: [[1, 'Alice', 'admin']] });

Request Templates

const tpls = await flow.requestTemplates.list();
const tpl = await flow.requestTemplates.create({ name: 'Get User', method: 'GET', path: '/users/{{id}}' });

Comments

const comments = await flow.comments.listForRequest(requestId);
await flow.comments.create(requestId, { body: 'Looks good!' });

Audit Log

const log = await flow.auditLog.list({ entity: 'collection', limit: 50 });
const users = await flow.auditLog.users();

Performance Tests

const result = await flow.perfTests.run({ url: 'https://api.example.com/health', concurrency: 20, totalRequests: 200 });
const runs = await flow.perfTests.list();

Team Management

const myTeams = await flow.teams.list();
const members = await flow.teams.members(teamId);
await flow.teams.invite(teamId, { email: '[email protected]', role: 'admin' });
await flow.teams.acceptInvitation(token);

History

const entries = await flow.history.list({ collectionId, limit: 20 });
const entry = await flow.history.get(entryId);
await flow.history.deleteMany({ olderThanDays: 30 });

Import / Export

const result = await flow.importExport.importCollection({ content: postmanJson });
await flow.importExport.exportCollection(collectionId, 'openapi');
await flow.importExport.exportCicd(collectionId, 'github', { schedule: '0 9 * * *' });

Workflow Folders & Templates

const folders = await flow.workflowFolders.list();
await flow.workflowFolders.create({ name: 'Onboarding', parentId });

const templates = await flow.workflowTemplates.list();
await flow.workflowTemplates.use(templateId, { name: 'My Onboarding Flow' });

MCP Servers

const templates = await flow.mcpServers.templates();
const servers = await flow.mcpServers.list();
await flow.mcpServers.create({ name: 'slack', type: 'template', credentials: { token: 'xoxb-...' } });
await flow.mcpServers.reconnect(serverId);

Proxy / Arbitrary Requests

Send any HTTP request through Flow's execution engine:

const res = await flow.requests.execute({
  method: 'POST',
  url: 'https://api.example.com/users',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice' }),
  envVars: [{ key: 'BASE_URL', value: 'https://api.example.com' }],
  assertions: [
    { type: 'status', operator: 'eq', expected: 201 },
  ],
});

Shorthand helpers are also available:

await flow.requests.get(url, opts);
await flow.requests.post(url, opts);
// put, patch, delete

Interceptors

flow.interceptors.request.use((config) => {
  console.log('Outgoing:', config.method, config.url);
  return config;
});

flow.interceptors.response.use(
  (res) => res,
  (err) => {
    console.error('Request failed:', err.message);
    throw err;
  }
);

Error Handling

import { FlowError, FlowAuthError } from '@arythmatic/flow-client';

try {
  await flow.collections.list();
} catch (err) {
  if (err instanceof FlowAuthError) {
    await flow.refresh();
  }
  console.error(err.status, err.code, err.response);
}

License

MIT