@contexthub/client

TypeScript client for the ContextHub API. Auto-generated from the OpenAPI specification with hand-crafted Zod schemas for runtime validation.

Installation

npm install @contexthub/client

Development

npm install          # Install dependencies
npm run generate     # Regenerate client from OpenAPI spec
npm run build        # Build the package
npm run dev          # Build with watch mode
npm run test         # Run tests (watch)
npm run test:run     # Run tests once
npm run typecheck    # Type-check without emitting
npm run lint         # Lint source files
npm run format       # Format source files

Regenerating from OpenAPI

When the ContextHub API changes, regenerate the client:

# From the repo root
make sync-openapi

# Then rebuild
cd clients/ts
npm run generate
npm run build

Publishing to npm

The package is published automatically via GitHub Actions using npm's OIDC trusted publishers (no tokens required).

One-time npm setup

Configure the trusted publisher on npmjs.com:

1. Go to @contexthub/client package settings on npmjs.com
2. Navigate to Settings > Publishing access
3. Under Trusted Publishers, add a new GitHub Actions publisher:
   • Repository owner: Sonic-Web-Dev
   • Repository name: contexthub-brain
   • Workflow filename: client-ts-publish.yml
   • Environment: (leave empty)

Cutting a release

1. Bump the version in clients/ts/package.json
2. Commit the change
3. Create and push a tag matching the pattern @contexthub/client@<version>:

git tag @contexthub/[email protected]
git push origin @contexthub/[email protected]

The Publish @contexthub/client workflow triggers on tags matching @contexthub/client@*, builds the package, and publishes to npm.

Package Structure

clients/ts/
├── src/
│   ├── index.ts            # Public API barrel export
│   ├── client.ts           # ContextHub client wrapper
│   ├── path.ts             # Path utilities
│   ├── path-service.ts     # Path service
│   ├── websocket.ts        # WebSocket client
│   ├── schemas/            # Hand-crafted Zod validation schemas
│   ├── generated/          # Auto-generated from OpenAPI (do not edit)
│   └── types/              # Shared type definitions
├── tests/                  # Vitest test suite
├── openapi.json            # Source OpenAPI spec
├── openapi-ts.config.ts    # Code generation config
├── tsup.config.ts          # Build config (dual CJS/ESM)
└── package.json