haystack-contracts 1.0.1 → 1.0.4

package/README.md

@@ -10,14 +10,14 @@ Public API contracts for Haystack Robotics — TypeScript types, path constants,
 pnpm add haystack-contracts
 ```
 
-Pin a specific version in production apps (e.g. `"haystack-contracts": "1.0.0"`).
+Pin a specific version in production apps (e.g. `"haystack-contracts": "1.0.2"`).
 
 ## What ships on npm
 
-| Import | Use |
-|--------|-----|
-| `haystack-contracts` | Types, `PublicApiPath`, enums, response envelopes |
-| `haystack-contracts/openapi.json` | OpenAPI 3 spec for API reference sites |
+| Import                            | Use                                               |
+| --------------------------------- | ------------------------------------------------- |
+| `haystack-contracts`              | Types, `PublicApiPath`, enums, response envelopes |
+| `haystack-contracts/openapi.json` | OpenAPI 3 spec for API reference sites            |
 
 ## Docs frontend (React static API page)
 
@@ -30,7 +30,7 @@ import openApiSpec from 'haystack-contracts/openapi.json';
 Or load from CDN:
 
 ```text
-https://unpkg.com/haystack-contracts@1.0.0/openapi.json
+https://unpkg.com/haystack-contracts@1.0.2/openapi.json
 ```
 
 Requires `resolveJsonModule: true` in `tsconfig.json` for the import pattern.
@@ -63,14 +63,82 @@ See the [consumer guide](https://github.com/haystackrobotics/haystack-backend/bl
 
 ## Maintainers (backend monorepo)
 
-After changing public API DTOs or `@ApiPublicWebhook()` endpoints:
+### After changing public API DTOs or `@ApiPublicWebhook()` endpoints
 
 ```bash
 pnpm api-check
 pnpm --filter haystack-contracts build
 ```
 
-Publishing: [PUBLISHING.md](./PUBLISHING.md)
+`pnpm api-check` re-exports `openapi.json`, regenerates `src/generated/`, and fails if artifacts have drifted. Commit any changed artifacts before publishing:
+
+```bash
+git add packages_published/contracts/openapi.json
+git add packages_published/contracts/src/generated/
+git commit -m "chore(contracts): sync openapi artifacts"
+```
+
+### Publishing a new version
+
+**1. Bump version** (from `packages_published/contracts/`):
+
+```bash
+npm version patch   # additive types / bugfix  → e.g. 1.0.4
+# npm version minor # new public endpoints      → e.g. 1.1.0
+# npm version major # breaking type changes     → e.g. 2.0.0
+```
+
+**2. Build and verify tarball:**
+
+```bash
+pnpm --filter haystack-contracts build
+cd packages_published/contracts
+npm pack --dry-run
+```
+
+Confirm the tarball includes `dist/`, `openapi.json`, and `README.md` — not `src/` or scripts.
+
+**3. Publish:**
+
+```bash
+npm publish
+```
+
+(`prepublishOnly` runs `build` again automatically if you skipped step 2.)
+
+**4. Commit and notify:**
+
+```bash
+git add packages_published/contracts/package.json
+git commit -m "chore(contracts): release haystack-contracts@<version>"
+```
+
+Tell the docs frontend and Haystack IoT SaaS teams to bump `haystack-contracts` in their `package.json` and redeploy.
+
+### First publish (one-time)
+
+```bash
+npm login
+pnpm api-check
+pnpm --filter haystack-contracts build
+cd packages_published/contracts
+npm pack --dry-run
+npm publish --access public
+```
+
+`--access public` is required the first time for an unscoped package name.
+
+### Verify after publish
+
+```bash
+npm view haystack-contracts version
+```
+
+CDN URL for docs sites:
+
+```text
+https://unpkg.com/haystack-contracts@<version>/openapi.json
+```
 
 ## Package details