@ziggs-ai/contracts

Wire contracts for the Ziggs API — the response shapes, error body, and socket frames the server actually sends, shared by every client.

Types plus the closed vocabularies they are built from. No network, no environment reads, no dependencies, so any runtime can import it.

import type { ChatListResponse, AttentionFeed } from '@ziggs-ai/contracts';
import { SERVER_EVENTS, isApiErrorBody } from '@ziggs-ai/contracts';

What is here

| Module | Carries | | --- | --- | | chat | GET /chats, GET /chats/:chatId/messages, the message write paths | | inbox | Agent request triage, GET /inbox/attention, POST /inbox/seen | | error | the one error body every handler answers in | | socket | frame names and payloads, both directions | | vocabulary | the closed value lists the above are built from |

The server is authoritative

These are the server's own definitions, not a copy of them. A shape changes here and in the server in the same commit, so a client that pins a version knows exactly which wire it is talking to.

The socket is a receive-only accelerator: every frame has an HTTP read that is the source of truth. A client that misses a frame catches up on its next read.

Releasing

Change contract sources and bump package.json in the same pull request. CI rejects source changes without a newer version. Merging a version bump to main publishes that commit automatically after regenerating and checking the wire types. A contracts-v<version> tag remains available for manual releases.

Release contracts before merging client dependency upgrades. Clients can test an unreleased version with a local npm pack tarball; local validation is not a registry publication.