@open-artifact/server-sdk 0.2.2 → 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.
@@ -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
- setResolved(threadId: unknown, resolved: boolean): Thread;
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
- markSent(threadId: unknown): Thread;
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>;
@@ -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
- thread.agent = { ...(thread.agent ?? {}), status: 'replied', repliedAt: at };
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
- setResolved(threadId, resolved) {
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
- setStatus(thread, resolved ? 'resolved' : 'open', now());
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
- markSent(threadId) {
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
- thread.agent = { status: 'pending', sentAt: now() };
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
- else
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
  }
@@ -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
  },