@ziggs-ai/contracts 0.34.0 → 0.42.0

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.
package/dist/socket.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * next read; a client that trusts a frame over the read will disagree with the
7
7
  * server.
8
8
  */
9
- import type { MessageWireDto } from './chat';
9
+ import type { MessageRecord } from './messaging';
10
10
  import type { ResourceKind } from './vocabulary';
11
11
  /**
12
12
  * A resource changed somewhere the reader can see.
@@ -27,7 +27,7 @@ export interface ResourceChangedFrame {
27
27
  ts: string;
28
28
  /** Primary id of the resource that changed. */
29
29
  resourceId: string;
30
- chatId?: string;
30
+ addressId?: string;
31
31
  agreementId?: string;
32
32
  taskId?: string;
33
33
  /** Coarse change marker. */
@@ -46,10 +46,12 @@ export interface ResourceChangedFrame {
46
46
  grantId?: string;
47
47
  orgId?: string | null;
48
48
  /** Artifact visibility, when the event is about one. */
49
- visibility?: 'chat' | 'public' | 'agent-private';
49
+ visibility?: 'address' | 'public' | 'agent-private';
50
50
  }
51
- /** A message landed in a room the reader is in. */
52
- export type ChatMessageNewFrame = MessageWireDto;
51
+ /** An authorized message arrived. Wire event names remain compatible with released clients. */
52
+ export type MessageNewFrame = MessageRecord;
53
+ /** @deprecated Use MessageNewFrame. */
54
+ export type ChatMessageNewFrame = MessageNewFrame;
53
55
  /**
54
56
  * The reader advanced their own watermark somewhere else.
55
57
  *
@@ -58,7 +60,7 @@ export type ChatMessageNewFrame = MessageWireDto;
58
60
  * of truth.
59
61
  */
60
62
  export interface ChatReadFrame {
61
- chatId: string;
63
+ addressId: string;
62
64
  lastReadAt: string;
63
65
  lastReadMessageId: string | null;
64
66
  }
@@ -74,56 +76,73 @@ export interface AgentLivenessFrame {
74
76
  }
75
77
  /** The roster of a room changed. Clients re-read parties. */
76
78
  export interface ChatParticipantsChangedFrame {
77
- chatIds: string[];
79
+ addressIds: string[];
78
80
  reason?: string;
79
81
  }
80
82
  /**
81
- * Which messages were read. The client sends this; the server fans the same
82
- * shape back out, sometimes with `kind` so a handover is not a human read.
83
+ * Exact-message receipt/invalidation. POST /messaging/messages/seen persists
84
+ * human receipts and emits this to authorized readers and the reader's sessions.
85
+ * Re-read authorized unread projections on receipt; another person's read does
86
+ * not mark your own inbox seen. `kind` distinguishes agent pickup from human read.
83
87
  */
84
- export interface ChatMessageReadFrame {
85
- chatId: string;
88
+ export interface MessageReadFrame {
89
+ addressId?: string;
86
90
  messageIds: string[];
87
91
  kind?: 'agent_handover';
88
92
  }
93
+ /** @deprecated Use MessageReadFrame. */
94
+ export type ChatMessageReadFrame = MessageReadFrame;
89
95
  /**
90
- * ZIG-857 — non-persisted "the agent is working" cue for the room.
96
+ * Non-persisted "the agent is working" cue scoped to exact messages.
91
97
  *
92
98
  * Agents never open a socket (inbox is HTTP). The server emits this when an
93
- * agent picks up chat mail (`working`) so the room is not dead air until the
94
- * first `chat:message:new`. Cleared by `done`, by that agent's next message,
99
+ * agent picks up message deliveries (`working`) until the
100
+ * first `address:message:new`. Cleared by `done`, by that agent's next message,
95
101
  * or by the client after a short idle.
96
102
  */
97
- export interface ChatMessageActivityFrame {
98
- chatId: string;
99
- /** Agent (or person) the indicator is about. */
103
+ export interface MessageActivityFrame {
104
+ /** Optional historical presentation hint; never the authorization scope. */
105
+ addressId?: string;
106
+ messageIds: string[];
107
+ /** Message-scoped endpoint ref, never a raw agent or person identity.
108
+ * Current frames name one message; correlate only within that exact message. */
100
109
  senderId: string;
101
110
  kind: 'working' | 'done';
102
111
  }
112
+ /** @deprecated Use MessageActivityFrame. */
113
+ export type ChatMessageActivityFrame = MessageActivityFrame;
103
114
  export interface ServerToClientEvents {
104
- 'chat:message:new': ChatMessageNewFrame;
105
- 'chat:message:read': ChatMessageReadFrame;
106
- 'chat:message:activity': ChatMessageActivityFrame;
107
- 'chat:read': ChatReadFrame;
108
- 'chat:participants_changed': ChatParticipantsChangedFrame;
115
+ 'address:message:new': MessageNewFrame;
116
+ 'address:message:read': MessageReadFrame;
117
+ 'address:message:activity': MessageActivityFrame;
118
+ 'address:read': ChatReadFrame;
119
+ 'address:participants_changed': ChatParticipantsChangedFrame;
109
120
  'agent:liveness': AgentLivenessFrame;
110
121
  resource_changed: ResourceChangedFrame;
111
122
  }
112
123
  /** Every frame a client sends. Joining a room is not one of them. */
113
124
  export interface ClientToServerEvents {
114
- 'chat:message:read': ChatMessageReadFrame;
125
+ 'address:message:read': MessageReadFrame;
115
126
  }
116
127
  /** Wire names of the frames a client receives. */
117
128
  export declare const SERVER_EVENTS: {
118
- readonly chatMessageNew: "chat:message:new";
119
- readonly chatMessageRead: "chat:message:read";
120
- readonly chatMessageActivity: "chat:message:activity";
121
- readonly chatRead: "chat:read";
122
- readonly chatParticipantsChanged: "chat:participants_changed";
129
+ readonly messageNew: "address:message:new";
130
+ readonly messageRead: "address:message:read";
131
+ readonly messageActivity: "address:message:activity";
132
+ /** @deprecated Use messageNew. */
133
+ readonly chatMessageNew: "address:message:new";
134
+ /** @deprecated Use messageRead. */
135
+ readonly chatMessageRead: "address:message:read";
136
+ /** @deprecated Use messageActivity. */
137
+ readonly chatMessageActivity: "address:message:activity";
138
+ readonly chatRead: "address:read";
139
+ readonly chatParticipantsChanged: "address:participants_changed";
123
140
  readonly agentLiveness: "agent:liveness";
124
141
  readonly resourceChanged: "resource_changed";
125
142
  };
126
143
  /** Wire names of the frames a client sends. */
127
144
  export declare const CLIENT_EVENTS: {
128
- readonly chatMessageRead: "chat:message:read";
145
+ readonly messageRead: "address:message:read";
146
+ /** @deprecated Use messageRead. */
147
+ readonly chatMessageRead: "address:message:read";
129
148
  };
package/dist/socket.js CHANGED
@@ -3,15 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.CLIENT_EVENTS = exports.SERVER_EVENTS = void 0;
4
4
  /** Wire names of the frames a client receives. */
5
5
  exports.SERVER_EVENTS = {
6
- chatMessageNew: 'chat:message:new',
7
- chatMessageRead: 'chat:message:read',
8
- chatMessageActivity: 'chat:message:activity',
9
- chatRead: 'chat:read',
10
- chatParticipantsChanged: 'chat:participants_changed',
6
+ messageNew: 'address:message:new',
7
+ messageRead: 'address:message:read',
8
+ messageActivity: 'address:message:activity',
9
+ /** @deprecated Use messageNew. */
10
+ chatMessageNew: 'address:message:new',
11
+ /** @deprecated Use messageRead. */
12
+ chatMessageRead: 'address:message:read',
13
+ /** @deprecated Use messageActivity. */
14
+ chatMessageActivity: 'address:message:activity',
15
+ chatRead: 'address:read',
16
+ chatParticipantsChanged: 'address:participants_changed',
11
17
  agentLiveness: 'agent:liveness',
12
18
  resourceChanged: 'resource_changed',
13
19
  };
14
20
  /** Wire names of the frames a client sends. */
15
21
  exports.CLIENT_EVENTS = {
16
- chatMessageRead: 'chat:message:read',
22
+ messageRead: 'address:message:read',
23
+ /** @deprecated Use messageRead. */
24
+ chatMessageRead: 'address:message:read',
17
25
  };
@@ -12,24 +12,14 @@
12
12
  * `read`, `admit` implies both. A required kind is satisfied by any kind at
13
13
  * least that strong.
14
14
  *
15
- * - `list` — know that the scope's rooms exist: their names, who is in
16
- * them, last activity. Never their contents. Held only on a
17
- * `person` scope (ZIG-2170), so no room grant ever means less
18
- * than `read`.
15
+ * - `list` — historical person-scope discovery, retained for inspection
16
+ * and revocation of existing grants.
19
17
  * - `read` — see the scope and its contents. Observing, not participating.
20
18
  * - `write` — take part: post entries, be a delivery participant.
21
19
  * - `admit` — bring others in: issue grants on this scope to new holders.
22
20
  */
23
21
  export declare const GRANT_ACCESS_KINDS: readonly ["list", "read", "write", "admit"];
24
22
  export type GrantAccessKind = (typeof GRANT_ACCESS_KINDS)[number];
25
- /**
26
- * The name a room can be reached by, when it has one.
27
- *
28
- * Most rooms have no address. What makes two opens land in the same room is
29
- * that they name the same thing — a pair of principals, or an org.
30
- */
31
- export declare const CHAT_ADDRESS_KINDS: readonly ["pair", "org"];
32
- export type ChatAddressKind = (typeof CHAT_ADDRESS_KINDS)[number];
33
23
  /**
34
24
  * The kinds a resource-change event — and therefore a durable delivery row —
35
25
  * can be. A consumer that switches on this can be made exhaustive.
@@ -124,6 +114,9 @@ export declare const TASK_STATE: {
124
114
  };
125
115
  export type TaskStateValue = (typeof TASK_STATE)[keyof typeof TASK_STATE];
126
116
  export declare const TASK_STATES: readonly TaskStateValue[];
117
+ /** States accepted by PATCH /tasks/:taskId/state. Cancellation has its own command. */
118
+ export type TaskUpdateState = Exclude<TaskStateValue, 'cancelled'>;
119
+ export declare const TASK_UPDATE_STATES: readonly TaskUpdateState[];
127
120
  /** Finished: nothing left to run. */
128
121
  export declare const TERMINAL_TASK_STATES: readonly TaskStateValue[];
129
122
  export declare function isTerminalTaskState(state: string): boolean;
@@ -142,12 +135,12 @@ export declare const AGREEMENT_TERMINAL_STATES: readonly AgreementStatusValue[];
142
135
  * Context-rail scopes, then the other rails a grant can name.
143
136
  * Order is the order the grants read and the OpenAPI enum publish.
144
137
  */
145
- export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "person"];
146
- export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "person", "connection", "wallet", "consent", "inbox"];
138
+ export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person"];
139
+ export declare const GRANT_SCOPE_KINDS: readonly ["message", "address", "agreement", "org", "artifact", "task", "person", "connection", "wallet", "consent", "inbox"];
147
140
  export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
148
141
  export type ContextGrantScopeKind = (typeof CONTEXT_GRANT_SCOPE_KINDS)[number];
149
142
  /** What an access request may name. Always one resource. */
150
- export declare const ACCESS_REQUEST_SCOPE_KINDS: readonly ["artifact", "chat", "agreement", "task", "person"];
143
+ export declare const ACCESS_REQUEST_SCOPE_KINDS: readonly ["message", "artifact", "agreement", "task"];
151
144
  export type AccessRequestScopeKind = (typeof ACCESS_REQUEST_SCOPE_KINDS)[number];
152
145
  /**
153
146
  * Who an artifact access request may ask a grant FOR. Each reader is named
@@ -7,7 +7,7 @@
7
7
  * enum, a switch a consumer needs to make exhaustive.
8
8
  */
9
9
  Object.defineProperty(exports, "__esModule", { value: true });
10
- exports.MESSAGE_CONTENT_TYPES = exports.MESSAGE_CONTENT_TYPE = exports.MAX_ACCESS_REQUEST_HOLDERS = exports.ACCESS_REQUEST_HOLDER_KINDS = exports.ACCESS_REQUEST_SCOPE_KINDS = exports.GRANT_SCOPE_KINDS = exports.CONTEXT_GRANT_SCOPE_KINDS = exports.AGREEMENT_TERMINAL_STATES = exports.AGREEMENT_STATUSES = exports.AGREEMENT_STATUS = exports.TERMINAL_TASK_STATES = exports.TASK_STATES = exports.TASK_STATE = exports.AGREEMENT_ENGAGEMENT_KIND = exports.BROADCAST_TARGETS = exports.COMPANY_AGREEMENT_TARGET = exports.ORG_AGREEMENT_TARGET = exports.OPEN_AGREEMENT_TARGET = exports.AGREEMENT_PARTY_SIDES = exports.ARTIFACT_FILE_FORMATS = exports.ARTIFACT_FILE_FORMAT = exports.RESOURCE_KINDS = exports.CHAT_ADDRESS_KINDS = exports.GRANT_ACCESS_KINDS = void 0;
10
+ exports.MESSAGE_CONTENT_TYPES = exports.MESSAGE_CONTENT_TYPE = exports.MAX_ACCESS_REQUEST_HOLDERS = exports.ACCESS_REQUEST_HOLDER_KINDS = exports.ACCESS_REQUEST_SCOPE_KINDS = exports.GRANT_SCOPE_KINDS = exports.CONTEXT_GRANT_SCOPE_KINDS = exports.AGREEMENT_TERMINAL_STATES = exports.AGREEMENT_STATUSES = exports.AGREEMENT_STATUS = exports.TERMINAL_TASK_STATES = exports.TASK_UPDATE_STATES = exports.TASK_STATES = exports.TASK_STATE = exports.AGREEMENT_ENGAGEMENT_KIND = exports.BROADCAST_TARGETS = exports.COMPANY_AGREEMENT_TARGET = exports.ORG_AGREEMENT_TARGET = exports.OPEN_AGREEMENT_TARGET = exports.AGREEMENT_PARTY_SIDES = exports.ARTIFACT_FILE_FORMATS = exports.ARTIFACT_FILE_FORMAT = exports.RESOURCE_KINDS = exports.GRANT_ACCESS_KINDS = void 0;
11
11
  exports.isBroadcastTarget = isBroadcastTarget;
12
12
  exports.partySideIds = partySideIds;
13
13
  exports.partyActorIds = partyActorIds;
@@ -20,22 +20,13 @@ exports.isTerminalTaskState = isTerminalTaskState;
20
20
  * `read`, `admit` implies both. A required kind is satisfied by any kind at
21
21
  * least that strong.
22
22
  *
23
- * - `list` — know that the scope's rooms exist: their names, who is in
24
- * them, last activity. Never their contents. Held only on a
25
- * `person` scope (ZIG-2170), so no room grant ever means less
26
- * than `read`.
23
+ * - `list` — historical person-scope discovery, retained for inspection
24
+ * and revocation of existing grants.
27
25
  * - `read` — see the scope and its contents. Observing, not participating.
28
26
  * - `write` — take part: post entries, be a delivery participant.
29
27
  * - `admit` — bring others in: issue grants on this scope to new holders.
30
28
  */
31
29
  exports.GRANT_ACCESS_KINDS = ['list', 'read', 'write', 'admit'];
32
- /**
33
- * The name a room can be reached by, when it has one.
34
- *
35
- * Most rooms have no address. What makes two opens land in the same room is
36
- * that they name the same thing — a pair of principals, or an org.
37
- */
38
- exports.CHAT_ADDRESS_KINDS = ['pair', 'org'];
39
30
  /**
40
31
  * The kinds a resource-change event — and therefore a durable delivery row —
41
32
  * can be. A consumer that switches on this can be made exhaustive.
@@ -127,6 +118,11 @@ exports.TASK_STATE = {
127
118
  CANCELLED: 'cancelled',
128
119
  };
129
120
  exports.TASK_STATES = Object.values(exports.TASK_STATE);
121
+ exports.TASK_UPDATE_STATES = [
122
+ exports.TASK_STATE.ACTIVE,
123
+ exports.TASK_STATE.COMPLETED,
124
+ exports.TASK_STATE.FAILED,
125
+ ];
130
126
  /** Finished: nothing left to run. */
131
127
  exports.TERMINAL_TASK_STATES = [
132
128
  exports.TASK_STATE.COMPLETED,
@@ -155,13 +151,14 @@ exports.AGREEMENT_TERMINAL_STATES = [
155
151
  * Order is the order the grants read and the OpenAPI enum publish.
156
152
  */
157
153
  exports.CONTEXT_GRANT_SCOPE_KINDS = [
158
- 'chat',
154
+ 'message',
155
+ // Historical room scopes remain inspectable and revocable.
156
+ 'address',
159
157
  'agreement',
160
158
  'org',
161
159
  'artifact',
162
160
  'task',
163
- // ZIG-2170 — every room one person is in, now and later, and never more
164
- // than that person sees. Held only at `list`.
161
+ // Historical person-wide room discovery. New grants cannot use this scope.
165
162
  'person',
166
163
  ];
167
164
  exports.GRANT_SCOPE_KINDS = [
@@ -173,11 +170,10 @@ exports.GRANT_SCOPE_KINDS = [
173
170
  ];
174
171
  /** What an access request may name. Always one resource. */
175
172
  exports.ACCESS_REQUEST_SCOPE_KINDS = [
173
+ 'message',
176
174
  'artifact',
177
- 'chat',
178
175
  'agreement',
179
176
  'task',
180
- 'person',
181
177
  ];
182
178
  /**
183
179
  * Who an artifact access request may ask a grant FOR. Each reader is named
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ziggs-ai/contracts",
3
- "version": "0.34.0",
3
+ "version": "0.42.0",
4
4
  "description": "Wire contracts for the Ziggs API — response shapes, error body, and socket events, shared by every client.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -1,39 +0,0 @@
1
- /**
2
- * GENERATED from the backend OpenAPI spec — do not edit.
3
- * Family: chatSend. Regenerate: backend 'pnpm docs:generate' then this script.
4
- */
5
- export type ConversationCoverage = {
6
- agreementId: string;
7
- messagesUsed: number;
8
- messageLimit: number | null;
9
- message: string;
10
- };
11
- export type ReceiverResolved = {
12
- how: string;
13
- namedAgentId?: string;
14
- seatedAgentId?: string;
15
- note?: string;
16
- };
17
- export type MessageDestination = {
18
- id: string;
19
- type: string;
20
- };
21
- export type MessageDelivery = {
22
- accepted: boolean;
23
- assignee?: string | null;
24
- reachable?: "yes" | "no";
25
- reason?: string;
26
- lastRead?: string | null;
27
- holdingSession?: string | null;
28
- to: MessageDestination;
29
- broadcast: boolean;
30
- };
31
- export type SendChatMessageResult = {
32
- success: boolean;
33
- message: string;
34
- messageId: string;
35
- chatId: string;
36
- delivery: MessageDelivery;
37
- coverage?: ConversationCoverage;
38
- receiverResolved?: ReceiverResolved;
39
- };
@@ -1,2 +0,0 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });