@huitzo/dashboard-sdk

Core client SDK for Huitzo dashboard. Framework-agnostic API for executing Intelligence Pack commands inside Huitzo Hub.

Installation

npm install @huitzo/dashboard-sdk

Quick Start

import { HuitzoClient } from '@huitzo/dashboard-sdk';

const huitzo = new HuitzoClient({
  apiUrl: 'https://api.huitzo.com',
});

// Register a new account
await huitzo.auth.register('[email protected]', 'password', 'acme', 'invite_code');

// Authenticate
await huitzo.auth.login('[email protected]', 'password');

// Get current user
const user = await huitzo.auth.getUser();

// Execute a command
const result = await huitzo.commands.execute('@acme/claims/process-claim', {
  claimId: 'CLM-12345',
});

console.log(result.data.result);

Commands

// Execute a command
const result = await huitzo.commands.execute<MyResultType>(
  '@acme/claims/process-claim',
  { claimId: 'CLM-12345' },
  { timeout: 30_000 },
);

// List available commands
const commands = await huitzo.commands.list();

// Get command details
const command = await huitzo.commands.get('@acme/claims/process-claim');

Error Handling

All errors extend HuitzoError and can be narrowed with instanceof:

import {
  HuitzoError,
  AuthenticationError,
  ValidationError,
  NetworkError,
  RateLimitError,
} from '@huitzo/dashboard-sdk';

try {
  await huitzo.commands.execute('@acme/claims/process', args);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — redirect to login
  } else if (error instanceof ValidationError) {
    // 400/422 — show field errors from error.details
  } else if (error instanceof RateLimitError) {
    // 429 — retry after error.retryAfter seconds
  } else if (error instanceof NetworkError) {
    // DNS failure, offline, etc.
  } else if (error instanceof HuitzoError) {
    // Catch-all for any other API error
    console.error(error.code, error.message);
  }
}

Every error carries:

• code — machine-readable error code (e.g. AUTHENTICATION_FAILED)
• statusCode — HTTP status (undefined for network errors)
• details — structured context (field errors, etc.)
• correlationId — request ID for debugging
• timestamp — server timestamp

Regenerating API Types

The SDK uses openapi-typescript to generate TypeScript types from the backend's OpenAPI schema. The generated types are used internally by the client for path autocomplete and request body validation.

# Regenerate from live backend
npm run generate:api-types

The generated file is committed to the repo so builds don't require network access.

Development

npm run build     # Build ESM + CJS + DTS
npm run test      # Run unit tests (vitest --project unit)
npm run lint      # Run biome
npm run dev       # Watch mode

Integration tests

Integration tests run against a real API. They are in a separate Vitest project and do not run by default.

• Unit tests: npm run test (runs vitest run --project unit). No backend required.
• Integration tests: npm run test:integration. Set E2E_BASE_URL, E2E_LOGIN_EMAIL and E2E_LOGIN_PASSWORD. When either credential is unset, auth tests are skipped.

License

MIT