haystack-contracts 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +79 -88
  2. package/dist/index.d.mts +1371 -144
  3. package/dist/index.d.ts +1371 -144
  4. package/dist/index.js +107 -0
  5. package/dist/index.mjs +96 -0
  6. package/openapi.json +1380 -0
  7. package/package.json +51 -34
package/README.md CHANGED
@@ -1,88 +1,79 @@
1
- # haystack-contracts
2
-
3
- TypeScript API contracts for the **Haystack Robotics platform** — shared between the backend API and any frontend/SDK consumer.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install haystack-contracts
9
- # or
10
- pnpm add haystack-contracts
11
- # or
12
- yarn add haystack-contracts
13
- ```
14
-
15
- ## Usage
16
-
17
- ### Response envelope typing
18
-
19
- ```typescript
20
- import type { ApiResponse, ApiErrorResponse, PaginatedResponse } from 'haystack-contracts';
21
-
22
- // Type your API call results
23
- const response: ApiResponse<BotSummaryResponse[]> = await fetch('/api/v1/robots/bots/summary')
24
- .then(r => r.json());
25
-
26
- // response.success → true
27
- // response.statusCode → 200
28
- // response.data → BotSummaryResponse[]
29
- // response.timestamp → "2026-02-25T16:00:00.000Z"
30
- ```
31
-
32
- ### Request payload typing
33
-
34
- ```typescript
35
- import type {
36
- CreateTenantPayload,
37
- CreateUserPayload,
38
- WebhookPayload,
39
- } from 'haystack-contracts';
40
-
41
- const body: CreateTenantPayload = {
42
- name: 'Acme Corp',
43
- slug: 'acme-corp',
44
- status: 'ACTIVE',
45
- };
46
- ```
47
-
48
- ### Full type inventory
49
-
50
- #### Response Envelope
51
- | Type | Description |
52
- |------|-------------|
53
- | `ApiResponse<T>` | `{ success: true, statusCode, data: T, timestamp }` |
54
- | `ApiErrorResponse` | `{ success: false, statusCode, data: null, error, timestamp, path }` |
55
- | `PaginationMeta` | `{ page, limit, total, totalPages }` |
56
- | `PaginatedResponse<T>` | `ApiResponse<T[]>` + `PaginationMeta` |
57
-
58
- #### Robots
59
- | Type | Description |
60
- |------|-------------|
61
- | `Robot` | Robot entry from Nimbus Cloud |
62
- | `Metric` | Robot metric from Nimbus Cloud |
63
- | `WebhookBasicData` | Nested BasicData block in Cognimbus webhook |
64
- | `WebhookPayload` | Full Cognimbus webhook payload (nested + flat formats) |
65
- | `BotSummaryResponse` | Current bot status from local DB |
66
- | `BotHistoryResponse` | Single bot status history record |
67
- | `BotStateChangeResponse` | Single online↔offline transition record |
68
-
69
- #### Tenants
70
- | Type | Description |
71
- |------|-------------|
72
- | `TenantStatus` | `'ACTIVE' \| 'SUSPENDED' \| 'INACTIVE'` |
73
- | `CreateTenantPayload` | POST /tenants body |
74
- | `UpdateTenantPayload` | PATCH /tenants/:id body |
75
- | `TenantResponse` | Tenant resource shape |
76
-
77
- #### Users
78
- | Type | Description |
79
- |------|-------------|
80
- | `UserRole` | `'SUPER_ADMIN' \| 'ADMIN' \| 'OPERATOR' \| 'VIEWER'` |
81
- | `CreateUserPayload` | POST /users body |
82
- | `UpdateUserPayload` | PATCH /users/:id body |
83
- | `UserResponse` | User resource shape |
84
-
85
- ## Package details
86
- - **Zero runtime code** — types only, fully tree-shakeable
87
- - **Dual format** — CJS (`dist/index.cjs`) + ESM (`dist/index.js`)
88
- - **TypeScript declarations** — `dist/index.d.ts`
1
+ # haystack-contracts
2
+
3
+ Public API contracts for Haystack Robotics — TypeScript types, path constants, and the OpenAPI document for frontend apps.
4
+
5
+ **Full consumer guide:** [docs/HAYSTACK_CONTRACTS_CONSUMERS.md](https://github.com/haystackrobotics/haystack-backend/blob/main/docs/HAYSTACK_CONTRACTS_CONSUMERS.md)
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pnpm add haystack-contracts
11
+ ```
12
+
13
+ Pin a specific version in production apps (e.g. `"haystack-contracts": "1.0.0"`).
14
+
15
+ ## What ships on npm
16
+
17
+ | Import | Use |
18
+ |--------|-----|
19
+ | `haystack-contracts` | Types, `PublicApiPath`, enums, response envelopes |
20
+ | `haystack-contracts/openapi.json` | OpenAPI 3 spec for API reference sites |
21
+
22
+ ## Docs frontend (React static API page)
23
+
24
+ Import the spec and pass it to your OpenAPI renderer:
25
+
26
+ ```typescript
27
+ import openApiSpec from 'haystack-contracts/openapi.json';
28
+ ```
29
+
30
+ Or load from CDN:
31
+
32
+ ```text
33
+ https://unpkg.com/haystack-contracts@1.0.0/openapi.json
34
+ ```
35
+
36
+ Requires `resolveJsonModule: true` in `tsconfig.json` for the import pattern.
37
+
38
+ See the [consumer guide](https://github.com/haystackrobotics/haystack-backend/blob/main/docs/HAYSTACK_CONTRACTS_CONSUMERS.md#a-docs-frontend-react-openapi--static-page) for copy-at-build-time and CDN patterns.
39
+
40
+ ## Haystack IoT SaaS (typed API calls)
41
+
42
+ ```typescript
43
+ import { HAYSTACK_PRODUCTION_API_URL, PublicApiPath } from 'haystack-contracts';
44
+ import type {
45
+ ApiSuccessResponse,
46
+ AuthResponse,
47
+ LoginPayload,
48
+ RobotListItem,
49
+ } from 'haystack-contracts';
50
+
51
+ const res = await fetch(
52
+ `${HAYSTACK_PRODUCTION_API_URL}${PublicApiPath.auth.login}`,
53
+ {
54
+ method: 'POST',
55
+ headers: { 'Content-Type': 'application/json' },
56
+ body: JSON.stringify({ email, password } satisfies LoginPayload),
57
+ },
58
+ );
59
+ const { data }: ApiSuccessResponse<AuthResponse> = await res.json();
60
+ ```
61
+
62
+ See the [consumer guide](https://github.com/haystackrobotics/haystack-backend/blob/main/docs/HAYSTACK_CONTRACTS_CONSUMERS.md#b-haystack-iot-saas-typed-api-integration) for robots, metrics, disinfection, and analytics examples.
63
+
64
+ ## Maintainers (backend monorepo)
65
+
66
+ After changing public API DTOs or `@ApiPublicWebhook()` endpoints:
67
+
68
+ ```bash
69
+ pnpm api-check
70
+ pnpm --filter haystack-contracts build
71
+ ```
72
+
73
+ Publishing: [PUBLISHING.md](./PUBLISHING.md)
74
+
75
+ ## Package details
76
+
77
+ - Zero runtime dependencies
78
+ - Dual CJS + ESM (`dist/index.js`, `dist/index.mjs`)
79
+ - Types in `dist/index.d.ts`