@empowerx-exflow/api-client

The official TypeScript SDK for the EMPOWERX EXFLOW API.

This package provides a type-safe, lightweight, and efficient way to interact with ExFlow services. Built on top of openapi-fetch, it offers full TypeScript support with generated types, automatic authentication handling, and a modular resource-based architecture.

Features

• Full TypeScript Support: Auto-generated types for all requests and responses.
• Modular Architecture: Resources are organized logically (e.g., client.workflows.actions).
• Automatic Authentication: Supports both static tokens and dynamic token retrieval (Bridge Pattern).
• Standardized Error Handling: Unified ApiError class for predictable error management.
• Zero-Config Pagination: Helpers for handling paginated list responses.
• Lightweight: Minimal dependencies, optimized for performance.

Installation

• npm: npm install @empowerx-exflow/api-client
• pnpm: pnpm add @empowerx-exflow/api-client
• yarn: yarn add @empowerx-exflow/api-client

Quick Start

Initialize the client with your base URL and authentication strategy.

import { ApiClient } from '@empowerx-exflow/api-client';

// Initialize the client
const client = new ApiClient({
  baseUrl: 'https://api.empowerx.com',
  // Static token
  token: 'your-api-token',
  // OR Dynamic token (e.g., from auth store)
  // getToken: async () => await auth.getAccessToken(),
});

// Use resources
async function main() {
  // Fetch all active workflows
  const { data: workflows, meta } = await client.workflows.findAll({ page: 1, limit: 10 });

  console.log(`Found ${meta.pagination.totalItems} workflows`);

  workflows.forEach((workflow) => {
    console.log(`- ${workflow.title} (${workflow.status})`);
  });
}

main();

Authentication

The client supports two authentication methods. The getToken function takes precedence if both are provided.

Static Token

Best for server-side usage or scripts with long-lived tokens.

const client = new ApiClient({
  baseUrl: '...',
  token: 'eyJh...',
});

Dynamic Token (Bridge Pattern)

Best for client-side apps where tokens expire and need refreshing. The client will call getToken before every request.

const client = new ApiClient({
  baseUrl: '...',
  getToken: async () => {
    // Logic to get the current valid token
    // e.g., from local storage, cookie, or auth provider SDK
    return localStorage.getItem('access_token') || '';
  },
});

Usage Patterns

Resource Namespaces

The SDK is organized into resources that match the API domain model.

// Personnel
await client.personnel.findAll();
await client.personnel.findById('uuid');

// Designations
await client.designations.findAll();

// Templates
await client.templates.create({ title: 'New Process', description: '...' });

// Workflows
await client.workflows.updateStatus('uuid', { status: 'Active' });

Nested Resources

Sub-resources are accessible through their parent resource.

// Actions within a Workflow
await client.workflows.actions.findAll('workflow-uuid');
await client.workflows.actions.create('workflow-uuid', { name: 'approve', type: 'button' });

// Steps within a Template
await client.templates.steps.findAll('template-uuid');

Pagination

List endpoints return a PaginatedResponse which includes data (array) and meta (pagination info).

const { data, meta } = await client.personnel.findAll({ page: 2, limit: 20 });

if (meta.pagination.hasNextPage) {
  console.log('More items available...');
}

Error Handling

All errors are thrown as ApiError instances containing status codes and server messages.

import { ApiError } from '@empowerx-exflow/api-client';

try {
  await client.workflows.create({ title: '' }); // Invalid request
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error('Trace ID:', error.meta?.traceId);
  } else {
    console.error('Unexpected error:', error);
  }
}

Escape Hatch

For endpoints not yet mapped in the SDK resources, use the raw request method. It still handles authentication and base URL resolution.

// POST /api/custom-endpoint
const result = await client.request('POST', '/api/custom-endpoint', {
  body: { foo: 'bar' },
});

Development

This package is part of the EmpowerX monorepo.

• Build: pnpm build
• Lint: pnpm lint
• Dev (Watch): pnpm dev