npm package: @huitzo/dashboard-sdk
Description: Core client SDK for Huitzo dashboard
Latest version: 0.3.0

# @huitzo/dashboard-sdk

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

## Installation

```bash
npm install @huitzo/dashboard-sdk
```

## Quick Start

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

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

// Register a new account
await huitzo.auth.register('jane@acme.com', 'password', 'acme', 'invite_code');

// Authenticate
await huitzo.auth.login('user@example.com', '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

```typescript
// 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`:

```typescript
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](https://openapi-ts.dev/) 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.

```bash
# 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

```bash
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