@open-artifact/server-sdk 0.2.1 → 0.9.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/package.json +2 -2
- package/src/frame/client/comments.css +1 -1
- package/src/frame/client/comments.js +15 -15
- package/src/frame/comments.d.ts +32 -4
- package/src/frame/comments.js +104 -13
- package/src/frame/index.js +2 -2
package/src/frame/comments.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Comment threads of a frame artifact, in the shared `comments.json` format
|
|
3
3
|
* (version 1) the other Open Artifact types write:
|
|
4
4
|
* `{version: 1, threads: [{id: 'c_…', anchor, label, detail?, location, status, agent?, createdAt, updatedAt,
|
|
5
|
-
* resolvedAt?, messages: [{id: 'm_…', author: {kind, name}, text, at, editedAt?}]}]}`.
|
|
5
|
+
* resolvedAt?, messages: [{id: 'm_…', author: {kind, name}, text, at, editedAt?, to?, reactions?}]}]}`.
|
|
6
6
|
*
|
|
7
7
|
* An original page anchors a comment with its own object; it is kept whole
|
|
8
8
|
* under `location.custom` and `anchor` is its stable JSON text, so the page
|
|
@@ -17,12 +17,23 @@ export interface Author {
|
|
|
17
17
|
name: string;
|
|
18
18
|
}
|
|
19
19
|
export declare const AGENT_AUTHOR: Readonly<Author>;
|
|
20
|
+
/** One person's emoji on a message. */
|
|
21
|
+
export interface MessageReaction {
|
|
22
|
+
emoji: string;
|
|
23
|
+
author: Author;
|
|
24
|
+
at: string;
|
|
25
|
+
}
|
|
20
26
|
export interface CommentMessage {
|
|
21
27
|
id: string;
|
|
22
28
|
author: Author;
|
|
23
29
|
text: string;
|
|
24
30
|
at: string;
|
|
25
31
|
editedAt?: string;
|
|
32
|
+
/** Who the message asks, as the page named them (`agent` asks the agent). */
|
|
33
|
+
to?: string[];
|
|
34
|
+
reactions?: MessageReaction[];
|
|
35
|
+
/** The agent's reply to a message that was sent to it without asking it (no `@agent`): it joined without being asked. */
|
|
36
|
+
joined?: boolean;
|
|
26
37
|
}
|
|
27
38
|
export interface ThreadAgentState {
|
|
28
39
|
status: 'pending' | 'delivered' | 'replied';
|
|
@@ -30,6 +41,8 @@ export interface ThreadAgentState {
|
|
|
30
41
|
deliveredAt?: string;
|
|
31
42
|
repliedAt?: string;
|
|
32
43
|
via?: string;
|
|
44
|
+
/** When a reply that did not ask the agent was sent to it after it had answered; its next reply has `joined`. */
|
|
45
|
+
unaskedAt?: string;
|
|
33
46
|
}
|
|
34
47
|
export interface Thread {
|
|
35
48
|
id: string;
|
|
@@ -42,6 +55,8 @@ export interface Thread {
|
|
|
42
55
|
createdAt: string;
|
|
43
56
|
updatedAt: string;
|
|
44
57
|
resolvedAt?: string;
|
|
58
|
+
/** Who resolved it, while it is resolved. */
|
|
59
|
+
resolvedBy?: Author;
|
|
45
60
|
messages: CommentMessage[];
|
|
46
61
|
}
|
|
47
62
|
interface CommentsDoc {
|
|
@@ -66,21 +81,34 @@ export declare class CommentStore {
|
|
|
66
81
|
detail?: unknown;
|
|
67
82
|
location?: unknown;
|
|
68
83
|
text: unknown;
|
|
84
|
+
to?: unknown;
|
|
69
85
|
author?: Author;
|
|
70
86
|
}): Thread;
|
|
71
|
-
addMessage(threadId: unknown, author: Author, text: unknown, { resolve }?: {
|
|
87
|
+
addMessage(threadId: unknown, author: Author, text: unknown, { resolve, to }?: {
|
|
72
88
|
resolve?: boolean;
|
|
89
|
+
to?: unknown;
|
|
73
90
|
}): {
|
|
74
91
|
thread: Thread;
|
|
75
92
|
message: CommentMessage;
|
|
76
93
|
};
|
|
77
|
-
|
|
94
|
+
/** Changes the text (and recipients, when given) of `author`'s own message. */
|
|
95
|
+
editMessage(threadId: unknown, messageId: unknown, author: Author, text: unknown, to?: unknown): Thread;
|
|
96
|
+
/** Adds (`on`) or takes back `author`'s `emoji` on a message; adding one already there changes nothing. */
|
|
97
|
+
react(threadId: unknown, messageId: unknown, author: Author, emoji: unknown, on: boolean): Thread;
|
|
98
|
+
setResolved(threadId: unknown, resolved: boolean, by?: Author): Thread;
|
|
78
99
|
move(threadId: unknown, anchor: unknown, location?: unknown): Thread;
|
|
79
100
|
remove(threadId: unknown, messageId?: unknown): {
|
|
80
101
|
deleted: 'message' | 'thread';
|
|
81
102
|
};
|
|
82
103
|
markDelivered(threadId: unknown, via: string): Thread;
|
|
83
|
-
|
|
104
|
+
/**
|
|
105
|
+
* Marks the thread sent to the agent. `unasked`: a reply that does not ask the agent, sent because it already took
|
|
106
|
+
* part in the thread; only such a thread can be, and it keeps its status (nothing waits on the agent). One the agent
|
|
107
|
+
* had answered remembers it (`unaskedAt`), so the agent's next reply there is marked `joined`.
|
|
108
|
+
*/
|
|
109
|
+
markSent(threadId: unknown, { unasked }?: {
|
|
110
|
+
unasked?: boolean;
|
|
111
|
+
}): Thread;
|
|
84
112
|
}
|
|
85
113
|
/** What the agent reads of a thread. */
|
|
86
114
|
export declare function agentView(thread: Thread, n?: number): Record<string, unknown>;
|
package/src/frame/comments.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Comment threads of a frame artifact, in the shared `comments.json` format
|
|
3
3
|
* (version 1) the other Open Artifact types write:
|
|
4
4
|
* `{version: 1, threads: [{id: 'c_…', anchor, label, detail?, location, status, agent?, createdAt, updatedAt,
|
|
5
|
-
* resolvedAt?, messages: [{id: 'm_…', author: {kind, name}, text, at, editedAt?}]}]}`.
|
|
5
|
+
* resolvedAt?, messages: [{id: 'm_…', author: {kind, name}, text, at, editedAt?, to?, reactions?}]}]}`.
|
|
6
6
|
*
|
|
7
7
|
* An original page anchors a comment with its own object; it is kept whole
|
|
8
8
|
* under `location.custom` and `anchor` is its stable JSON text, so the page
|
|
@@ -19,6 +19,10 @@ export const TEXT_MAX = 10_000;
|
|
|
19
19
|
const LOCK_STALE_MS = 10_000;
|
|
20
20
|
const LOCK_WAIT_MS = 5_000;
|
|
21
21
|
export const AGENT_AUTHOR = Object.freeze({ kind: 'agent', name: 'agent' });
|
|
22
|
+
/** At most this many recipients on a message. */
|
|
23
|
+
const TO_MAX = 20;
|
|
24
|
+
/** The longest emoji a reaction may be (a sequence with modifiers). */
|
|
25
|
+
const EMOJI_MAX = 32;
|
|
22
26
|
const newId = (prefix) => `${prefix}${randomBytes(5).toString('hex')}`;
|
|
23
27
|
const now = () => new Date().toISOString();
|
|
24
28
|
export class CommentStore {
|
|
@@ -104,6 +108,7 @@ export class CommentStore {
|
|
|
104
108
|
}
|
|
105
109
|
create(input) {
|
|
106
110
|
const body = checkText(input.text);
|
|
111
|
+
const to = checkTo(input.to);
|
|
107
112
|
return this.mutate((doc) => {
|
|
108
113
|
const at = now();
|
|
109
114
|
const thread = {
|
|
@@ -115,24 +120,28 @@ export class CommentStore {
|
|
|
115
120
|
status: 'open',
|
|
116
121
|
createdAt: at,
|
|
117
122
|
updatedAt: at,
|
|
118
|
-
messages: [{ id: newId('m_'), author: input.author ?? { ...AGENT_AUTHOR }, text: body, at }],
|
|
123
|
+
messages: [{ id: newId('m_'), author: input.author ?? { ...AGENT_AUTHOR }, text: body, at, ...(to ? { to } : {}) }],
|
|
119
124
|
};
|
|
120
125
|
doc.threads.push(thread);
|
|
121
126
|
return thread;
|
|
122
127
|
});
|
|
123
128
|
}
|
|
124
|
-
addMessage(threadId, author, text, { resolve = false } = {}) {
|
|
129
|
+
addMessage(threadId, author, text, { resolve = false, to } = {}) {
|
|
125
130
|
const body = checkText(text);
|
|
131
|
+
const recipients = checkTo(to);
|
|
126
132
|
return this.mutate((doc) => {
|
|
127
133
|
const thread = this.find(doc, threadId);
|
|
128
134
|
const at = now();
|
|
129
|
-
const message = { id: newId('m_'), author, text: body, at };
|
|
135
|
+
const message = { id: newId('m_'), author, text: body, at, ...(recipients ? { to: recipients } : {}) };
|
|
130
136
|
thread.messages.push(message);
|
|
131
137
|
thread.updatedAt = at;
|
|
132
138
|
if (author.kind === 'agent') {
|
|
133
|
-
|
|
139
|
+
if (thread.agent?.unaskedAt)
|
|
140
|
+
message.joined = true;
|
|
141
|
+
const { unaskedAt: _answered, ...agent } = thread.agent ?? { status: 'replied' };
|
|
142
|
+
thread.agent = { ...agent, status: 'replied', repliedAt: at };
|
|
134
143
|
if (resolve)
|
|
135
|
-
setStatus(thread, 'resolved', at);
|
|
144
|
+
setStatus(thread, 'resolved', at, author);
|
|
136
145
|
}
|
|
137
146
|
else if (thread.status === 'resolved') {
|
|
138
147
|
setStatus(thread, 'open', at);
|
|
@@ -140,10 +149,52 @@ export class CommentStore {
|
|
|
140
149
|
return { thread, message };
|
|
141
150
|
});
|
|
142
151
|
}
|
|
143
|
-
|
|
152
|
+
/** Changes the text (and recipients, when given) of `author`'s own message. */
|
|
153
|
+
editMessage(threadId, messageId, author, text, to) {
|
|
154
|
+
const body = checkText(text);
|
|
155
|
+
const recipients = to === undefined ? undefined : checkTo(to);
|
|
144
156
|
return this.mutate((doc) => {
|
|
145
157
|
const thread = this.find(doc, threadId);
|
|
146
|
-
|
|
158
|
+
const message = findMessage(thread, messageId);
|
|
159
|
+
if (!sameAuthor(message.author, author))
|
|
160
|
+
throw new FrameError('forbidden', 'Only its author edits a comment.', 403);
|
|
161
|
+
const at = now();
|
|
162
|
+
message.text = body;
|
|
163
|
+
message.editedAt = at;
|
|
164
|
+
if (to !== undefined) {
|
|
165
|
+
if (recipients)
|
|
166
|
+
message.to = recipients;
|
|
167
|
+
else
|
|
168
|
+
delete message.to;
|
|
169
|
+
}
|
|
170
|
+
thread.updatedAt = at;
|
|
171
|
+
return thread;
|
|
172
|
+
});
|
|
173
|
+
}
|
|
174
|
+
/** Adds (`on`) or takes back `author`'s `emoji` on a message; adding one already there changes nothing. */
|
|
175
|
+
react(threadId, messageId, author, emoji, on) {
|
|
176
|
+
if (typeof emoji !== 'string' || !emoji.trim() || emoji.length > EMOJI_MAX)
|
|
177
|
+
throw new FrameError('invalid_argument', 'A reaction is one emoji.');
|
|
178
|
+
return this.mutate((doc) => {
|
|
179
|
+
const thread = this.find(doc, threadId);
|
|
180
|
+
const message = findMessage(thread, messageId);
|
|
181
|
+
const reactions = message.reactions ?? [];
|
|
182
|
+
const mine = reactions.findIndex((r) => r.emoji === emoji && sameAuthor(r.author, author));
|
|
183
|
+
if (on && mine < 0)
|
|
184
|
+
reactions.push({ emoji, author, at: now() });
|
|
185
|
+
if (!on && mine >= 0)
|
|
186
|
+
reactions.splice(mine, 1);
|
|
187
|
+
if (reactions.length)
|
|
188
|
+
message.reactions = reactions;
|
|
189
|
+
else
|
|
190
|
+
delete message.reactions;
|
|
191
|
+
return thread;
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
setResolved(threadId, resolved, by) {
|
|
195
|
+
return this.mutate((doc) => {
|
|
196
|
+
const thread = this.find(doc, threadId);
|
|
197
|
+
setStatus(thread, resolved ? 'resolved' : 'open', now(), by);
|
|
147
198
|
return thread;
|
|
148
199
|
});
|
|
149
200
|
}
|
|
@@ -179,21 +230,58 @@ export class CommentStore {
|
|
|
179
230
|
return thread;
|
|
180
231
|
});
|
|
181
232
|
}
|
|
182
|
-
|
|
233
|
+
/**
|
|
234
|
+
* Marks the thread sent to the agent. `unasked`: a reply that does not ask the agent, sent because it already took
|
|
235
|
+
* part in the thread; only such a thread can be, and it keeps its status (nothing waits on the agent). One the agent
|
|
236
|
+
* had answered remembers it (`unaskedAt`), so the agent's next reply there is marked `joined`.
|
|
237
|
+
*/
|
|
238
|
+
markSent(threadId, { unasked = false } = {}) {
|
|
183
239
|
return this.mutate((doc) => {
|
|
184
240
|
const thread = this.find(doc, threadId);
|
|
185
|
-
|
|
241
|
+
if (!unasked) {
|
|
242
|
+
thread.agent = { status: 'pending', sentAt: now() };
|
|
243
|
+
return thread;
|
|
244
|
+
}
|
|
245
|
+
if (!thread.agent && !thread.messages.some((m) => m.author?.kind === 'agent')) {
|
|
246
|
+
throw new FrameError('invalid_argument', 'Only a thread the agent took part in is sent to it without asking it.');
|
|
247
|
+
}
|
|
248
|
+
const agent = thread.agent ?? { status: 'replied' };
|
|
249
|
+
thread.agent = agent.status === 'replied' ? { ...agent, unaskedAt: now() } : agent;
|
|
186
250
|
return thread;
|
|
187
251
|
});
|
|
188
252
|
}
|
|
189
253
|
}
|
|
190
|
-
function setStatus(thread, status, at) {
|
|
254
|
+
function setStatus(thread, status, at, by) {
|
|
191
255
|
thread.status = status;
|
|
192
256
|
thread.updatedAt = at;
|
|
193
|
-
if (status === 'resolved')
|
|
257
|
+
if (status === 'resolved') {
|
|
194
258
|
thread.resolvedAt = at;
|
|
195
|
-
|
|
259
|
+
if (by)
|
|
260
|
+
thread.resolvedBy = { ...by };
|
|
261
|
+
else
|
|
262
|
+
delete thread.resolvedBy;
|
|
263
|
+
}
|
|
264
|
+
else {
|
|
196
265
|
delete thread.resolvedAt;
|
|
266
|
+
delete thread.resolvedBy;
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
function findMessage(thread, messageId) {
|
|
270
|
+
const message = thread.messages.find((m) => m.id === messageId);
|
|
271
|
+
if (!message)
|
|
272
|
+
throw new FrameError('not_found', `No message ${String(messageId)} in thread ${thread.id}.`, 404);
|
|
273
|
+
return message;
|
|
274
|
+
}
|
|
275
|
+
const sameAuthor = (a, b) => a?.kind === b.kind && a.name === b.name;
|
|
276
|
+
/** The recipients a message names: short non-empty strings, without repeats; none is `undefined`. */
|
|
277
|
+
function checkTo(to) {
|
|
278
|
+
if (to === undefined || to === null)
|
|
279
|
+
return undefined;
|
|
280
|
+
if (!Array.isArray(to) || to.length > TO_MAX || !to.every((name) => typeof name === 'string' && name && name.length <= 200)) {
|
|
281
|
+
throw new FrameError('invalid_argument', `to is a list of at most ${TO_MAX} names.`);
|
|
282
|
+
}
|
|
283
|
+
const names = [...new Set(to)];
|
|
284
|
+
return names.length ? names : undefined;
|
|
197
285
|
}
|
|
198
286
|
function checkText(text) {
|
|
199
287
|
if (typeof text !== 'string' || !text.trim())
|
|
@@ -223,6 +311,9 @@ export function agentView(thread, n) {
|
|
|
223
311
|
text: m.text,
|
|
224
312
|
at: m.at,
|
|
225
313
|
...(m.editedAt ? { editedAt: m.editedAt } : {}),
|
|
314
|
+
...(m.to?.length ? { to: m.to } : {}),
|
|
315
|
+
...(m.reactions?.length ? { reactions: m.reactions.map((r) => `${r.emoji} ${r.author.kind === 'agent' ? 'agent' : r.author.name}`) } : {}),
|
|
316
|
+
...(m.joined ? { joined: true } : {}),
|
|
226
317
|
})),
|
|
227
318
|
};
|
|
228
319
|
}
|
package/src/frame/index.js
CHANGED
|
@@ -597,7 +597,7 @@ export class FrameSite {
|
|
|
597
597
|
return { threadId: thread.id, commentId: message.id, thread: pageThread(thread) };
|
|
598
598
|
}
|
|
599
599
|
case 'comments.resolve': {
|
|
600
|
-
const thread = this.comments.setResolved(a.threadId, a.resolved !== false);
|
|
600
|
+
const thread = this.comments.setResolved(a.threadId, a.resolved !== false, this.author());
|
|
601
601
|
this.commentsChanged();
|
|
602
602
|
return { thread: pageThread(thread) };
|
|
603
603
|
}
|
|
@@ -1067,7 +1067,7 @@ export const frameActions = {
|
|
|
1067
1067
|
hidden: true,
|
|
1068
1068
|
run: (artifact, a) => {
|
|
1069
1069
|
const site = frameOf(artifact);
|
|
1070
|
-
const thread = site.comments.setResolved(a.thread_id, !a.reopen);
|
|
1070
|
+
const thread = site.comments.setResolved(a.thread_id, !a.reopen, { ...AGENT_AUTHOR });
|
|
1071
1071
|
site.commentsChanged();
|
|
1072
1072
|
return { thread: agentView(thread) };
|
|
1073
1073
|
},
|