@ziggs-ai/contracts 0.50.4 → 0.50.8

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/README.md CHANGED
@@ -21,6 +21,8 @@ import { SERVER_EVENTS, isApiErrorBody } from '@ziggs-ai/contracts';
21
21
  | `error` | the one error body every handler answers in |
22
22
  | `socket` | frame names and payloads, both directions |
23
23
  | `vocabulary` | the closed value lists the above are built from |
24
+ | `messaging` | message commands, records, thread pages, closed-in-thread |
25
+ | `buckets` | brains: views, contents, items, shares |
24
26
 
25
27
  ## The server is authoritative
26
28
 
@@ -0,0 +1,3 @@
1
+ import type { AgreementRead } from './generated/agreements';
2
+ /** The grant request on an agreement read, when it carries one. */
3
+ export type AgreementGrantRequest = NonNullable<AgreementRead['grantRequest']>;
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -0,0 +1,154 @@
1
+ /** Wire shapes for buckets (brains). A bucket stores pointers, never permission. */
2
+ export declare const BUCKET_ITEM_KINDS: readonly ["message", "artifact", "task", "bucket"];
3
+ export type BucketItemKind = (typeof BUCKET_ITEM_KINDS)[number];
4
+ export interface BucketItemRef {
5
+ kind: BucketItemKind;
6
+ id: string;
7
+ }
8
+ export type BucketLook = {
9
+ icon: string | null;
10
+ color: string | null;
11
+ };
12
+ export interface BucketPerson {
13
+ id: string;
14
+ kind: 'user' | 'agent' | 'org';
15
+ name: string | null;
16
+ faceId: string | null;
17
+ image: string | null;
18
+ }
19
+ /** GET /buckets and every write that returns the bucket. */
20
+ export interface BucketView {
21
+ bucketId: string;
22
+ name: string;
23
+ createdBy: string;
24
+ audience: string[];
25
+ revision: number;
26
+ itemCount: number;
27
+ createdAt: string | null;
28
+ /** How it looks as a brain; null or missing is plain. */
29
+ look?: BucketLook | null;
30
+ people?: BucketPerson[];
31
+ }
32
+ /** Alias used by the web app. */
33
+ export type Bucket = BucketView;
34
+ export type BucketMisfit = {
35
+ item: BucketItemRef;
36
+ reason: 'you-cannot-read';
37
+ } | {
38
+ item: BucketItemRef;
39
+ reason: 'members-cannot-read';
40
+ memberIds: string[];
41
+ };
42
+ export type BucketShare = {
43
+ item: BucketItemRef;
44
+ holderId: string;
45
+ outcome: 'shared' | 'pending' | 'refused';
46
+ ownerId?: string;
47
+ ownerName?: string | null;
48
+ agreementId?: string | null;
49
+ reason?: string;
50
+ };
51
+ export interface BucketInsertResult {
52
+ bucket: BucketView;
53
+ inserted: BucketItemRef[];
54
+ alreadyIn: BucketItemRef[];
55
+ misfits: BucketMisfit[];
56
+ shared: BucketShare[];
57
+ }
58
+ export interface BucketAddMembersResult {
59
+ bucket: BucketView;
60
+ added: string[];
61
+ waiting?: string[];
62
+ shared: BucketShare[];
63
+ split: {
64
+ bucket: BucketView;
65
+ items: BucketItemRef[];
66
+ } | null;
67
+ }
68
+ export type BucketThread = {
69
+ rootMessageId: string;
70
+ title: string;
71
+ messageCount: number;
72
+ lastAt: string | null;
73
+ yours: boolean;
74
+ /** The thread holding the message asked about as `current`. */
75
+ current?: boolean;
76
+ recent?: Array<{
77
+ messageId: string;
78
+ from: string;
79
+ text: string;
80
+ at: string;
81
+ }>;
82
+ };
83
+ export type BucketInvite = {
84
+ agreementId: string;
85
+ title: string | null;
86
+ waitingFor: string[];
87
+ };
88
+ export type BucketWaitingPerson = {
89
+ principalId: string;
90
+ addedBy: string;
91
+ owners: Array<{
92
+ ownerId: string;
93
+ items: number;
94
+ answer: 'asked' | 'yes' | 'no';
95
+ }>;
96
+ };
97
+ export type BucketConnection = {
98
+ connectionId: string;
99
+ provider: string;
100
+ account: string | null;
101
+ ownerId: string;
102
+ yours: boolean;
103
+ waiting: string[];
104
+ };
105
+ export type SilentAgent = {
106
+ agentId: string;
107
+ outside: string[];
108
+ agreementId?: string;
109
+ };
110
+ export type AgentHire = {
111
+ agentId: string;
112
+ agreementId: string;
113
+ };
114
+ export interface BucketContents {
115
+ bucket: Pick<BucketView, 'bucketId' | 'name' | 'audience' | 'revision'>;
116
+ threads: BucketThread[];
117
+ artifacts: Array<{
118
+ artifactId: string;
119
+ name: string | null;
120
+ }>;
121
+ tasks: Array<{
122
+ taskId: string;
123
+ title: string;
124
+ state: string;
125
+ }>;
126
+ agreements: Array<{
127
+ agreementId: string;
128
+ title: string;
129
+ status: string;
130
+ }>;
131
+ invites?: BucketInvite[];
132
+ waiting?: BucketWaitingPerson[];
133
+ outOfReach: number;
134
+ nextCursor?: string | null;
135
+ silentAgents?: SilentAgent[];
136
+ agentHires?: AgentHire[];
137
+ connections?: BucketConnection[];
138
+ children?: Array<{
139
+ bucketId: string;
140
+ name: string;
141
+ }>;
142
+ parents?: Array<{
143
+ bucketId: string;
144
+ name: string;
145
+ }>;
146
+ }
147
+ export interface BucketItemPage {
148
+ items: Array<BucketItemRef & {
149
+ addedBy: string;
150
+ addedAt: string | null;
151
+ }>;
152
+ outOfReach: BucketMisfit[];
153
+ nextCursor: string | null;
154
+ }
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ /** Wire shapes for buckets (brains). A bucket stores pointers, never permission. */
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.BUCKET_ITEM_KINDS = void 0;
5
+ exports.BUCKET_ITEM_KINDS = [
6
+ 'message',
7
+ 'artifact',
8
+ 'task',
9
+ 'bucket',
10
+ ];
package/dist/index.d.ts CHANGED
@@ -20,8 +20,10 @@ export * from './generated/payments';
20
20
  export * from './generated/connections';
21
21
  export * from './generated/agreements';
22
22
  export * from './generated/artifacts';
23
+ export * from './agreement-grant-request';
23
24
  export * from './identifiers';
24
25
  export * from './execution';
25
26
  export * from './messaging';
27
+ export * from './buckets';
26
28
  export * from './actions';
27
29
  export { parseMessageCommand } from './message-command';
package/dist/index.js CHANGED
@@ -38,9 +38,11 @@ __exportStar(require("./generated/payments"), exports);
38
38
  __exportStar(require("./generated/connections"), exports);
39
39
  __exportStar(require("./generated/agreements"), exports);
40
40
  __exportStar(require("./generated/artifacts"), exports);
41
+ __exportStar(require("./agreement-grant-request"), exports);
41
42
  __exportStar(require("./identifiers"), exports);
42
43
  __exportStar(require("./execution"), exports);
43
44
  __exportStar(require("./messaging"), exports);
45
+ __exportStar(require("./buckets"), exports);
44
46
  __exportStar(require("./actions"), exports);
45
47
  var message_command_1 = require("./message-command");
46
48
  Object.defineProperty(exports, "parseMessageCommand", { enumerable: true, get: function () { return message_command_1.parseMessageCommand; } });
@@ -95,6 +95,57 @@ function source(value) {
95
95
  return fail('source kind');
96
96
  }
97
97
  }
98
+ const NAME = /^[A-Za-z0-9_.:-]{1,80}$/;
99
+ function formName(value, field) {
100
+ if (typeof value !== 'string' || !NAME.test(value))
101
+ return fail(`${field}: letters, digits, _ . : - up to 80`);
102
+ return value;
103
+ }
104
+ function pageForm(value) {
105
+ const row = object(value, ['name', 'fields'], 'form');
106
+ const fields = list(row.fields, (item) => {
107
+ const f = object(item, ['name', 'label', 'choices', 'freeText'], 'form field');
108
+ const choices = f.choices === undefined
109
+ ? undefined
110
+ : list(f.choices, (c) => id(c, 'form field choice', 200), 'form field choices', 50);
111
+ if (f.freeText !== undefined && typeof f.freeText !== 'boolean')
112
+ return fail('form field freeText: true or false');
113
+ return {
114
+ name: formName(f.name, 'form field name'),
115
+ ...(f.label !== undefined
116
+ ? { label: id(f.label, 'form field label', 300) }
117
+ : {}),
118
+ ...(choices ? { choices } : {}),
119
+ ...(f.freeText !== undefined ? { freeText: f.freeText } : {}),
120
+ };
121
+ }, 'form fields', 100);
122
+ if (new Set(fields.map((f) => f.name)).size !== fields.length)
123
+ return fail('form fields: duplicate name');
124
+ return { name: formName(row.name, 'form name'), fields };
125
+ }
126
+ function formValue(value, field) {
127
+ if (value === null ||
128
+ typeof value === 'boolean' ||
129
+ (typeof value === 'number' && Number.isFinite(value)))
130
+ return value;
131
+ if (typeof value === 'string' && value.length <= 10000)
132
+ return value;
133
+ return fail(`${field}: a string, number, true/false or null`);
134
+ }
135
+ function formEntry(value) {
136
+ const row = object(value, ['form', 'fields'], 'form entry');
137
+ if (!row.fields ||
138
+ typeof row.fields !== 'object' ||
139
+ Array.isArray(row.fields))
140
+ return fail('form entry fields: an object of field name to value');
141
+ const entries = Object.entries(row.fields);
142
+ if (entries.length > 100)
143
+ return fail('form entry fields: at most 100');
144
+ const fields = {};
145
+ for (const [key, v] of entries)
146
+ fields[formName(key, 'form entry field name')] = formValue(v, `form entry field "${key}"`);
147
+ return { form: formName(row.form, 'form entry form'), fields };
148
+ }
98
149
  /** Strict at every nesting level: identity/authority cannot enter via page JSON. */
99
150
  function parseMessageCommand(value) {
100
151
  const row = object(value, [
@@ -107,6 +158,8 @@ function parseMessageCommand(value) {
107
158
  'mandate',
108
159
  'relationships',
109
160
  'page',
161
+ 'forms',
162
+ 'formEntry',
110
163
  ], 'message command');
111
164
  const content = object(row.content, ['text'], 'content');
112
165
  const audience = object(row.audience, ['kind', 'principalIds'], 'audience');
@@ -136,6 +189,15 @@ function parseMessageCommand(value) {
136
189
  command.sources = list(row.sources, source, 'sources', 50);
137
190
  if (row.page !== undefined)
138
191
  command.page = exactArtifact(row.page);
192
+ if (row.forms !== undefined) {
193
+ if (!command.page)
194
+ return fail('forms: only with page');
195
+ command.forms = list(row.forms, pageForm, 'forms', 20);
196
+ if (new Set(command.forms.map((f) => f.name)).size !== command.forms.length)
197
+ return fail('forms: duplicate name');
198
+ }
199
+ if (row.formEntry !== undefined)
200
+ command.formEntry = formEntry(row.formEntry);
139
201
  if (row.mandate !== undefined) {
140
202
  const mandate = object(row.mandate, ['agreementId', 'taskId'], 'mandate');
141
203
  command.mandate = {
@@ -159,5 +221,9 @@ function parseMessageCommand(value) {
159
221
  : {}),
160
222
  };
161
223
  }
224
+ if (command.formEntry && !command.relationships?.replyToMessageId)
225
+ return fail('formEntry: reply to the page version it was filled on (relationships.replyToMessageId)');
226
+ if (command.formEntry && command.page)
227
+ return fail('formEntry: an entry carries no page');
162
228
  return command;
163
229
  }
@@ -61,6 +61,44 @@ export type MessageDeliveries = {
61
61
  kind: 'explicit';
62
62
  principalIds: string[];
63
63
  };
64
+ /**
65
+ * One field of a page's form. A field with `choices` takes one of them; with
66
+ * `freeText` it also takes any text. A field with neither takes any value.
67
+ */
68
+ export interface PageFormField {
69
+ name: string;
70
+ label?: string;
71
+ choices?: string[];
72
+ freeText?: boolean;
73
+ }
74
+ /** A form a page carries: declared on the message that carries the page. */
75
+ export interface PageForm {
76
+ name: string;
77
+ fields: PageFormField[];
78
+ }
79
+ export type FormFieldValue = string | number | boolean | null;
80
+ /**
81
+ * ZIG-2452 — the page a thread shows, as the server names it. `messageId`,
82
+ * `page` and `author` are those of the newest version the poster's side sent;
83
+ * all three are null and `closed` is true when the viewer cannot read that
84
+ * version, so no read names a message the viewer cannot read. `versions` are
85
+ * the versions the viewer can read, oldest first, numbered in the thread.
86
+ */
87
+ export interface CurrentPage {
88
+ messageId: string | null;
89
+ page: ExactArtifactRef | null;
90
+ author: MessageEndpoint | null;
91
+ versions: Array<{
92
+ number: number;
93
+ messageId: string;
94
+ }>;
95
+ closed?: boolean;
96
+ }
97
+ /** One filled-in form: a reply to the page version it was filled on. */
98
+ export interface FormEntry {
99
+ form: string;
100
+ fields: Record<string, FormFieldValue>;
101
+ }
64
102
  export interface MessageCommand {
65
103
  /** Authenticated accountable principal scopes this identity. Changed input conflicts. */
66
104
  operationId: string;
@@ -81,6 +119,18 @@ export interface MessageCommand {
81
119
  * names no reply target starts its own thread, even in a wake.
82
120
  */
83
121
  page?: ExactArtifactRef;
122
+ /**
123
+ * The forms the page carries: each form's name, its fields, their choices
124
+ * and which take free text. Only with `page`. Agents and the server read
125
+ * them here, not from the page's HTML.
126
+ */
127
+ forms?: PageForm[];
128
+ /**
129
+ * A form entry: a reply to the page version it was filled on
130
+ * (`relationships.replyToMessageId`). Checked against that version's forms;
131
+ * it goes to the page's poster as a request.
132
+ */
133
+ formEntry?: FormEntry;
84
134
  /** Required when the selected work/spending relies on an agreement. No fallback. */
85
135
  mandate?: {
86
136
  agreementId: string;
@@ -93,6 +143,8 @@ export interface MessageCommand {
93
143
  artifacts?: ExactArtifactRef[];
94
144
  };
95
145
  }
146
+ /** The version a page thread shows. Same wire as `CurrentPage` (ZIG-2452). */
147
+ export type ThreadCurrentPage = CurrentPage;
96
148
  /** One viewer-safe presentation for every message; no work/direct/shared variant. */
97
149
  export interface MessageRecord {
98
150
  messageId: string;
@@ -113,6 +165,10 @@ export interface MessageRecord {
113
165
  intent: MessageIntent;
114
166
  /** The page it carries; null when it carries none, or the viewer cannot read the file. */
115
167
  page: ExactArtifactRef | null;
168
+ /** The forms the page it carries declares. Absent when it declares none. */
169
+ forms?: PageForm[];
170
+ /** Set when this message is a form entry. */
171
+ formEntry?: FormEntry;
116
172
  /**
117
173
  * Set when it carries a page the viewer cannot open: that page's name, so a
118
174
  * client says so instead of showing nothing. Absent otherwise.
@@ -125,10 +181,7 @@ export interface MessageRecord {
125
181
  * newest page the poster's side sent in the thread. `page` is null when the
126
182
  * viewer cannot open that version. Absent outside a page thread.
127
183
  */
128
- currentPage?: {
129
- messageId: string;
130
- page: ExactArtifactRef | null;
131
- };
184
+ currentPage?: CurrentPage;
132
185
  /** The outside channel it arrived through, without its provider reference. */
133
186
  importedFrom: {
134
187
  channel: 'slack' | 'email' | 'github';
@@ -152,6 +205,28 @@ export interface MessageCommandResult {
152
205
  outcome: 'created' | 'existing';
153
206
  message: MessageRecord;
154
207
  }
208
+ /**
209
+ * What in a thread the caller cannot read yet, by whose it is, and whether
210
+ * that owner has been asked. Counts and faces only; nothing closed is shown.
211
+ */
212
+ export interface ClosedInThread {
213
+ owner: {
214
+ id: string | null;
215
+ name: string | null;
216
+ };
217
+ count: number;
218
+ asked: boolean;
219
+ }
220
+ /**
221
+ * A page of GET /messaging/messages (or /replies). `closed` and `currentPage`
222
+ * are on the first page of a named thread, not on a search or a later page.
223
+ */
224
+ export interface MessagePage {
225
+ messages: MessageRecord[];
226
+ nextCursor: string | null;
227
+ closed?: ClosedInThread[];
228
+ currentPage?: CurrentPage | null;
229
+ }
155
230
  /** Optional contact routing configuration owns no history, grants or work. */
156
231
  export interface ContactAlias {
157
232
  aliasId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ziggs-ai/contracts",
3
- "version": "0.50.4",
3
+ "version": "0.50.8",
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",