@celobus/sdk 0.0.0-stage → 0.1.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/LICENSE +91 -0
- package/README.md +38 -2
- package/dist/access.d.ts +141 -0
- package/dist/access.js +232 -0
- package/dist/codec.d.ts +29 -0
- package/dist/codec.js +361 -0
- package/dist/cron.d.ts +2 -0
- package/dist/cron.js +113 -0
- package/dist/ctx.d.ts +644 -0
- package/dist/ctx.js +657 -0
- package/dist/db.d.ts +234 -0
- package/dist/db.js +495 -0
- package/dist/decimal.d.ts +39 -0
- package/dist/decimal.js +158 -0
- package/dist/declare.d.ts +311 -0
- package/dist/declare.js +78 -0
- package/dist/descriptor.d.ts +229 -0
- package/dist/descriptor.js +899 -0
- package/dist/errors.d.ts +65 -0
- package/dist/errors.js +114 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +34 -0
- package/dist/log.d.ts +39 -0
- package/dist/log.js +101 -0
- package/dist/names.d.ts +12 -0
- package/dist/names.js +41 -0
- package/dist/notify.d.ts +185 -0
- package/dist/notify.js +234 -0
- package/dist/platform.d.ts +61 -0
- package/dist/platform.js +47 -0
- package/dist/plugin.d.ts +43 -0
- package/dist/plugin.js +117 -0
- package/dist/query.d.ts +326 -0
- package/dist/query.js +794 -0
- package/dist/remote.d.ts +8 -0
- package/dist/remote.js +19 -0
- package/dist/schema.d.ts +487 -0
- package/dist/schema.js +405 -0
- package/dist/serve.d.ts +63 -0
- package/dist/serve.js +411 -0
- package/dist/sql.d.ts +13 -0
- package/dist/sql.js +33 -0
- package/dist/ui.d.ts +1867 -0
- package/dist/ui.js +3964 -0
- package/dist/viz-kinds.d.ts +12 -0
- package/dist/viz-kinds.js +14 -0
- package/package.json +33 -4
- package/proto/plugin.proto +994 -0
package/dist/notify.js
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
// Notifications: the kinds a plugin declares, and what it sends.
|
|
2
|
+
//
|
|
3
|
+
// A plugin only sends: the platform stores each notification in the member's inbox, tracks read and done, keeps
|
|
4
|
+
// follows and preferences, hides what the member can no longer read, keeps their screens live and mails a daily
|
|
5
|
+
// digest of what stays unread. Sending needs the capability `push:send`, declared with its reason.
|
|
6
|
+
//
|
|
7
|
+
// export const mention = notification('mention', { title: 'Mentions', description: 'Someone wrote @you', digest: true });
|
|
8
|
+
// plugin({ ..., capabilities: { 'push:send': 'Tells people when they are mentioned.' }, notifications: [mention] });
|
|
9
|
+
//
|
|
10
|
+
// await tx.notifications.send(mention, { to: mentioned, key: notify.row(post, id), title: 'mentioned you', link });
|
|
11
|
+
//
|
|
12
|
+
// The API is `ctx.notifications` (`Notifications`): `send` a notice of a kind, `ask` an approval or a decision with
|
|
13
|
+
// buttons and `resolve` it, `follow` a key, `unfollow` it, ask whether the caller is `following` it.
|
|
14
|
+
import { encodeMessage, stringify } from "./codec.js";
|
|
15
|
+
import { describedEndpoints } from "./declare.js";
|
|
16
|
+
import { internal } from "./errors.js";
|
|
17
|
+
import { entityNames } from "./schema.js";
|
|
18
|
+
/**
|
|
19
|
+
* A kind of notification the plugin declares (`plugin({ notifications: [mention] })`): what a member turns on or off
|
|
20
|
+
* in their settings. Its name is snake_case, at most 32 characters.
|
|
21
|
+
*/
|
|
22
|
+
export class NotificationKind {
|
|
23
|
+
name;
|
|
24
|
+
options;
|
|
25
|
+
constructor(name, options) {
|
|
26
|
+
this.name = name;
|
|
27
|
+
this.options = options;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/** `export const mention = notification('mention', { title: 'Mentions', digest: true })`. */
|
|
31
|
+
export function notification(name, options) {
|
|
32
|
+
return new NotificationKind(name, options);
|
|
33
|
+
}
|
|
34
|
+
// ---------------------------------------------------------------------------------------------- what is sent
|
|
35
|
+
function entityName(entity) {
|
|
36
|
+
const name = entityNames.get(entity) ?? entity.options.name;
|
|
37
|
+
if (!name)
|
|
38
|
+
throw internal(new Error("notify: the entity is not in plugin({ entities })"));
|
|
39
|
+
return name;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* What a notification is about: the plugin's name for it (`post:0193…`, at most 200 bytes), optionally one of its
|
|
43
|
+
* entity rows (the subject, `<entity>/<id>`). Unread notifications of one kind and key group into one row
|
|
44
|
+
* ("3 replies"); members follow keys; an ask's key is its identity. A member who can no longer read the subject no
|
|
45
|
+
* longer sees it.
|
|
46
|
+
*/
|
|
47
|
+
export class NotifyKey {
|
|
48
|
+
key;
|
|
49
|
+
subject;
|
|
50
|
+
constructor(key, subject = "") {
|
|
51
|
+
this.key = key;
|
|
52
|
+
this.subject = subject;
|
|
53
|
+
}
|
|
54
|
+
/** The same key tied to one of the plugin's entity rows. */
|
|
55
|
+
withSubject(entity, id) {
|
|
56
|
+
return new NotifyKey(this.key, `${entityName(entity)}/${id}`);
|
|
57
|
+
}
|
|
58
|
+
toString() {
|
|
59
|
+
return this.key;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
/** Where a notification opens: one of the plugin's screens or document-level overlays, with its params. */
|
|
63
|
+
export class NotifyLink {
|
|
64
|
+
screen;
|
|
65
|
+
overlay;
|
|
66
|
+
args;
|
|
67
|
+
/** @internal */
|
|
68
|
+
constructor(screen, overlay, args) {
|
|
69
|
+
this.screen = screen;
|
|
70
|
+
this.overlay = overlay;
|
|
71
|
+
this.args = args;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
function paramsJson(message, params) {
|
|
75
|
+
if (!message)
|
|
76
|
+
return (params ?? {});
|
|
77
|
+
try {
|
|
78
|
+
return encodeMessage(message, params);
|
|
79
|
+
}
|
|
80
|
+
catch (e) {
|
|
81
|
+
throw internal(new Error(`notify: the params are not ${message.name}: ${e.message}`));
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* A button of an ask: it calls one of the plugin's `ui` endpoints with this request, as the member who presses it.
|
|
86
|
+
* The endpoint checks the member and resolves the ask. Made with `notify.button(..)`.
|
|
87
|
+
*/
|
|
88
|
+
export class NotifyButton {
|
|
89
|
+
label;
|
|
90
|
+
endpoint;
|
|
91
|
+
request;
|
|
92
|
+
primary;
|
|
93
|
+
icon;
|
|
94
|
+
/** @internal */
|
|
95
|
+
constructor(label, endpoint, request, primary, icon) {
|
|
96
|
+
this.label = label;
|
|
97
|
+
this.endpoint = endpoint;
|
|
98
|
+
this.request = request;
|
|
99
|
+
this.primary = primary;
|
|
100
|
+
this.icon = icon;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/** Keys, links and buttons of notifications. */
|
|
104
|
+
export const notify = {
|
|
105
|
+
/** A key of the plugin's own (no subject). */
|
|
106
|
+
key(key) {
|
|
107
|
+
return new NotifyKey(key);
|
|
108
|
+
},
|
|
109
|
+
/** The key of one of the plugin's entity rows, `<entity>:<id>`, with the row as its subject. */
|
|
110
|
+
row(entity, id) {
|
|
111
|
+
const name = entityName(entity);
|
|
112
|
+
return new NotifyKey(`${name}:${id}`, `${name}/${id}`);
|
|
113
|
+
},
|
|
114
|
+
/** Opens one of the plugin's screens with these params. */
|
|
115
|
+
screen(screen, params) {
|
|
116
|
+
return new NotifyLink(screen.id, "", paramsJson(screen.paramsMessage, params));
|
|
117
|
+
},
|
|
118
|
+
/** Opens one of the plugin's document-level overlays (a side panel, shown beside the inbox's list). */
|
|
119
|
+
overlay(overlay, params) {
|
|
120
|
+
return new NotifyLink("", overlay.id, paramsJson(overlay.paramsMessage, params));
|
|
121
|
+
},
|
|
122
|
+
/** A button of an ask that calls `endpoint` (a `ui` endpoint of the plugin) with `request`. */
|
|
123
|
+
button(label, endpoint, request, options = {}) {
|
|
124
|
+
return new NotifyButton(label, endpoint, request, !!options.primary, options.icon ?? "");
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
function actorWire(a) {
|
|
128
|
+
if (a.agent)
|
|
129
|
+
return { agent: a.agent };
|
|
130
|
+
if (a.noActor)
|
|
131
|
+
return { none: true };
|
|
132
|
+
return { caller: true };
|
|
133
|
+
}
|
|
134
|
+
/** @internal A link as the wire carries it (a notification's, an agent run's `notifyLink`). */
|
|
135
|
+
export function linkWire(l) {
|
|
136
|
+
return l && { screen: l.screen, overlay: l.overlay, args: stringify(l.args) };
|
|
137
|
+
}
|
|
138
|
+
function buttonWire(b) {
|
|
139
|
+
const described = describedEndpoints.get(b.endpoint.root);
|
|
140
|
+
if (!described)
|
|
141
|
+
throw internal(new Error(`notify: the button "${b.label}" names an endpoint that is not in plugin({ endpoints })`));
|
|
142
|
+
let body;
|
|
143
|
+
try {
|
|
144
|
+
body = encodeMessage(described.input, b.request);
|
|
145
|
+
}
|
|
146
|
+
catch (e) {
|
|
147
|
+
throw internal(new Error(`notify: the request of the button "${b.label}" is not ${described.name}'s: ${e.message}`));
|
|
148
|
+
}
|
|
149
|
+
return { label: b.label, endpoint: described.name, body: stringify(body), primary: b.primary, icon: b.icon };
|
|
150
|
+
}
|
|
151
|
+
const REASONS = { manual: "MANUAL", replied: "REPLIED", edited: "EDITED" };
|
|
152
|
+
/**
|
|
153
|
+
* The plugin's notifications (`ctx.notifications`; `tx.notifications` writes in the transaction, and its members hear
|
|
154
|
+
* of it when it commits). A notification never undoes the transaction: a call the database or a limit refuses in it
|
|
155
|
+
* is let go (logged) and resolves normally. Send late in a transaction: a send holds the unread groups it grew until
|
|
156
|
+
* the commit. Needs the capability `push:send` (403 `capability_missing`); a send the platform refuses is 400
|
|
157
|
+
* `invalid`; sends over 50 a second are let go; a manual follow of a key with 2,000 followers, outside a
|
|
158
|
+
* transaction, is 409 `follow_limit`. A send answers nothing about who received it.
|
|
159
|
+
*/
|
|
160
|
+
export class Notifications {
|
|
161
|
+
link;
|
|
162
|
+
/** @internal */
|
|
163
|
+
constructor(link) {
|
|
164
|
+
this.link = link;
|
|
165
|
+
}
|
|
166
|
+
sendWire(kind, n, ask) {
|
|
167
|
+
const key = n.key ?? n.followers;
|
|
168
|
+
return {
|
|
169
|
+
requestId: this.link.requestId,
|
|
170
|
+
tx: this.link.tx,
|
|
171
|
+
kind,
|
|
172
|
+
to: [...(n.to ?? [])],
|
|
173
|
+
followers: n.followers !== undefined,
|
|
174
|
+
except: [...(n.except ?? [])],
|
|
175
|
+
key: key?.key ?? "",
|
|
176
|
+
subject: key?.subject ?? "",
|
|
177
|
+
actor: actorWire(n),
|
|
178
|
+
title: n.title ?? "",
|
|
179
|
+
body: n.body ?? "",
|
|
180
|
+
...(n.source ? { source: { label: n.source.label, icon: n.source.icon } } : {}),
|
|
181
|
+
...(n.link ? { link: linkWire(n.link) } : {}),
|
|
182
|
+
...(ask ? { ask } : {}),
|
|
183
|
+
once: n.once ?? "",
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
/** Sends a notification of one of the plugin's kinds. */
|
|
187
|
+
async send(kind, notice) {
|
|
188
|
+
await this.link.syscall({ notifySend: this.sendWire(kind.name, notice) });
|
|
189
|
+
}
|
|
190
|
+
/** Asks members for an approval or a decision. */
|
|
191
|
+
async ask(ask) {
|
|
192
|
+
const wire = {
|
|
193
|
+
kind: ask.kind === "decision" ? "DECISION" : "APPROVAL",
|
|
194
|
+
buttons: ask.buttons.map(buttonWire),
|
|
195
|
+
review: ask.review ?? "",
|
|
196
|
+
};
|
|
197
|
+
const { kind: _kind, buttons: _buttons, review: _review, ...notice } = ask;
|
|
198
|
+
await this.link.syscall({ notifySend: this.sendWire("", notice, wire) });
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* Resolves every open ask of `key`, for every member it asked: `outcome` ("Approved by Sarah Bennett", at most 80
|
|
202
|
+
* characters) is what the inbox shows.
|
|
203
|
+
*/
|
|
204
|
+
async resolve(key, outcome) {
|
|
205
|
+
await this.link.syscall({ notifyResolve: { requestId: this.link.requestId, tx: this.link.tx, key: key.key, outcome } });
|
|
206
|
+
}
|
|
207
|
+
followWire(key, op, follow = {}, reason = "") {
|
|
208
|
+
return {
|
|
209
|
+
requestId: this.link.requestId,
|
|
210
|
+
tx: this.link.tx,
|
|
211
|
+
key: key.key,
|
|
212
|
+
subject: key.subject,
|
|
213
|
+
noun: follow.noun ?? "",
|
|
214
|
+
users: [...(follow.users ?? [])],
|
|
215
|
+
reason: reason || "REASON_UNSPECIFIED",
|
|
216
|
+
op,
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
/** Makes the caller (or, for `replied` and `edited`, `follow.users`) follow `key`. */
|
|
220
|
+
async follow(key, follow = {}) {
|
|
221
|
+
await this.link.syscall({ notifyFollow: this.followWire(key, "FOLLOW", follow, REASONS[follow.reason ?? "manual"]) });
|
|
222
|
+
}
|
|
223
|
+
/** The caller stops following `key`; an automatic follow does not resume it. */
|
|
224
|
+
async unfollow(key) {
|
|
225
|
+
await this.link.syscall({ notifyFollow: this.followWire(key, "UNFOLLOW") });
|
|
226
|
+
}
|
|
227
|
+
/** Whether the caller follows `key` (for a "Following" button): the one thing a plugin may read of notifications. */
|
|
228
|
+
async following(key) {
|
|
229
|
+
const r = await this.link.syscall({ notifyFollow: this.followWire(key, "GET") });
|
|
230
|
+
if (!r.notifyFollowState)
|
|
231
|
+
throw internal(new Error("the platform answered a follow with something else"));
|
|
232
|
+
return !!r.notifyFollowState.following;
|
|
233
|
+
}
|
|
234
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { PlatformEntity, type Field } from "./schema.js";
|
|
2
|
+
/** A person or a service account. */
|
|
3
|
+
export declare const userKind: import("./schema.js").EnumDef<"service" | "person">;
|
|
4
|
+
/** The base role in the workspace (`undefined` for a person who left). */
|
|
5
|
+
export declare const baseRole: import("./schema.js").EnumDef<"member" | "admin" | "owner" | "guest">;
|
|
6
|
+
/** Whether a person is in the workspace. */
|
|
7
|
+
export declare const userStatus: import("./schema.js").EnumDef<"active" | "removed" | "erased">;
|
|
8
|
+
/** A person (or service account) of the workspace. `email` is read only with the plugin permission `members.email`,
|
|
9
|
+
* and never by a guest. */
|
|
10
|
+
export declare const user: PlatformEntity<{
|
|
11
|
+
id: Field<string, false, PlatformEntity<any>>;
|
|
12
|
+
displayName: Field<string, false>;
|
|
13
|
+
avatarUrl: Field<string, false>;
|
|
14
|
+
email: Field<string, true>;
|
|
15
|
+
kind: Field<"person" | "service", false>;
|
|
16
|
+
baseRole: Field<"owner" | "admin" | "member" | "guest", true>;
|
|
17
|
+
status: Field<"active" | "removed" | "erased", false>;
|
|
18
|
+
locale: Field<string, false>;
|
|
19
|
+
joinedAt: Field<Date, false>;
|
|
20
|
+
leftAt: Field<Date, true>;
|
|
21
|
+
}>;
|
|
22
|
+
/** A group of the workspace. */
|
|
23
|
+
export declare const group: PlatformEntity<{
|
|
24
|
+
id: Field<string, false, PlatformEntity<any>>;
|
|
25
|
+
name: Field<string, false>;
|
|
26
|
+
}>;
|
|
27
|
+
/** A person's membership of a group (queries only). */
|
|
28
|
+
export declare const groupMember: PlatformEntity<{
|
|
29
|
+
groupId: Field<string, false, PlatformEntity<{
|
|
30
|
+
id: Field<string, false, PlatformEntity<any>>;
|
|
31
|
+
name: Field<string, false>;
|
|
32
|
+
}>>;
|
|
33
|
+
userId: Field<string, false, PlatformEntity<{
|
|
34
|
+
id: Field<string, false, PlatformEntity<any>>;
|
|
35
|
+
displayName: Field<string, false>;
|
|
36
|
+
avatarUrl: Field<string, false>;
|
|
37
|
+
email: Field<string, true>;
|
|
38
|
+
kind: Field<"person" | "service", false>;
|
|
39
|
+
baseRole: Field<"owner" | "admin" | "member" | "guest", true>;
|
|
40
|
+
status: Field<"active" | "removed" | "erased", false>;
|
|
41
|
+
locale: Field<string, false>;
|
|
42
|
+
joinedAt: Field<Date, false>;
|
|
43
|
+
leftAt: Field<Date, true>;
|
|
44
|
+
}>>;
|
|
45
|
+
}>;
|
|
46
|
+
/** A role a person holds: `workspace.*` and the plugin's own (queries only). */
|
|
47
|
+
export declare const roleAssignment: PlatformEntity<{
|
|
48
|
+
userId: Field<string, false, PlatformEntity<{
|
|
49
|
+
id: Field<string, false, PlatformEntity<any>>;
|
|
50
|
+
displayName: Field<string, false>;
|
|
51
|
+
avatarUrl: Field<string, false>;
|
|
52
|
+
email: Field<string, true>;
|
|
53
|
+
kind: Field<"person" | "service", false>;
|
|
54
|
+
baseRole: Field<"owner" | "admin" | "member" | "guest", true>;
|
|
55
|
+
status: Field<"active" | "removed" | "erased", false>;
|
|
56
|
+
locale: Field<string, false>;
|
|
57
|
+
joinedAt: Field<Date, false>;
|
|
58
|
+
leftAt: Field<Date, true>;
|
|
59
|
+
}>>;
|
|
60
|
+
role: Field<string, false, unknown>;
|
|
61
|
+
}>;
|
package/dist/platform.js
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
// The workspace directory, an implicit read-only dependency of every plugin:
|
|
2
|
+
//
|
|
3
|
+
// import * as platform from '@celobus/sdk/platform';
|
|
4
|
+
// ownerId: t.ref(platform.user) // ref:platform.user
|
|
5
|
+
//
|
|
6
|
+
// and, for queries (`ctx.query(platform.groupMember).join(platform.user, platform.groupMember.f.userId)`), its
|
|
7
|
+
// people, groups, memberships and role assignments. A member (base role `member` and above) reads every row (a plugin:
|
|
8
|
+
// the assignments of its own roles and the platform's); a guest reads their own user row only, and sees others as
|
|
9
|
+
// labels (`label(ref)` from `@celobus/sdk/query`).
|
|
10
|
+
import { PlatformEntity, t } from "./schema.js";
|
|
11
|
+
/** A person or a service account. */
|
|
12
|
+
export const userKind = t.enum("UserKind", ["person", "service"]);
|
|
13
|
+
/** The base role in the workspace (`undefined` for a person who left). */
|
|
14
|
+
export const baseRole = t.enum("BaseRole", ["owner", "admin", "member", "guest"]);
|
|
15
|
+
/** Whether a person is in the workspace. */
|
|
16
|
+
export const userStatus = t.enum("UserStatus", ["active", "removed", "erased"]);
|
|
17
|
+
const userRef = () => t.ref("platform.user");
|
|
18
|
+
const groupRef = () => t.ref("platform.group");
|
|
19
|
+
/** A person (or service account) of the workspace. `email` is read only with the plugin permission `members.email`,
|
|
20
|
+
* and never by a guest. */
|
|
21
|
+
export const user = new PlatformEntity("platform.user", {
|
|
22
|
+
id: t.ref("platform.user"),
|
|
23
|
+
displayName: t.text(),
|
|
24
|
+
avatarUrl: t.text(),
|
|
25
|
+
email: t.text().optional(),
|
|
26
|
+
kind: t.enum(userKind),
|
|
27
|
+
baseRole: t.enum(baseRole).optional(),
|
|
28
|
+
status: t.enum(userStatus),
|
|
29
|
+
locale: t.text(),
|
|
30
|
+
joinedAt: t.timestamp(),
|
|
31
|
+
leftAt: t.timestamp().optional(),
|
|
32
|
+
});
|
|
33
|
+
/** A group of the workspace. */
|
|
34
|
+
export const group = new PlatformEntity("platform.group", {
|
|
35
|
+
id: t.ref("platform.group"),
|
|
36
|
+
name: t.text(),
|
|
37
|
+
});
|
|
38
|
+
/** A person's membership of a group (queries only). */
|
|
39
|
+
export const groupMember = new PlatformEntity("platform.group_member", {
|
|
40
|
+
groupId: groupRef(),
|
|
41
|
+
userId: userRef(),
|
|
42
|
+
});
|
|
43
|
+
/** A role a person holds: `workspace.*` and the plugin's own (queries only). */
|
|
44
|
+
export const roleAssignment = new PlatformEntity("platform.role_assignment", {
|
|
45
|
+
userId: userRef(),
|
|
46
|
+
role: t.text(),
|
|
47
|
+
});
|
package/dist/plugin.d.ts
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { RunChangeHandler } from "./ctx.js";
|
|
2
|
+
import type { PluginOptions } from "./declare.js";
|
|
3
|
+
import { type DescribeError, type Descriptor, type Resolved } from "./descriptor.js";
|
|
4
|
+
import { type ServeOptions } from "./serve.js";
|
|
5
|
+
export declare class Plugin {
|
|
6
|
+
readonly options: PluginOptions;
|
|
7
|
+
private resolved?;
|
|
8
|
+
private runChange?;
|
|
9
|
+
constructor(options: PluginOptions);
|
|
10
|
+
/** @internal */
|
|
11
|
+
model(): Resolved;
|
|
12
|
+
/**
|
|
13
|
+
* The run-change hook: the platform calls `handler` when a run the plugin sees
|
|
14
|
+
* changes — a run of one of its agents, or one its code started — with where the run stands (`RunChange`). A
|
|
15
|
+
* system request: no caller (`ctx.caller.kind` is `system`), so the handler writes with `ctx.asSystem(..)` and reads
|
|
16
|
+
* the run with `ctx.agents`. The descriptor says `runs: {on_change: true}`.
|
|
17
|
+
*
|
|
18
|
+
* Coalesced per run (one call per 250 ms window, then a trailing one with the latest state) and delivered at least
|
|
19
|
+
* once: an error, the handler's 30 s timeout or a restart of the plugin makes the platform call again. Handle it
|
|
20
|
+
* idempotently.
|
|
21
|
+
*
|
|
22
|
+
* export default plugin({ id: 'helpdesk', agents, endpoints }).onRunChange(async (ctx, change) => {
|
|
23
|
+
* if (change.ended) { const run = await ctx.agents.get(change.runId); ... }
|
|
24
|
+
* });
|
|
25
|
+
*/
|
|
26
|
+
onRunChange(handler: RunChangeHandler): this;
|
|
27
|
+
/** The plugin's id. */
|
|
28
|
+
get id(): string;
|
|
29
|
+
/** The definition errors (empty when the plugin is well defined). */
|
|
30
|
+
check(): DescribeError[];
|
|
31
|
+
/** The descriptor; throws `DescribeErrors` when the definition has errors. */
|
|
32
|
+
describe(): Descriptor;
|
|
33
|
+
/**
|
|
34
|
+
* With `--describe`: prints the descriptor on stdout and exits 0, or the definition errors on stderr and exits
|
|
35
|
+
* 2, without connecting. Otherwise refuses to start on definition errors (exit 2), then serves until SIGTERM.
|
|
36
|
+
*/
|
|
37
|
+
serve(options?: ServeOptions): Promise<void>;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Declares the plugin. Names come from the keys: `roles: { clerk }` → role `clerk`, `endpoints: { getNote }` →
|
|
41
|
+
* endpoint `GetNote`, `entities: { orderLine }` → entity `order_line` (message `OrderLine`).
|
|
42
|
+
*/
|
|
43
|
+
export declare function plugin(options: PluginOptions): Plugin;
|
package/dist/plugin.js
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
// `plugin({...})`: the plugin as a value. `describe()` gives the descriptor, `check()` the definition errors,
|
|
2
|
+
// `serve()` runs it: with `--describe` it prints the descriptor and exits (2 on definition errors), otherwise it
|
|
3
|
+
// connects to the platform.
|
|
4
|
+
import * as fs from "node:fs";
|
|
5
|
+
import * as path from "node:path";
|
|
6
|
+
import { DescribeErrors, formatError, resolve } from "./descriptor.js";
|
|
7
|
+
import { createLogger } from "./log.js";
|
|
8
|
+
import { runSession } from "./serve.js";
|
|
9
|
+
/** The version of the nearest package.json above the program (`process.argv[1]`) that is not the SDK's own. */
|
|
10
|
+
function packageVersion() {
|
|
11
|
+
const main = process.argv[1];
|
|
12
|
+
if (!main)
|
|
13
|
+
return undefined;
|
|
14
|
+
let dir;
|
|
15
|
+
try {
|
|
16
|
+
dir = path.dirname(fs.realpathSync(main));
|
|
17
|
+
}
|
|
18
|
+
catch {
|
|
19
|
+
return undefined;
|
|
20
|
+
}
|
|
21
|
+
for (;;) {
|
|
22
|
+
const file = path.join(dir, "package.json");
|
|
23
|
+
if (fs.existsSync(file)) {
|
|
24
|
+
try {
|
|
25
|
+
const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
26
|
+
if (pkg.name !== "@celobus/sdk")
|
|
27
|
+
return pkg.version;
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return undefined;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
const parent = path.dirname(dir);
|
|
34
|
+
if (parent === dir)
|
|
35
|
+
return undefined;
|
|
36
|
+
dir = parent;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
export class Plugin {
|
|
40
|
+
options;
|
|
41
|
+
resolved;
|
|
42
|
+
runChange;
|
|
43
|
+
constructor(options) {
|
|
44
|
+
this.options = options;
|
|
45
|
+
}
|
|
46
|
+
/** @internal */
|
|
47
|
+
model() {
|
|
48
|
+
const options = this.runChange ? { ...this.options, onRunChange: this.runChange } : this.options;
|
|
49
|
+
this.resolved ??= resolve(options, this.options.version ?? packageVersion());
|
|
50
|
+
return this.resolved;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The run-change hook: the platform calls `handler` when a run the plugin sees
|
|
54
|
+
* changes — a run of one of its agents, or one its code started — with where the run stands (`RunChange`). A
|
|
55
|
+
* system request: no caller (`ctx.caller.kind` is `system`), so the handler writes with `ctx.asSystem(..)` and reads
|
|
56
|
+
* the run with `ctx.agents`. The descriptor says `runs: {on_change: true}`.
|
|
57
|
+
*
|
|
58
|
+
* Coalesced per run (one call per 250 ms window, then a trailing one with the latest state) and delivered at least
|
|
59
|
+
* once: an error, the handler's 30 s timeout or a restart of the plugin makes the platform call again. Handle it
|
|
60
|
+
* idempotently.
|
|
61
|
+
*
|
|
62
|
+
* export default plugin({ id: 'helpdesk', agents, endpoints }).onRunChange(async (ctx, change) => {
|
|
63
|
+
* if (change.ended) { const run = await ctx.agents.get(change.runId); ... }
|
|
64
|
+
* });
|
|
65
|
+
*/
|
|
66
|
+
onRunChange(handler) {
|
|
67
|
+
this.runChange = handler;
|
|
68
|
+
this.resolved = undefined;
|
|
69
|
+
return this;
|
|
70
|
+
}
|
|
71
|
+
/** The plugin's id. */
|
|
72
|
+
get id() {
|
|
73
|
+
return this.options.id;
|
|
74
|
+
}
|
|
75
|
+
/** The definition errors (empty when the plugin is well defined). */
|
|
76
|
+
check() {
|
|
77
|
+
return this.model().errors;
|
|
78
|
+
}
|
|
79
|
+
/** The descriptor; throws `DescribeErrors` when the definition has errors. */
|
|
80
|
+
describe() {
|
|
81
|
+
const { descriptor, errors } = this.model();
|
|
82
|
+
if (errors.length > 0)
|
|
83
|
+
throw new DescribeErrors(errors);
|
|
84
|
+
return descriptor;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* With `--describe`: prints the descriptor on stdout and exits 0, or the definition errors on stderr and exits
|
|
88
|
+
* 2, without connecting. Otherwise refuses to start on definition errors (exit 2), then serves until SIGTERM.
|
|
89
|
+
*/
|
|
90
|
+
async serve(options = {}) {
|
|
91
|
+
const argv = options.argv ?? process.argv;
|
|
92
|
+
const { descriptor, errors } = this.model();
|
|
93
|
+
if (errors.length > 0) {
|
|
94
|
+
process.stderr.write(errors.map(formatError).join("\n") + "\n", () => process.exit(2));
|
|
95
|
+
return new Promise(() => { });
|
|
96
|
+
}
|
|
97
|
+
if (argv.includes("--describe")) {
|
|
98
|
+
process.stdout.write(JSON.stringify(descriptor, null, 2) + "\n", () => process.exit(0));
|
|
99
|
+
return new Promise(() => { });
|
|
100
|
+
}
|
|
101
|
+
const log = createLogger({ plugin: descriptor.id });
|
|
102
|
+
return runSession({
|
|
103
|
+
id: descriptor.id,
|
|
104
|
+
version: descriptor.version,
|
|
105
|
+
depends: descriptor.dependencies.map((d) => d.plugin),
|
|
106
|
+
resolved: this.model(),
|
|
107
|
+
log,
|
|
108
|
+
}, options);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Declares the plugin. Names come from the keys: `roles: { clerk }` → role `clerk`, `endpoints: { getNote }` →
|
|
113
|
+
* endpoint `GetNote`, `entities: { orderLine }` → entity `order_line` (message `OrderLine`).
|
|
114
|
+
*/
|
|
115
|
+
export function plugin(options) {
|
|
116
|
+
return new Plugin(options);
|
|
117
|
+
}
|