haystack-contracts

TypeScript API contracts for the Haystack Robotics platform — shared between the backend API and any frontend/SDK consumer.

Install

npm install haystack-contracts
# or
pnpm add haystack-contracts
# or
yarn add haystack-contracts

Usage

Response envelope typing

import type { ApiResponse, ApiErrorResponse, PaginatedResponse } from 'haystack-contracts';

// Type your API call results
const response: ApiResponse<BotSummaryResponse[]> = await fetch('/api/v1/robots/bots/summary')
  .then(r => r.json());

// response.success    → true
// response.statusCode → 200
// response.data       → BotSummaryResponse[]
// response.timestamp  → "2026-02-25T16:00:00.000Z"

Request payload typing

import type {
  CreateTenantPayload,
  CreateUserPayload,
  WebhookPayload,
} from 'haystack-contracts';

const body: CreateTenantPayload = {
  name: 'Acme Corp',
  slug: 'acme-corp',
  status: 'ACTIVE',
};

Full type inventory

Response Envelope

| Type | Description | |------|-------------| | ApiResponse<T> | { success: true, statusCode, data: T, timestamp } | | ApiErrorResponse | { success: false, statusCode, data: null, error, timestamp, path } | | PaginationMeta | { page, limit, total, totalPages } | | PaginatedResponse<T> | ApiResponse<T[]> + PaginationMeta |

Robots

| Type | Description | |------|-------------| | Robot | Robot entry from Nimbus Cloud | | Metric | Robot metric from Nimbus Cloud | | WebhookBasicData | Nested BasicData block in Cognimbus webhook | | WebhookPayload | Full Cognimbus webhook payload (nested + flat formats) | | BotSummaryResponse | Current bot status from local DB | | BotHistoryResponse | Single bot status history record | | BotStateChangeResponse | Single online↔offline transition record |

Tenants

| Type | Description | |------|-------------| | TenantStatus | 'ACTIVE' \| 'SUSPENDED' \| 'INACTIVE' | | CreateTenantPayload | POST /tenants body | | UpdateTenantPayload | PATCH /tenants/:id body | | TenantResponse | Tenant resource shape |

Users

| Type | Description | |------|-------------| | UserRole | 'SUPER_ADMIN' \| 'ADMIN' \| 'OPERATOR' \| 'VIEWER' | | CreateUserPayload | POST /users body | | UpdateUserPayload | PATCH /users/:id body | | UserResponse | User resource shape |

Package details

• Zero runtime code — types only, fully tree-shakeable
• Dual format — CJS (dist/index.cjs) + ESM (dist/index.js)
• TypeScript declarations — dist/index.d.ts