@ziggs-ai/contracts 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @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.
+
+```ts
+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` | `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.

package/dist/chat.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Chat wire contracts: what `GET /chats`, `GET /chats/:chatId/messages` and
+ * the message write paths carry.
+ *
+ * Every shape here is what the server actually sends. A client that needs less
+ * narrows locally rather than redeclaring the shape.
+ */
+import type { ChatAddressKind, GrantAccessKind, MessageSenderType, PartyRole } from './vocabulary';
+/** A persona's face, as any surface renders it. */
+export interface PersonaDisplay {
+    id: string;
+    name: string;
+    image: string | null;
+    revision?: number;
+}
+/**
+ * How a principal is shown. Render this — never infer identity from an id.
+ *
+ * `subject` exists only own-side: across an org boundary the masked id is the
+ * whole point, so correlating it back to a principal must not be possible.
+ */
+export interface PrincipalPresentation {
+    /** Public, non-addressable reference. */
+    ref?: string;
+    persona: PersonaDisplay;
+    mode: 'persona' | 'chain';
+    subject?: {
+        id: string;
+        type: 'user' | 'agent';
+    };
+}
+/**
+ * Why a principal appears on the derived chat roster.
+ *
+ * There is no `member` arm: taking part is `grant`. The other kind is an
+ * overlay row that explains why someone is visible without putting them in the
+ * room, so a client branching on it must not treat `agreement` as absence.
+ */
+export type ChatRosterVia = {
+    kind: 'agreement';
+    /**
+     * Present on authority-derived rows. Dropped on persona-masked
+     * presentation so a masked member id cannot be correlated through the
+     * agreement.
+     */
+    agreementId?: string;
+    role: PartyRole;
+} | {
+    kind: 'grant';
+};
+/** One row of the complete display roster for a room. */
+export interface ChatRosterRow {
+    id: string;
+    type: 'user' | 'agent' | 'service' | 'org';
+    via: ChatRosterVia[];
+    /**
+     * What this holder's grant on the room lets them do, declared rather than
+     * guessed. Absent on overlay rows (an agreement party or a service): those
+     * are on the roster without holding anything, which is precisely the
+     * difference a reader needs. `write` or `admit` means they take part;
+     * `read` means they watch.
+     */
+    access?: GrantAccessKind;
+}
+/** One principal who takes part in the room. */
+export interface ChatParticipantRow {
+    id: string;
+    type: 'user' | 'agent' | 'org';
+    via: Array<Extract<ChatRosterVia, {
+        kind: 'grant';
+    }>>;
+    /** Always present here: a participant is a holder of `write` or stronger. */
+    access?: GrantAccessKind;
+}
+/**
+ * Flat projection of the participant list.
+ *
+ * An agent participates in its own name, so it appears as both ids: an agent's
+ * owner is not automatically in the room with it.
+ */
+export interface ChatMemberView {
+    principalId: string;
+    agentId: string | null;
+    /**
+     * Present when the room shows this member through a persona. The ids above
+     * are then the exposed ones, not the underlying principal.
+     */
+    presentation?: PrincipalPresentation;
+    /** The viewer cannot tell which of several representations is speaking. */
+    representationAmbiguous?: boolean;
+}
+/** Max characters of a last-message snippet. */
+export declare const CHAT_SNIPPET_CAP = 280;
+/** Newest message in a room, enough to tell entries apart at a glance. */
+export interface ChatLastMessage {
+    /** Sender id (user, agent, service, or system). */
+    sender: string;
+    /** ISO timestamp of the message. */
+    at: string;
+    /** Message text truncated to {@link CHAT_SNIPPET_CAP}. */
+    snippet: string;
+}
+/** One room as an external read returns it. Never a raw stored document. */
+export interface ChatReadDto {
+    chatId: string;
+    /** Flat projection of `participantSummary`, for clients that read it. */
+    members: ChatMemberView[];
+    /**
+     * Complete display roster derived from members, agreement links, grants,
+     * spaces, and services. It is never an authorization input.
+     */
+    rosterSummary: ChatRosterRow[];
+    /** Same canonical participant answer used by server-side delivery. */
+    participantSummary: ChatParticipantRow[];
+    /** Next grant-expiry transition for `participantSummary`, if any. */
+    participantsRefreshAt: string | null;
+    /**
+     * What kind of name this room is reached by, when it has one. The kind only:
+     * a `pair` key names both principals, and principal ids are what the persona
+     * border masks.
+     */
+    addressKind: ChatAddressKind | null;
+    /** Human-readable name so entries can be told apart at a glance. */
+    name: string;
+    /** Recency for sorting and triage. Null when the chat has no messages. */
+    updatedAt: string | null;
+    /** Newest-message snippet. Absent when the chat has no messages. */
+    lastMessage?: ChatLastMessage;
+    /**
+     * Unread messages for the reader, capped at 99 so a badge can render "99+".
+     * Attached by the list read; absent on reads that do not resolve it.
+     */
+    unreadCount?: number;
+}
+/**
+ * The sender of a message as the wire carries it.
+ *
+ * The own-side fields are deliberately absent across an org boundary — read
+ * them as "not disclosed here", never as "no value".
+ */
+export interface MessageSenderWire {
+    id: string;
+    type: MessageSenderType;
+    /** Own-side/audit only. Deliberately absent across the org boundary. */
+    underAgreementId?: string | null;
+    /** Own-side/audit only. Deliberately absent across the org boundary. */
+    presentedAs?: string | null;
+    /** Own-side/audit only. Deliberately absent across the org boundary. */
+    actedBy?: string | null;
+    persona?: {
+        id: string;
+        name: string;
+        image: string | null;
+    } | null;
+    /** Canonical presentation contract. Subject/actor exist only own-side. */
+    presentation?: {
+        ref: string;
+        personaId: string;
+        revision: number;
+        name: string;
+        image: string | null;
+        badge: 'persona';
+        mode: 'persona' | 'chain';
+        subject?: {
+            id: string;
+            type: MessageSenderType;
+        };
+        actor?: {
+            id: string;
+            type: string;
+            mode: string;
+        };
+    } | null;
+}
+/**
+ * Structured payload written alongside a message (task snapshots, service
+ * results, agreement-lifecycle stamps). Stored content, passed through as-is.
+ */
+export interface MessageServicePayload {
+    task?: unknown;
+    id?: string;
+    name?: string;
+    operation?: string;
+    result?: unknown;
+    error?: string;
+    /**
+     * Agreement-lifecycle notifications persist the acting agreement here so a
+     * reader can resolve the lifecycle transition without a second read.
+     */
+    agreement?: unknown;
+    agreementId?: string;
+}
+/**
+ * One message as the wire carries it.
+ *
+ * Timestamps are ISO strings here. A server-side read model may hold them as
+ * dates; nothing outside the server ever sees that.
+ */
+export interface MessageWireDto {
+    messageId: string | null;
+    chatId: string;
+    text: string;
+    sender: MessageSenderWire;
+    receiver: {
+        id: string;
+        type: MessageSenderType;
+    };
+    entryType: string;
+    contentType: string;
+    timestamp: string;
+    sentTimestamp?: string;
+    service?: MessageServicePayload;
+}
+/**
+ * `GET /chats?withMessages=true`.
+ *
+ * `messages` is flat across rooms — the last page per room — and `hasMore` and
+ * `nextCursor` are keyed by chat id. Without the flag the response still has
+ * this shape, with `messages: []` and empty maps.
+ */
+export interface ChatListResponse {
+    chats: ChatReadDto[];
+    messages: MessageWireDto[];
+    hasMore: Record<string, boolean>;
+    /** Where a backward read continues from, per chat. */
+    nextCursor: Record<string, string | null>;
+}
+/**
+ * `GET /chats/:chatId/messages`.
+ *
+ * One backward page, oldest-to-newest within the page; `nextCursor` reads
+ * older.
+ */
+export interface MessagesPage {
+    messages: MessageWireDto[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** `POST /chats/:chatId/messages`. */
+export interface SendChatMessageBody {
+    /**
+     * Client-generated idempotency key. The server dedupes on
+     * `(chatId, messageId)`, so a retry that re-sends the same key collapses to
+     * a single stored row.
+     */
+    messageId: string;
+    text: string;
+    entryType: 'message';
+    contentType: 'text';
+}
+/**
+ * `POST /chats/:chatId/read` — advance the person's read watermark.
+ *
+ * An empty body marks to the latest message.
+ */
+export interface MarkChatReadBody {
+    messageId?: string;
+}

package/dist/chat.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAT_SNIPPET_CAP = void 0;
+/** Max characters of a last-message snippet. */
+exports.CHAT_SNIPPET_CAP = 280;

package/dist/error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one error shape the API answers in.
+ *
+ * Every handler error is rendered as this body with an HTTP status, so a
+ * client can render the real message instead of a boolean.
+ */
+export interface ApiErrorBody {
+    error: string;
+}
+/** True when a response body is the API's error shape. */
+export declare function isApiErrorBody(body: unknown): body is ApiErrorBody;

package/dist/error.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isApiErrorBody = isApiErrorBody;
+/** True when a response body is the API's error shape. */
+function isApiErrorBody(body) {
+    return (typeof body === 'object' &&
+        body !== null &&
+        typeof body.error === 'string');
+}

package/dist/inbox.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The human inbox: what is waiting on the signed-in person, and how a surface
+ * marks it seen.
+ *
+ * This is a different surface from the agent work protocol. An agent reads its
+ * assigned work through `GET /inbox` with per-reader watermarks and ack
+ * windows; a person's mark is `seen`, not `handled`.
+ */
+import type { InboxPartyKind, DecisionKind, ResourceKind } from './vocabulary';
+/**
+ * How to act on a decision.
+ *
+ * Carried per row, fully resolved, so a client never hardcodes the mapping
+ * from kind to write path and never has to fill in a party id itself. The
+ * attention read adds no write endpoints of its own — deciding still happens
+ * on the surfaces that already own each object, and this field is how the
+ * caller finds them.
+ */
+export interface DecideVia {
+    method: 'PUT' | 'POST';
+    path: string;
+}
+/**
+ * One thing waiting on the signed-in person, in the shape a card needs.
+ *
+ * Deliberately one merged type rather than three arrays: the caller's job is
+ * to render "what needs me" as a single list, and merging on the client would
+ * mean every client reimplements the same sort.
+ */
+export interface DecisionRef {
+    kind: DecisionKind;
+    /** agreementId, or approvalId for a spend. Unique within a kind. */
+    id: string;
+    /** What it is, in the counterparty's own words where there are any. */
+    title: string;
+    /** Who is asking. Labels, never account or agent ids. */
+    requestedByDisplayName: string | null;
+    requestedByOrgName: string | null;
+    requestedAt: string | null;
+    /**
+     * Money at stake in cents: an agreement's price, or the amount a paused
+     * transfer would move. Null when nothing is owed.
+     */
+    amountCents: number | null;
+    /** Present where the object expires on its own, e.g. a spend approval. */
+    expiresAt: string | null;
+    decideVia: DecideVia;
+}
+/**
+ * One row in the reader's merged view. A reference, never content — following
+ * it (a chat read, a task read) is where the caller's grants are enforced.
+ *
+ * "Is this mine to act on" is `assigneeId === my agent id`, nothing else. A
+ * row without that stamp is context the reader may open, never a wake.
+ */
+export interface InboxDeliveryRef {
+    /**
+     * Which vocabulary this row speaks — the same list the emitting event and
+     * the stored delivery enum use. Typed rather than `string` so a consumer's
+     * switch over it can be exhaustive: a delivery kind nobody handles is how a
+     * deliverable gets acked unread.
+     */
+    kind: ResourceKind;
+    resourceId: string;
+    /** One emit, one id — collapse copies of the same event on this. */
+    eventId: string;
+    /** The mailbox this copy lives in. */
+    partyId: string;
+    partyKind: InboxPartyKind;
+    /** The ONE agent stamped to act; null when nothing has to. */
+    assigneeId: string | null;
+    /** The owner's human should see this. */
+    needsHuman: boolean;
+    chatId: string | null;
+    agreementId: string | null;
+    taskId: string | null;
+    /** ISO instant of the event; the axis `ackTo` moves along. */
+    ts: string;
+    /**
+     * Who wrote the event (claimer or buyer on store claims, responder on
+     * approve). Null on older rows and system emits.
+     */
+    actorId: string | null;
+    /**
+     * Emitter lifecycle hint when present (e.g. a fulfilled or rejected
+     * connection request). Older rows omit it; treat absent as an unspecified
+     * doorbell.
+     */
+    reason?: string | null;
+    /** Connection to use after a fulfilled first-hop request. */
+    connectionId?: string | null;
+    /** Grant minted for the requesting agent on fulfill. */
+    grantId?: string | null;
+}
+/**
+ * One thing on the person, from whichever writer owns it.
+ *
+ * Two writers, one list: the decisions read says what is waiting and how to
+ * answer it, the party mailboxes say what landed. Both are "this is on you",
+ * so the merge happens once on the server rather than in every client — two
+ * clients merging the same two reads is two totals that can disagree, with
+ * nobody to arbitrate.
+ */
+export type AttentionEntry = {
+    /** Stable per row, so a list can key on it without inventing one. */
+    key: string;
+    /** When it arrived; null on a decision the source never timestamped. */
+    at: string | null;
+    source: 'decision';
+    decision: DecisionRef;
+} | {
+    key: string;
+    at: string;
+    source: 'notice';
+    notice: InboxDeliveryRef;
+};
+/** How many notice rows one attention window can carry. */
+export declare const INBOX_ATTENTION_NOTICE_CAP = 50;
+/**
+ * `GET /inbox/attention` — what needs an answer, then what needs eyes.
+ *
+ * A window onto the one party-owned log, not a log of its own. Three rules
+ * hold it to that:
+ *   • `message` rows never appear — the room renders conversation and counts
+ *     its own unread, and a second count here is the disagreement this merge
+ *     exists to prevent. They are excluded server-side, so they are not
+ *     counted here either.
+ *   • Workspace scoped. A lane fences a window; the unfiltered human log at
+ *     `GET /inbox/feed` stays cross-org and is not what an app reads.
+ *   • `seenTo` covers ONLY the notice rows this response actually carried, so
+ *     marking seen can never advance past mail no surface displayed.
+ */
+export interface AttentionFeed {
+    asOf: string;
+    /** Decisions first — somebody is blocked on those — then notices, newest first. */
+    items: AttentionEntry[];
+    /** Decisions the server capped. Nothing local can expand into them. */
+    truncated: number;
+    /** Older unseen notice rows exist past the cap; they stay unseen. */
+    hasMore: boolean;
+    /**
+     * Opaque token for `POST /inbox/seen`, covering the notice rows above and
+     * nothing else. Null when the block carried no notices. Never constructed
+     * or parsed by a client.
+     */
+    seenTo: string | null;
+}
+/**
+ * `POST /inbox/seen`.
+ *
+ * `upTo` is the `seenTo` token from the attention window being marked — pass
+ * it back verbatim.
+ */
+export interface MarkInboxSeenBody {
+    upTo: string;
+}

package/dist/inbox.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INBOX_ATTENTION_NOTICE_CAP = void 0;
+/** How many notice rows one attention window can carry. */
+exports.INBOX_ATTENTION_NOTICE_CAP = 50;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wire contracts for the Ziggs API.
+ *
+ * The server is authoritative: every shape here is what it actually sends or
+ * accepts. Nothing in this package reaches the network or reads an
+ * environment — it is types plus the closed vocabularies they are built from,
+ * so any runtime can import it.
+ */
+export * from './vocabulary';
+export * from './chat';
+export * from './inbox';
+export * from './error';
+export * from './socket';

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wire contracts for the Ziggs API.
+ *
+ * The server is authoritative: every shape here is what it actually sends or
+ * accepts. Nothing in this package reaches the network or reads an
+ * environment — it is types plus the closed vocabularies they are built from,
+ * so any runtime can import it.
+ */
+__exportStar(require("./vocabulary"), exports);
+__exportStar(require("./chat"), exports);
+__exportStar(require("./inbox"), exports);
+__exportStar(require("./error"), exports);
+__exportStar(require("./socket"), exports);

package/dist/socket.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Socket contracts.
+ *
+ * The socket is a receive-only accelerator: every frame here has an HTTP read
+ * that is the source of truth. A client that misses a frame catches up on its
+ * next read; a client that trusts a frame over the read will disagree with the
+ * server.
+ */
+import type { MessageWireDto } from './chat';
+import type { ResourceKind } from './vocabulary';
+/**
+ * A resource changed somewhere the reader can see.
+ *
+ * Deliberately minimal — no body content — so cross-party visibility questions
+ * are decided by the reader's subsequent authorized read, not by what shipped
+ * on the wire.
+ */
+export interface ResourceChangedFrame {
+    kind: ResourceKind;
+    /**
+     * One emit, one id. Every party copy of the event shares it, so a reader
+     * whose grants reach two parties of the same event can collapse the copies
+     * instead of seeing doubles.
+     */
+    eventId?: string;
+    /** ISO timestamp set by the emitter. */
+    ts: string;
+    /** Primary id of the resource that changed. */
+    resourceId: string;
+    chatId?: string;
+    agreementId?: string;
+    taskId?: string;
+    /** Coarse change marker. */
+    change?: 'created' | 'updated' | 'state-changed';
+    /**
+     * Principal whose action produced this event, when the emit site knows it.
+     * Agents are not woken by their own writes; people still receive their own
+     * events, because a surface re-syncs from them.
+     */
+    actorId?: string;
+    /** Lifecycle hint for a client (e.g. a proposal that was approved). */
+    reason?: string;
+    /** Connection to plug into after a fulfilled first-hop request. */
+    connectionId?: string;
+    /** Grant minted for the requesting agent on fulfill. */
+    grantId?: string;
+    orgId?: string | null;
+    /** Artifact visibility, when the event is about one. */
+    visibility?: 'chat' | 'public' | 'agent-private';
+}
+/** A message landed in a room the reader is in. */
+export type ChatMessageNewFrame = MessageWireDto;
+/**
+ * The reader advanced their own watermark somewhere else.
+ *
+ * Fanned out to a person's other live sessions so an unread badge clears on
+ * their other tabs and devices. Best-effort — the watermark row is the source
+ * of truth.
+ */
+export interface ChatReadFrame {
+    chatId: string;
+    lastReadAt: string;
+    lastReadMessageId: string | null;
+}
+/**
+ * Every frame a client receives, keyed by its wire name.
+ *
+ * Written as a map so a client can type one listener registry over it and be
+ * told when a frame it handles changes shape.
+ */
+export interface ServerToClientEvents {
+    'chat:message:new': ChatMessageNewFrame;
+    'chat:read': ChatReadFrame;
+    resource_changed: ResourceChangedFrame;
+}
+/** Every frame a client sends. */
+export interface ClientToServerEvents {
+    'chat:join': string;
+}
+/** Wire names of the frames a client receives. */
+export declare const SERVER_EVENTS: {
+    readonly chatMessageNew: "chat:message:new";
+    readonly chatRead: "chat:read";
+    readonly resourceChanged: "resource_changed";
+};
+/** Wire names of the frames a client sends. */
+export declare const CLIENT_EVENTS: {
+    readonly chatJoin: "chat:join";
+};

package/dist/socket.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_EVENTS = exports.SERVER_EVENTS = void 0;
+/** Wire names of the frames a client receives. */
+exports.SERVER_EVENTS = {
+    chatMessageNew: 'chat:message:new',
+    chatRead: 'chat:read',
+    resourceChanged: 'resource_changed',
+};
+/** Wire names of the frames a client sends. */
+exports.CLIENT_EVENTS = {
+    chatJoin: 'chat:join',
+};

package/dist/vocabulary.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The small closed vocabularies every other contract in this package speaks.
+ *
+ * These are value lists rather than bare unions because each one crosses a
+ * boundary where the values must exist at runtime: a socket frame, a stored
+ * enum, a switch a consumer needs to make exhaustive.
+ */
+/**
+ * What a grant lets its holder do with the scope.
+ *
+ * Ordered weakest to strongest, and the order is load-bearing: `write` implies
+ * `read`, `admit` implies both. A required kind is satisfied by any kind at
+ * least that strong.
+ *
+ *  - `read`   — see the scope and its contents. Observing, not participating.
+ *  - `write`  — take part: post entries, be a delivery participant.
+ *  - `admit`  — bring others in: issue grants on this scope to new holders.
+ */
+export declare const GRANT_ACCESS_KINDS: readonly ["read", "write", "admit"];
+export type GrantAccessKind = (typeof GRANT_ACCESS_KINDS)[number];
+/**
+ * The name a room can be reached by, when it has one.
+ *
+ * Most rooms have no address. What makes two opens land in the same room is
+ * that they name the same thing — a pair of principals, or an org.
+ */
+export declare const CHAT_ADDRESS_KINDS: readonly ["pair", "org"];
+export type ChatAddressKind = (typeof CHAT_ADDRESS_KINDS)[number];
+/**
+ * The kinds a resource-change event — and therefore a durable delivery row —
+ * can be. A consumer that switches on this can be made exhaustive.
+ */
+export declare const RESOURCE_KINDS: readonly ["message", "artifact", "task-state", "agreement", "request"];
+export type ResourceKind = (typeof RESOURCE_KINDS)[number];
+/** What kind of thing is waiting on a person. */
+export type DecisionKind = 'proposal' | 'connection_request' | 'spend_approval';
+/** Which mailbox a delivery copy lives in. */
+export type InboxPartyKind = 'human' | 'org';
+/** How a principal is party to an agreement. */
+export type PartyRole = 'payer' | 'provider' | 'creator' | 'proposedTo' | 'providerPrincipal';
+/** What kind of principal sent a message. */
+export type MessageSenderType = 'user' | 'agent' | 'service' | 'system';

package/dist/vocabulary.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * The small closed vocabularies every other contract in this package speaks.
+ *
+ * These are value lists rather than bare unions because each one crosses a
+ * boundary where the values must exist at runtime: a socket frame, a stored
+ * enum, a switch a consumer needs to make exhaustive.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCE_KINDS = exports.CHAT_ADDRESS_KINDS = exports.GRANT_ACCESS_KINDS = void 0;
+/**
+ * What a grant lets its holder do with the scope.
+ *
+ * Ordered weakest to strongest, and the order is load-bearing: `write` implies
+ * `read`, `admit` implies both. A required kind is satisfied by any kind at
+ * least that strong.
+ *
+ *  - `read`   — see the scope and its contents. Observing, not participating.
+ *  - `write`  — take part: post entries, be a delivery participant.
+ *  - `admit`  — bring others in: issue grants on this scope to new holders.
+ */
+exports.GRANT_ACCESS_KINDS = ['read', 'write', 'admit'];
+/**
+ * The name a room can be reached by, when it has one.
+ *
+ * Most rooms have no address. What makes two opens land in the same room is
+ * that they name the same thing — a pair of principals, or an org.
+ */
+exports.CHAT_ADDRESS_KINDS = ['pair', 'org'];
+/**
+ * The kinds a resource-change event — and therefore a durable delivery row —
+ * can be. A consumer that switches on this can be made exhaustive.
+ */
+exports.RESOURCE_KINDS = [
+    'message',
+    'artifact',
+    'task-state',
+    'agreement',
+    /** Marketplace request doorbell: a typed inbox channel, not a chat. */
+    'request',
+];

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ziggs-ai/contracts",
+  "version": "0.1.0",
+  "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "rm -rf dist && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ziggs",
+    "contracts",
+    "types"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}