@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 +2 -0
- package/dist/agreement-grant-request.d.ts +3 -0
- package/dist/agreement-grant-request.js +2 -0
- package/dist/buckets.d.ts +154 -0
- package/dist/buckets.js +10 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/message-command.js +66 -0
- package/dist/messaging.d.ts +79 -4
- package/package.json +1 -1
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,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
|
+
}
|
package/dist/buckets.js
ADDED
|
@@ -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; } });
|
package/dist/message-command.js
CHANGED
|
@@ -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
|
}
|
package/dist/messaging.d.ts
CHANGED
|
@@ -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