@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
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
import type { Ctx, RoleLike, RunChangeHandler } from "./ctx.js";
|
|
2
|
+
import type { NotificationKind } from "./notify.js";
|
|
3
|
+
import type { EntityDef, EnumDef, Infer, IoType, IoValue, MessageDef, Shape } from "./schema.js";
|
|
4
|
+
import type { InvalidationLike, TopicLike, UiDoc } from "./ui.js";
|
|
5
|
+
export type DefaultFor = "none" | "member" | "admin";
|
|
6
|
+
export interface RoleOptions {
|
|
7
|
+
title?: string;
|
|
8
|
+
description?: string;
|
|
9
|
+
/** Only explicit assignment: `workspace.admin` does not substitute for it. */
|
|
10
|
+
strict?: boolean;
|
|
11
|
+
/** Whom the role is given to by default when the plugin is installed. */
|
|
12
|
+
defaultFor?: DefaultFor;
|
|
13
|
+
}
|
|
14
|
+
/** A role of the plugin; its name is its key in `plugin({ roles })`, in snake_case. */
|
|
15
|
+
export declare class RoleDef {
|
|
16
|
+
readonly options: RoleOptions;
|
|
17
|
+
readonly __role: true;
|
|
18
|
+
constructor(options: RoleOptions);
|
|
19
|
+
}
|
|
20
|
+
/** `export const manager = role({ title: 'Order manager', strict: true })`. */
|
|
21
|
+
export declare function role(options?: RoleOptions): RoleDef;
|
|
22
|
+
/** The platform's base roles, by their full names. */
|
|
23
|
+
export declare const workspace: {
|
|
24
|
+
readonly owner: "workspace.owner";
|
|
25
|
+
readonly admin: "workspace.admin";
|
|
26
|
+
readonly member: "workspace.member";
|
|
27
|
+
readonly guest: "workspace.guest";
|
|
28
|
+
};
|
|
29
|
+
export type Auth = "user" | "service" | "any" | "public";
|
|
30
|
+
export type Idempotency = "off" | "optional" | "required";
|
|
31
|
+
/** Milliseconds, or a string: `'500ms'`, `'10s'`, `'2m'`. */
|
|
32
|
+
export type Timeout = number | `${number}ms` | `${number}s` | `${number}m`;
|
|
33
|
+
export interface EndpointOptions<I extends IoType, O extends IoType> {
|
|
34
|
+
description?: string;
|
|
35
|
+
/** A message (`t.message(...)`), an entity, or inline fields (the message `<Name>Request`). */
|
|
36
|
+
input: I;
|
|
37
|
+
/** A message, an entity (the handler returns a row), or inline fields (the message `<Name>Reply`). */
|
|
38
|
+
output: O;
|
|
39
|
+
/** Any of these roles (default: any member who passes the scopes). Checked by the platform, not the SDK. */
|
|
40
|
+
roles?: readonly RoleLike[];
|
|
41
|
+
/** All of these scopes; default `['write']`, or `['read']` when `readOnly`. */
|
|
42
|
+
scopes?: readonly string[];
|
|
43
|
+
readOnly?: boolean;
|
|
44
|
+
/** Default `user`. */
|
|
45
|
+
auth?: Auth;
|
|
46
|
+
/** Default `off`. */
|
|
47
|
+
idempotency?: Idempotency;
|
|
48
|
+
/** Default 30 s, at most 600 s. */
|
|
49
|
+
timeout?: Timeout;
|
|
50
|
+
/** Screens may call it: queries (when it is `readOnly`) and actions. Other endpoints stay out of reach of a UI. */
|
|
51
|
+
ui?: boolean;
|
|
52
|
+
/**
|
|
53
|
+
* After a 2xx answer the platform invalidates these topics (every key: `ORDERS`; or the key taken from the response:
|
|
54
|
+
* `ORDER.by(orderKey.f.id, order.f.id)`); open screens following them re-read.
|
|
55
|
+
*/
|
|
56
|
+
invalidates?: readonly InvalidationLike[];
|
|
57
|
+
handler(ctx: Ctx, input: IoValue<I>): Promise<IoValue<O>> | IoValue<O>;
|
|
58
|
+
}
|
|
59
|
+
/** An endpoint; its name is its key in `plugin({ endpoints })` in PascalCase (`placeOrder` → `PlaceOrder`). */
|
|
60
|
+
export declare class EndpointDef<I extends IoType = IoType, O extends IoType = IoType> {
|
|
61
|
+
readonly options: EndpointOptions<I, O>;
|
|
62
|
+
/** @internal The declaration this one was derived from (`.ui()` and the rest return new ones); UI references
|
|
63
|
+
* resolve through it, so `ui.call(listOrders)` names the endpoint registered as `listOrders.ui()`. */
|
|
64
|
+
readonly root: EndpointDef<any, any>;
|
|
65
|
+
constructor(options: EndpointOptions<I, O>, root?: EndpointDef<any, any>);
|
|
66
|
+
private with;
|
|
67
|
+
/** Screens may call it (see `EndpointOptions.ui`). */
|
|
68
|
+
ui(): EndpointDef<I, O>;
|
|
69
|
+
/** The endpoint only reads: its scope is `read`, and UI queries may call it. */
|
|
70
|
+
readOnly(): EndpointDef<I, O>;
|
|
71
|
+
/** After a 2xx answer the platform invalidates the topic (see `EndpointOptions.invalidates`). */
|
|
72
|
+
invalidates(...topics: InvalidationLike[]): EndpointDef<I, O>;
|
|
73
|
+
}
|
|
74
|
+
export declare function endpoint<I extends IoType, O extends IoType>(options: EndpointOptions<I, O>): EndpointDef<I, O>;
|
|
75
|
+
/**
|
|
76
|
+
* @internal The name each endpoint has in its plugin's descriptor and its request message (an inline input's
|
|
77
|
+
* generated one), set when the plugin is described: what an ask's button sends.
|
|
78
|
+
*/
|
|
79
|
+
export declare const describedEndpoints: WeakMap<EndpointDef<any, any>, {
|
|
80
|
+
name: string;
|
|
81
|
+
input: MessageDef<any> | EntityDef<any>;
|
|
82
|
+
}>;
|
|
83
|
+
/** Milliseconds, or a string: `'500ms'`, `'10s'`, `'2m'`, `'1h'`. */
|
|
84
|
+
export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
|
|
85
|
+
/** @internal Milliseconds of a duration, or `undefined` when it cannot be read. */
|
|
86
|
+
export declare function durationMs(d: unknown): number | undefined;
|
|
87
|
+
/** A job's payload: a message (`t.message(...)`) or inline fields (the message named as the job, in PascalCase). */
|
|
88
|
+
export type JobPayloadType = MessageDef<any> | Shape;
|
|
89
|
+
/** The value of a job's payload in its handler and in `ctx.jobs.enqueue`. */
|
|
90
|
+
export type JobPayload<P> = P extends MessageDef<infer S> ? Infer<S> : P extends Shape ? Infer<P> : never;
|
|
91
|
+
/**
|
|
92
|
+
* How a job's failed attempts are retried: `retries` attempts after the first (at most 20), the first `delay` after
|
|
93
|
+
* the failure (at most an hour), then the same delay (`fixed`) or doubling (`exponential`, each ±20 %, at most an
|
|
94
|
+
* hour). Unset members: 3 retries, 30 s, exponential. `{ retries: 0 }`: one attempt only.
|
|
95
|
+
*/
|
|
96
|
+
export interface JobRetry {
|
|
97
|
+
retries?: number;
|
|
98
|
+
delay?: Duration;
|
|
99
|
+
backoff?: "fixed" | "exponential";
|
|
100
|
+
}
|
|
101
|
+
export interface JobOptions<P extends JobPayloadType> {
|
|
102
|
+
/** The payload message, or inline fields (`{ olderThanDays: t.int() }`: the message `RemindUnpaid` of `remindUnpaid`). */
|
|
103
|
+
payload: P;
|
|
104
|
+
/** What the job does, for the workspace's list of jobs: plain text or a key of the UI's text catalog. */
|
|
105
|
+
description?: string;
|
|
106
|
+
/**
|
|
107
|
+
* A schedule: five fields in UTC, `minute hour day-of-month month day-of-week` (`'0 9 * * 1-5'`: weekdays at 09:00
|
|
108
|
+
* UTC). Each occurrence starts a run with the payload's defaults; an occurrence that comes due while the previous
|
|
109
|
+
* scheduled run is still pending or running is not started. Unset: the job runs only when enqueued.
|
|
110
|
+
*/
|
|
111
|
+
cron?: string;
|
|
112
|
+
/** `'system'`: its runs run as the plugin's system principal, whoever enqueued them. Unset: as the enqueuer. */
|
|
113
|
+
as?: "system";
|
|
114
|
+
/** Unset: 3 retries, 30 s apart, backing off exponentially. */
|
|
115
|
+
retry?: JobRetry;
|
|
116
|
+
/** How long an attempt may run, 1 s to 1 h (default 5 minutes); past it `ctx.signal` aborts and the attempt fails as `timeout`. */
|
|
117
|
+
timeout?: Duration;
|
|
118
|
+
/** How many runs of the job run at once in the workspace, 1 to 64 (default 1). */
|
|
119
|
+
concurrency?: number;
|
|
120
|
+
/** The job's name instead of its key in snake_case: snake_case, at most 32 characters. */
|
|
121
|
+
name?: string;
|
|
122
|
+
/**
|
|
123
|
+
* The run: `ctx.job` says which (run id, attempt), `ctx.signal` aborts when it must stop. Resolving ends the attempt
|
|
124
|
+
* as done; throwing fails it, and the run is retried unless the error is permanent (`permanent(..)`, an error marked
|
|
125
|
+
* `.asPermanent()`, or `invalid`, `not_found`, `permission_denied`, `payload_invalid`).
|
|
126
|
+
*/
|
|
127
|
+
handler(ctx: Ctx, payload: JobPayload<P>): Promise<void> | void;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* A background job; its name is its key in `plugin({ jobs })` in snake_case (`remindUnpaid` → `remind_unpaid`), and
|
|
131
|
+
* `ctx.jobs.enqueue(remindUnpaid, {..})` starts a run of it.
|
|
132
|
+
*/
|
|
133
|
+
export declare class JobDef<P extends JobPayloadType = JobPayloadType> {
|
|
134
|
+
readonly options: JobOptions<P>;
|
|
135
|
+
readonly __job: true;
|
|
136
|
+
constructor(options: JobOptions<P>);
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* `export const remindUnpaid = job({ payload: { olderThanDays: t.int() }, cron: '0 9 * * 1-5', as: 'system',
|
|
140
|
+
* async handler(ctx, p) { .. } })`, listed in `plugin({ jobs: { remindUnpaid } })`.
|
|
141
|
+
*/
|
|
142
|
+
export declare function job<P extends JobPayloadType>(options: JobOptions<P>): JobDef<P>;
|
|
143
|
+
export interface ScopeOptions {
|
|
144
|
+
/** Consent text. */
|
|
145
|
+
title?: string;
|
|
146
|
+
description?: string;
|
|
147
|
+
sensitive?: boolean;
|
|
148
|
+
}
|
|
149
|
+
export interface Dependency {
|
|
150
|
+
plugin: string;
|
|
151
|
+
/** The endpoints this plugin calls (`['GetCustomer']`); the platform refuses others. */
|
|
152
|
+
calls?: readonly string[];
|
|
153
|
+
/**
|
|
154
|
+
* The dependency's exported entities this plugin reads (`ctx.query`), with the fields it reads and their types,
|
|
155
|
+
* as `celobus plugin add` generates them; the platform refuses other reads.
|
|
156
|
+
*/
|
|
157
|
+
reads?: readonly DependencyRead[];
|
|
158
|
+
}
|
|
159
|
+
/** One entity of a dependency this plugin reads: its name there and the fields read, each with its descriptor type. */
|
|
160
|
+
export interface DependencyRead {
|
|
161
|
+
entity: string;
|
|
162
|
+
fields: readonly {
|
|
163
|
+
name: string;
|
|
164
|
+
type: string;
|
|
165
|
+
}[];
|
|
166
|
+
}
|
|
167
|
+
/** The coding-agent CLI that runs an agent. */
|
|
168
|
+
export type AgentEngine = "claude" | "codex" | "pi";
|
|
169
|
+
/** How long an agent's run may take: `'90s'`, `'15m'`, `'2h'`. */
|
|
170
|
+
export type AgentTimeout = `${number}s` | `${number}m` | `${number}h`;
|
|
171
|
+
/**
|
|
172
|
+
* An agent of the plugin: a service account with the roles it holds, and how its runs are made. Its system
|
|
173
|
+
* prompt, its skills and its extra MCP servers are files of the plugin: `agents/<name>/soul.md`,
|
|
174
|
+
* `agents/<name>/skills/<skill>/SKILL.md`, `agents/<name>/mcp.json`.
|
|
175
|
+
*/
|
|
176
|
+
export interface AgentOptions {
|
|
177
|
+
roles?: readonly RoleLike[];
|
|
178
|
+
/**
|
|
179
|
+
* The workspace permissions the agent asks for (`['plugins.install']`): with one, the agent does the workspace
|
|
180
|
+
* operations that take it as a workspace admin would. Whoever installs the plugin sees the list.
|
|
181
|
+
*/
|
|
182
|
+
workspace?: readonly string[];
|
|
183
|
+
/**
|
|
184
|
+
* The agents this one may bring into its group when they are not there: an agent of this plugin by its name, or
|
|
185
|
+
* `<dependency>.<agent>`. Messaging an agent that is in the group already needs no entry. Whoever installs the
|
|
186
|
+
* plugin sees the list.
|
|
187
|
+
*/
|
|
188
|
+
delegates?: readonly string[];
|
|
189
|
+
/**
|
|
190
|
+
* The `llm` connection its runs use: a connection of this plugin by its key (`research`), or `<dependency>.<name>`
|
|
191
|
+
* (`ai.anthropic`). An owner or admin may choose another one of the plugin or its dependencies in the agent's
|
|
192
|
+
* settings. Whoever installs the plugin sees it.
|
|
193
|
+
*/
|
|
194
|
+
connection?: string;
|
|
195
|
+
/**
|
|
196
|
+
* The agent has an SSH key of its own (ed25519, one per workspace), in `~/.ssh` of its runs: its public key is shown
|
|
197
|
+
* in the workspace's settings, to add to the agent's account at GitHub or GitLab.
|
|
198
|
+
*/
|
|
199
|
+
sshKey?: boolean;
|
|
200
|
+
/**
|
|
201
|
+
* The agent's service account asks for base role admin instead of member: it does whatever a workspace admin does,
|
|
202
|
+
* not only the operations of its `workspace` permissions. Only an owner installs or upgrades to a version that asks
|
|
203
|
+
* for it, and whoever installs the plugin sees it; an owner may still change the account's role. Never owner.
|
|
204
|
+
*/
|
|
205
|
+
admin?: boolean;
|
|
206
|
+
/** The agent's display name. */
|
|
207
|
+
title?: string;
|
|
208
|
+
/** What the agent is for, in a sentence. */
|
|
209
|
+
description?: string;
|
|
210
|
+
/**
|
|
211
|
+
* The agent's own glyph, a lucide icon's name (`rocket`, `git-pull-request`): the client draws it over its engine's
|
|
212
|
+
* mark wherever the agent is shown, so two agents on one engine are told apart.
|
|
213
|
+
*/
|
|
214
|
+
icon?: string;
|
|
215
|
+
/**
|
|
216
|
+
* The engine of its runs, unless whoever starts one names another (default: the one its connection's protocol picks:
|
|
217
|
+
* Claude Code for `anthropic`, Codex for `openai_responses`, Pi for `openai_chat`).
|
|
218
|
+
*/
|
|
219
|
+
engine?: AgentEngine;
|
|
220
|
+
/**
|
|
221
|
+
* The model of its runs when its connection lists it, unless whoever starts a run or the workspace's settings name
|
|
222
|
+
* another (default: the connection's default model).
|
|
223
|
+
*/
|
|
224
|
+
model?: string;
|
|
225
|
+
/** Its runs are sessions: they wait for follow-up messages after every turn. */
|
|
226
|
+
session?: boolean;
|
|
227
|
+
/** The longest a run takes, from a minute to six hours (default: 30 minutes). */
|
|
228
|
+
timeout?: AgentTimeout;
|
|
229
|
+
/** The shared skills of the plugin (`skills/<name>/`) the agent has besides its own. */
|
|
230
|
+
skills?: readonly string[];
|
|
231
|
+
/**
|
|
232
|
+
* A topic of the plugin (one of `plugin({ topics })`) the platform invalidates, for every key, whenever a run of the
|
|
233
|
+
* agent changes: its status, a new event, the text being written. Screens that follow it re-read the run through
|
|
234
|
+
* the plugin's endpoints (`ctx.agents.get`, `ctx.agents.events`).
|
|
235
|
+
*/
|
|
236
|
+
topic?: TopicLike;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* A connection the plugin declares: installing the plugin creates it, not set up, in the
|
|
240
|
+
* workspace, and an owner or admin fills it in. `llm`: a language model provider for agents; `stt`: speech recognition
|
|
241
|
+
* for dictation. The plugin's code never sees it.
|
|
242
|
+
*/
|
|
243
|
+
export interface ConnectionOptions {
|
|
244
|
+
kind: "llm" | "stt";
|
|
245
|
+
/** Its display name (at most 80 characters). */
|
|
246
|
+
title?: string;
|
|
247
|
+
/** What it is for, in a sentence (at most 500 characters). */
|
|
248
|
+
description?: string;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* What a system context (`ctx.asSystem(reason)`) may do on an entity: the scope of `authz:bypass`
|
|
252
|
+
* (`capabilities: { 'authz:bypass': { reason, on: [{ entity: note, ops: ['read'] }] } }`).
|
|
253
|
+
*/
|
|
254
|
+
export interface BypassScope {
|
|
255
|
+
entity: EntityDef<any>;
|
|
256
|
+
ops: readonly ("read" | "create" | "update" | "delete")[];
|
|
257
|
+
}
|
|
258
|
+
export interface PluginOptions {
|
|
259
|
+
/** `^[a-z][a-z0-9]{1,15}$`, not reserved. */
|
|
260
|
+
id: string;
|
|
261
|
+
/** Semver; by default the `version` of the plugin's package.json. */
|
|
262
|
+
version?: string;
|
|
263
|
+
/** Default: the id, humanized. */
|
|
264
|
+
title?: string;
|
|
265
|
+
description?: string;
|
|
266
|
+
roles?: Record<string, RoleDef>;
|
|
267
|
+
/** Extra scopes and the titles of `read` and `write` (implicit). */
|
|
268
|
+
scopes?: Record<string, ScopeOptions>;
|
|
269
|
+
/** `{ 'push:send': 'Reminds clerks of their unpaid orders.' }`: a reason for each. */
|
|
270
|
+
capabilities?: Record<string, string | {
|
|
271
|
+
reason: string;
|
|
272
|
+
on?: readonly BypassScope[];
|
|
273
|
+
}>;
|
|
274
|
+
/** Directory data beyond names: `['members.email']`. */
|
|
275
|
+
permissions?: readonly string[];
|
|
276
|
+
/**
|
|
277
|
+
* The plugin's agents by name (`assistant: { roles: [manager], engine: 'claude' }`); a camelCase key is the
|
|
278
|
+
* snake_case name (`orderHelper` is `order_helper`).
|
|
279
|
+
*/
|
|
280
|
+
agents?: Record<string, AgentOptions>;
|
|
281
|
+
/** The plugin's connections by name (`anthropic: { kind: 'llm', title: 'Shared Anthropic' }`); a camelCase key is the snake_case name. */
|
|
282
|
+
connections?: Record<string, ConnectionOptions>;
|
|
283
|
+
dependencies?: readonly (string | Dependency)[];
|
|
284
|
+
entities?: Record<string, EntityDef<any>>;
|
|
285
|
+
endpoints?: Record<string, EndpointDef<any, any>>;
|
|
286
|
+
/**
|
|
287
|
+
* The kinds of notification the plugin sends (`notification('mention', {..})`, `ctx.notifications`); they need the
|
|
288
|
+
* capability `push:send`.
|
|
289
|
+
*/
|
|
290
|
+
notifications?: readonly NotificationKind[];
|
|
291
|
+
/**
|
|
292
|
+
* The plugin's background jobs by key (`jobs: { remindUnpaid }`); a camelCase key is the snake_case name
|
|
293
|
+
* (`remind_unpaid`).
|
|
294
|
+
*/
|
|
295
|
+
jobs?: Record<string, JobDef<any>>;
|
|
296
|
+
/** How many runs of its jobs one process runs at once, apart from its requests: 1 to 64 (default 16). */
|
|
297
|
+
jobSlots?: number;
|
|
298
|
+
/** Messages no endpoint or entity uses (they follow the others in the descriptor). */
|
|
299
|
+
messages?: readonly MessageDef<any>[];
|
|
300
|
+
/** Enums no message uses. */
|
|
301
|
+
enums?: readonly EnumDef<any>[];
|
|
302
|
+
/** Topics screens follow and endpoints invalidate (`[ORDERS.roles([clerk]), ORDER.authorize(getOrder)]`). */
|
|
303
|
+
topics?: readonly TopicLike[] | Record<string, TopicLike>;
|
|
304
|
+
/** The plugin's UI: `ui.define({ nav, screens, commands, ... })`. */
|
|
305
|
+
ui?: UiDoc;
|
|
306
|
+
/**
|
|
307
|
+
* The run-change hook (or `plugin({..}).onRunChange(handler)`): the platform
|
|
308
|
+
* calls it when a run the plugin sees changes. The descriptor then says `runs: {on_change: true}`.
|
|
309
|
+
*/
|
|
310
|
+
onRunChange?: RunChangeHandler;
|
|
311
|
+
}
|
package/dist/declare.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/** A role of the plugin; its name is its key in `plugin({ roles })`, in snake_case. */
|
|
2
|
+
export class RoleDef {
|
|
3
|
+
options;
|
|
4
|
+
__role = true;
|
|
5
|
+
constructor(options) {
|
|
6
|
+
this.options = options;
|
|
7
|
+
}
|
|
8
|
+
}
|
|
9
|
+
/** `export const manager = role({ title: 'Order manager', strict: true })`. */
|
|
10
|
+
export function role(options = {}) {
|
|
11
|
+
return new RoleDef(options);
|
|
12
|
+
}
|
|
13
|
+
/** The platform's base roles, by their full names. */
|
|
14
|
+
export const workspace = {
|
|
15
|
+
owner: "workspace.owner",
|
|
16
|
+
admin: "workspace.admin",
|
|
17
|
+
member: "workspace.member",
|
|
18
|
+
guest: "workspace.guest",
|
|
19
|
+
};
|
|
20
|
+
/** An endpoint; its name is its key in `plugin({ endpoints })` in PascalCase (`placeOrder` → `PlaceOrder`). */
|
|
21
|
+
export class EndpointDef {
|
|
22
|
+
options;
|
|
23
|
+
/** @internal The declaration this one was derived from (`.ui()` and the rest return new ones); UI references
|
|
24
|
+
* resolve through it, so `ui.call(listOrders)` names the endpoint registered as `listOrders.ui()`. */
|
|
25
|
+
root;
|
|
26
|
+
constructor(options, root) {
|
|
27
|
+
this.options = options;
|
|
28
|
+
this.root = root ?? this;
|
|
29
|
+
}
|
|
30
|
+
with(extra) {
|
|
31
|
+
return new EndpointDef({ ...this.options, ...extra }, this.root);
|
|
32
|
+
}
|
|
33
|
+
/** Screens may call it (see `EndpointOptions.ui`). */
|
|
34
|
+
ui() {
|
|
35
|
+
return this.with({ ui: true });
|
|
36
|
+
}
|
|
37
|
+
/** The endpoint only reads: its scope is `read`, and UI queries may call it. */
|
|
38
|
+
readOnly() {
|
|
39
|
+
return this.with({ readOnly: true });
|
|
40
|
+
}
|
|
41
|
+
/** After a 2xx answer the platform invalidates the topic (see `EndpointOptions.invalidates`). */
|
|
42
|
+
invalidates(...topics) {
|
|
43
|
+
return this.with({ invalidates: [...(this.options.invalidates ?? []), ...topics] });
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
export function endpoint(options) {
|
|
47
|
+
return new EndpointDef(options);
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* @internal The name each endpoint has in its plugin's descriptor and its request message (an inline input's
|
|
51
|
+
* generated one), set when the plugin is described: what an ask's button sends.
|
|
52
|
+
*/
|
|
53
|
+
export const describedEndpoints = new WeakMap();
|
|
54
|
+
/** @internal Milliseconds of a duration, or `undefined` when it cannot be read. */
|
|
55
|
+
export function durationMs(d) {
|
|
56
|
+
if (typeof d === "number")
|
|
57
|
+
return Number.isFinite(d) ? d : undefined;
|
|
58
|
+
const m = typeof d === "string" ? /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(d) : null;
|
|
59
|
+
return m ? Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2]] : undefined;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* A background job; its name is its key in `plugin({ jobs })` in snake_case (`remindUnpaid` → `remind_unpaid`), and
|
|
63
|
+
* `ctx.jobs.enqueue(remindUnpaid, {..})` starts a run of it.
|
|
64
|
+
*/
|
|
65
|
+
export class JobDef {
|
|
66
|
+
options;
|
|
67
|
+
__job = true;
|
|
68
|
+
constructor(options) {
|
|
69
|
+
this.options = options;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* `export const remindUnpaid = job({ payload: { olderThanDays: t.int() }, cron: '0 9 * * 1-5', as: 'system',
|
|
74
|
+
* async handler(ctx, p) { .. } })`, listed in `plugin({ jobs: { remindUnpaid } })`.
|
|
75
|
+
*/
|
|
76
|
+
export function job(options) {
|
|
77
|
+
return new JobDef(options);
|
|
78
|
+
}
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
import { type RoleLike } from "./ctx.js";
|
|
2
|
+
import { JobDef, type EndpointOptions, type JobOptions, type PluginOptions } from "./declare.js";
|
|
3
|
+
import { EntityDef, MessageDef, type IoType } from "./schema.js";
|
|
4
|
+
export interface DescriptorField {
|
|
5
|
+
name: string;
|
|
6
|
+
number: number;
|
|
7
|
+
type: string;
|
|
8
|
+
repeated: boolean;
|
|
9
|
+
optional: boolean;
|
|
10
|
+
description: string;
|
|
11
|
+
/** Entity columns only, each written only when declared. */
|
|
12
|
+
unique?: true;
|
|
13
|
+
index?: true;
|
|
14
|
+
encrypted?: true;
|
|
15
|
+
searchable?: string;
|
|
16
|
+
nav?: string;
|
|
17
|
+
inverse?: string;
|
|
18
|
+
on_delete?: string;
|
|
19
|
+
}
|
|
20
|
+
export interface Descriptor {
|
|
21
|
+
schema: 1;
|
|
22
|
+
id: string;
|
|
23
|
+
version: string;
|
|
24
|
+
title: string;
|
|
25
|
+
description: string;
|
|
26
|
+
roles: {
|
|
27
|
+
name: string;
|
|
28
|
+
title: string;
|
|
29
|
+
description: string;
|
|
30
|
+
strict: boolean;
|
|
31
|
+
default_for: string;
|
|
32
|
+
}[];
|
|
33
|
+
scopes: {
|
|
34
|
+
name: string;
|
|
35
|
+
title: string;
|
|
36
|
+
description: string;
|
|
37
|
+
sensitive: boolean;
|
|
38
|
+
}[];
|
|
39
|
+
/** `on`: the scope of `authz:bypass`, written only when declared. */
|
|
40
|
+
capabilities: {
|
|
41
|
+
name: string;
|
|
42
|
+
reason: string;
|
|
43
|
+
on?: {
|
|
44
|
+
entity: string;
|
|
45
|
+
ops: string[];
|
|
46
|
+
}[];
|
|
47
|
+
}[];
|
|
48
|
+
permissions: string[];
|
|
49
|
+
agents: {
|
|
50
|
+
name: string;
|
|
51
|
+
roles: string[];
|
|
52
|
+
workspace?: string[];
|
|
53
|
+
delegates?: string[];
|
|
54
|
+
connection?: string;
|
|
55
|
+
ssh_key?: true;
|
|
56
|
+
admin?: true;
|
|
57
|
+
title?: string;
|
|
58
|
+
description?: string;
|
|
59
|
+
icon?: string;
|
|
60
|
+
engine?: string;
|
|
61
|
+
model?: string;
|
|
62
|
+
session?: true;
|
|
63
|
+
timeout_s?: number;
|
|
64
|
+
skills?: string[];
|
|
65
|
+
topic?: string;
|
|
66
|
+
}[];
|
|
67
|
+
/** Written only when declared. */
|
|
68
|
+
connections?: {
|
|
69
|
+
name: string;
|
|
70
|
+
kind: string;
|
|
71
|
+
title?: string;
|
|
72
|
+
description?: string;
|
|
73
|
+
}[];
|
|
74
|
+
/** `reads`: written only when declared. */
|
|
75
|
+
dependencies: {
|
|
76
|
+
plugin: string;
|
|
77
|
+
calls: string[];
|
|
78
|
+
reads?: {
|
|
79
|
+
entity: string;
|
|
80
|
+
fields: {
|
|
81
|
+
name: string;
|
|
82
|
+
type: string;
|
|
83
|
+
}[];
|
|
84
|
+
}[];
|
|
85
|
+
}[];
|
|
86
|
+
enums: {
|
|
87
|
+
name: string;
|
|
88
|
+
values: string[];
|
|
89
|
+
}[];
|
|
90
|
+
/** `kind`: `job` for a job's payload. */
|
|
91
|
+
messages: {
|
|
92
|
+
name: string;
|
|
93
|
+
kind: "message" | "job";
|
|
94
|
+
description: string;
|
|
95
|
+
fields: DescriptorField[];
|
|
96
|
+
}[];
|
|
97
|
+
entities: {
|
|
98
|
+
name: string;
|
|
99
|
+
message: string;
|
|
100
|
+
key: string;
|
|
101
|
+
label: string;
|
|
102
|
+
soft_delete: boolean;
|
|
103
|
+
version: boolean;
|
|
104
|
+
append_only: boolean;
|
|
105
|
+
fields: DescriptorField[];
|
|
106
|
+
/** Written only when declared. */
|
|
107
|
+
indexes?: {
|
|
108
|
+
columns: {
|
|
109
|
+
name: string;
|
|
110
|
+
desc?: true;
|
|
111
|
+
}[];
|
|
112
|
+
unique?: true;
|
|
113
|
+
}[];
|
|
114
|
+
/** The access rules; written only when declared. */
|
|
115
|
+
access?: Record<string, unknown>;
|
|
116
|
+
}[];
|
|
117
|
+
endpoints: {
|
|
118
|
+
name: string;
|
|
119
|
+
input: string;
|
|
120
|
+
output: string;
|
|
121
|
+
description: string;
|
|
122
|
+
auth: string;
|
|
123
|
+
roles: string[];
|
|
124
|
+
scopes: string[];
|
|
125
|
+
idempotency: string;
|
|
126
|
+
timeout_ms: number;
|
|
127
|
+
/** `ui` endpoints only (written when true). */
|
|
128
|
+
read_only?: boolean;
|
|
129
|
+
/** Written when true. */
|
|
130
|
+
ui?: boolean;
|
|
131
|
+
/** Written when the endpoint invalidates topics. */
|
|
132
|
+
invalidates?: Record<string, unknown>[];
|
|
133
|
+
}[];
|
|
134
|
+
/** Written only when declared, so plugins without them describe as before. */
|
|
135
|
+
topics?: {
|
|
136
|
+
name: string;
|
|
137
|
+
key: string;
|
|
138
|
+
description: string;
|
|
139
|
+
roles?: string[];
|
|
140
|
+
scopes?: string[];
|
|
141
|
+
authorize?: string;
|
|
142
|
+
manual?: boolean;
|
|
143
|
+
}[];
|
|
144
|
+
/** The UI document (`ui.define(..)`), written only when declared. */
|
|
145
|
+
ui?: Record<string, unknown>;
|
|
146
|
+
/** The notification kinds; written only when declared, every member of each. */
|
|
147
|
+
notifications?: {
|
|
148
|
+
name: string;
|
|
149
|
+
title: string;
|
|
150
|
+
description: string;
|
|
151
|
+
tab: string;
|
|
152
|
+
digest: boolean;
|
|
153
|
+
}[];
|
|
154
|
+
/** What the plugin asks of agent runs; written only when it handles the run-change hook. */
|
|
155
|
+
runs?: {
|
|
156
|
+
on_change: true;
|
|
157
|
+
};
|
|
158
|
+
/** The background jobs; written only when declared, each optional member only when declared. */
|
|
159
|
+
jobs?: {
|
|
160
|
+
name: string;
|
|
161
|
+
payload: string;
|
|
162
|
+
description?: string;
|
|
163
|
+
cron?: string;
|
|
164
|
+
as_system?: true;
|
|
165
|
+
retry?: {
|
|
166
|
+
retries: number;
|
|
167
|
+
delay_ms: number;
|
|
168
|
+
backoff: "fixed" | "exponential";
|
|
169
|
+
};
|
|
170
|
+
timeout_ms?: number;
|
|
171
|
+
concurrency?: number;
|
|
172
|
+
}[];
|
|
173
|
+
}
|
|
174
|
+
/** A definition error: `error[E_CODE] at <path>: <message>`. */
|
|
175
|
+
export interface DescribeError {
|
|
176
|
+
code: string;
|
|
177
|
+
path: string;
|
|
178
|
+
message: string;
|
|
179
|
+
help?: string;
|
|
180
|
+
}
|
|
181
|
+
export declare function formatError(e: DescribeError): string;
|
|
182
|
+
/** Thrown by `plugin.describe()` when the definition has errors. */
|
|
183
|
+
export declare class DescribeErrors extends Error {
|
|
184
|
+
readonly errors: DescribeError[];
|
|
185
|
+
constructor(errors: DescribeError[]);
|
|
186
|
+
}
|
|
187
|
+
/** An endpoint ready to serve. */
|
|
188
|
+
export interface ResolvedEndpoint {
|
|
189
|
+
key: string;
|
|
190
|
+
name: string;
|
|
191
|
+
input: MessageDef<any> | EntityDef<any>;
|
|
192
|
+
output: MessageDef<any> | EntityDef<any>;
|
|
193
|
+
timeoutMs: number;
|
|
194
|
+
handler: EndpointOptions<IoType, IoType>["handler"];
|
|
195
|
+
/** A request of the platform itself (the run-change hook): refused (404) when it carries a caller. */
|
|
196
|
+
system?: boolean;
|
|
197
|
+
/** Reads the body instead of the input message (throws an `RpcError`). */
|
|
198
|
+
decode?: (body: unknown) => unknown;
|
|
199
|
+
}
|
|
200
|
+
/** The reserved method of the run-change hook: `/<id>.v1.<Service>/_RunChange`. */
|
|
201
|
+
export declare const RUN_CHANGE_METHOD = "_RunChange";
|
|
202
|
+
/** A job ready to run. */
|
|
203
|
+
export interface ResolvedJob {
|
|
204
|
+
def: JobDef<any>;
|
|
205
|
+
name: string;
|
|
206
|
+
payload: MessageDef<any>;
|
|
207
|
+
handler: JobOptions<any>["handler"];
|
|
208
|
+
}
|
|
209
|
+
/** The runs a process starts at once by default, and the most it may announce. */
|
|
210
|
+
export declare const DEFAULT_JOB_SLOTS = 16;
|
|
211
|
+
export declare const MAX_JOB_SLOTS = 64;
|
|
212
|
+
export interface Resolved {
|
|
213
|
+
descriptor: Descriptor;
|
|
214
|
+
errors: DescribeError[];
|
|
215
|
+
endpoints: ResolvedEndpoint[];
|
|
216
|
+
/** The jobs by name. */
|
|
217
|
+
jobs: Map<string, ResolvedJob>;
|
|
218
|
+
/** The job pool's size, announced at registration (0: no jobs). */
|
|
219
|
+
jobSlots: number;
|
|
220
|
+
roleName: (role: RoleLike) => string | undefined;
|
|
221
|
+
}
|
|
222
|
+
export declare const RESERVED_IDS: string[];
|
|
223
|
+
export declare const CAPABILITIES: string[];
|
|
224
|
+
/** Milliseconds of a timeout option, or `undefined` when it cannot be read. */
|
|
225
|
+
export declare function timeoutMs(timeout: unknown): number | undefined;
|
|
226
|
+
/** Whole seconds of an agent's timeout (`'90s'`, `'15m'`, `'2h'`), or `undefined` when it cannot be read. */
|
|
227
|
+
export declare function agentTimeoutSeconds(timeout: unknown): number | undefined;
|
|
228
|
+
/** Builds the descriptor and the serving model; definition errors are collected, not thrown. */
|
|
229
|
+
export declare function resolve(options: PluginOptions, version: string | undefined): Resolved;
|