@indy-center/indy-larry-worker 1.1.0 → 1.3.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/dist/api.d.ts CHANGED
@@ -8,6 +8,13 @@ export type AllowedMentions = {
8
8
  /** Role IDs that may ping (not with `parse: ['roles']`). */
9
9
  roles?: string[];
10
10
  };
11
+ /** A button that opens a web address. */
12
+ export type LinkButton = {
13
+ /** Up to 80 characters. */
14
+ label: string;
15
+ /** An http(s) address, up to 512 characters. */
16
+ url: string;
17
+ };
11
18
  /** A message to send as Larry. At least one of `content` or `embeds` is required. */
12
19
  export type Message = {
13
20
  /** Up to 2000 characters. Mention a user with `<@userId>`, a role with `<@&roleId>`. */
@@ -20,6 +27,12 @@ export type Message = {
20
27
  * ping more, or `{ parse: [] }` to ping nobody.
21
28
  */
22
29
  allowedMentions?: AllowedMentions;
30
+ /**
31
+ * Up to 5 buttons under the message, each opening a web address. Larry offers no buttons that do
32
+ * something when pressed. On editMessage()/enqueueEdit(), leave it out to keep the buttons the message
33
+ * has, or pass `[]` to remove them.
34
+ */
35
+ buttons?: LinkButton[];
23
36
  };
24
37
  /** A message to a channel. */
25
38
  export type ChannelSend = Message & {
@@ -29,6 +42,21 @@ export type ChannelSend = Message & {
29
42
  */
30
43
  channel: string;
31
44
  };
45
+ /**
46
+ * A change to a message Larry posted in a channel from `SEND_CHANNELS`. What is given replaces what the
47
+ * message had; `content` or `embeds` left out stays as it was. An edit pings nobody.
48
+ */
49
+ export type ChannelEdit = ChannelSend & {
50
+ /** The message's ID, as send() returned it. */
51
+ messageId: string;
52
+ };
53
+ /** A message Larry posted in a channel from `SEND_CHANNELS`, to delete. */
54
+ export type MessageRef = {
55
+ /** The channel name it was sent to, as in ChannelSend. */
56
+ channel: string;
57
+ /** The message's ID, as send() returned it. */
58
+ messageId: string;
59
+ };
32
60
  /** A private message to a user. */
33
61
  export type DirectSend = Message & {
34
62
  /** The user's Discord ID. They must share a server with Larry and allow DMs from it. */
@@ -51,6 +79,11 @@ export type RoleSync = {
51
79
  * Larry never renames a role.
52
80
  */
53
81
  rename?: boolean;
82
+ /**
83
+ * The colour of a role Larry **creates**, as hex (`'#e67e22'` or `'e67e22'`). Not applied to a role
84
+ * that already exists, so a colour chosen in Discord is never overwritten. Leave it out for no colour.
85
+ */
86
+ color?: string;
54
87
  /** Discord user IDs who should hold the role. Someone not in the server is reported and can be tried again later. */
55
88
  members: string[];
56
89
  /**
@@ -166,7 +199,7 @@ export type Sent = {
166
199
  messageId: string;
167
200
  };
168
201
  /**
169
- * Larry's RPC surface, version 1.1.0. Every method checks the message first and throws for an unknown
202
+ * Larry's RPC surface, version 1.3.0. Every method checks the message first and throws for an unknown
170
203
  * channel, a bad user ID, an empty message or one over Discord's limits.
171
204
  */
172
205
  export interface LarryRpc extends Rpc.WorkerEntrypointBranded {
@@ -181,6 +214,20 @@ export interface LarryRpc extends Rpc.WorkerEntrypointBranded {
181
214
  enqueue(request: ChannelSend): Promise<void>;
182
215
  /** Queue a DM, like enqueue(). */
183
216
  enqueueDirect(request: DirectSend): Promise<void>;
217
+ /**
218
+ * Change a message Larry posted, now, and return it. Throws if Discord refuses, including when the
219
+ * message has been deleted or was not Larry's.
220
+ */
221
+ editMessage(request: ChannelEdit): Promise<Sent>;
222
+ /** Queue the same change, like enqueue(). An edit to a message that has since been deleted is dropped. */
223
+ enqueueEdit(request: ChannelEdit): Promise<void>;
224
+ /**
225
+ * Delete a message Larry posted, now. **Cannot be undone.** A message that is already gone counts as
226
+ * deleted. Throws if Discord refuses, e.g. for someone else's message without Manage Messages.
227
+ */
228
+ deleteMessage(request: MessageRef): Promise<void>;
229
+ /** Queue the same deletion and return once it's queued. Delivery retries rate limits and Discord outages. */
230
+ enqueueDelete(request: MessageRef): Promise<void>;
184
231
  /**
185
232
  * Make each role's membership match what is asked for, and report what changed. One role failing
186
233
  * does not stop the rest. Refuses roles that carry moderation permissions. Throws if `GUILD_ID` isn't set.
@@ -214,6 +261,118 @@ export interface LarryRpc extends Rpc.WorkerEntrypointBranded {
214
261
  sendToChannel(request: ChannelIdSend): Promise<Sent>;
215
262
  /** Queue a post to a channel by ID, like enqueue(). The channel is checked before it is queued. */
216
263
  enqueueToChannel(request: ChannelIdSend): Promise<void>;
264
+ /**
265
+ * Link a member's own Discord account, which the caller has already proven they hold, and queue
266
+ * their role sync. Throws "That Discord account is linked to another member." when someone else has
267
+ * it, and "Sign in to flyindycenter.com once before linking." when identity has no user for the CID.
268
+ */
269
+ linkDiscord(cid: number, discordId: string): Promise<void>;
270
+ /**
271
+ * Clear a member's link and queue their role sync, which falls back to the Discord ID VATUSA holds.
272
+ * `'teamspeak'` throws "TeamSpeak links aren't available yet." for now.
273
+ */
274
+ unlink(cid: number, service: 'discord' | 'teamspeak'): Promise<void>;
275
+ /** Which Discord account the role sync uses for a member, and whether it is their link or VATUSA's. */
276
+ getLinks(cid: number): Promise<Links>;
277
+ /**
278
+ * Sync these members now, instead of waiting for the next run: for an app that has just changed
279
+ * something about them (a credential granted, a student assigned). larry reads every group source
280
+ * again, then queues each CID's role sync. Each CID is declined, with a reason to show, when nothing is
281
+ * known to sync or it was synced in the last 2 minutes. At most 100 CIDs a call.
282
+ */
283
+ syncMembers(cids: number[]): Promise<SyncMembersResult>;
284
+ /**
285
+ * Post a notice in a group's room, mentioning `mention` (CIDs). Each mentioned member's roles are
286
+ * synced first, so someone just added to the group can see the room. `'no-room'` when the group has
287
+ * no room (yet), `'not-live'` when the source's group sync isn't `live`.
288
+ */
289
+ postToGroup(request: GroupPost): Promise<GroupPostResult>;
290
+ /** What the last cron run did with a source's groups. */
291
+ getGroupStatus(source: string): Promise<GroupStatus>;
217
292
  }
293
+ /** One group an app serves: who is in it, and whether it has a private room. */
294
+ export type Group = {
295
+ /** Stable within the source; renaming a key makes a new group. */
296
+ key: string;
297
+ /** The group's name, as people should see it: the Discord role's name. */
298
+ name: string;
299
+ /** VATSIM CIDs, digit strings, no duplicates. The whole truth: anyone else loses the role. */
300
+ members: string[];
301
+ room?: {
302
+ /** The room's name, as people should see it. */
303
+ name: string;
304
+ /** Used instead when two rooms' names collide in Discord. */
305
+ fallbackName: string;
306
+ };
307
+ /** Keep this group exactly as it is: don't manage its members, rename or delete it. */
308
+ hold?: true;
309
+ };
310
+ /** What a group source's `getGroups()` answers. */
311
+ export type GroupsAnswer = {
312
+ groups: Group[];
313
+ };
314
+ /** What an app implements, on the entrypoint larry's binding names, to serve groups. */
315
+ export type GroupSource = {
316
+ getGroups(): Promise<GroupsAnswer>;
317
+ };
318
+ /** A notice for a group's room. Plain text: larry escapes Discord's formatting. */
319
+ export type GroupNotice = {
320
+ title: string;
321
+ body: string;
322
+ fields?: {
323
+ name: string;
324
+ value: string;
325
+ }[];
326
+ };
327
+ export type GroupPost = {
328
+ /** The source's name in larry's config, e.g. `'training'`. */
329
+ source: string;
330
+ /** The group's key in that source. */
331
+ key: string;
332
+ notice: GroupNotice;
333
+ /** CIDs to mention. One with no Discord account is left unmentioned. */
334
+ mention?: string[];
335
+ };
336
+ /** `'posted'` means queued. */
337
+ export type GroupPostResult = 'posted' | 'no-room' | 'not-live';
338
+ /** What happened to a role or room in the last run (or would, in `dry-run`). */
339
+ export type GroupState = 'found' | 'created' | 'renamed' | 'held' | 'missing' | 'deleted' | 'failed';
340
+ export type GroupStatus = {
341
+ mode: 'off' | 'dry-run' | 'live';
342
+ /** When the last run read the source; null before the first. */
343
+ at: string | null;
344
+ /** Why the source's answer was refused that run. */
345
+ refused?: string;
346
+ groups: {
347
+ key: string;
348
+ name: string;
349
+ role: GroupState;
350
+ room?: GroupState;
351
+ error?: string;
352
+ }[];
353
+ };
354
+ /** What `syncMembers` answers, one entry per CID asked for. */
355
+ export type SyncMembersResult = ({
356
+ cid: number;
357
+ } & SyncMemberResult)[];
358
+ /** What `getLinks` reports for a member. */
359
+ export type Links = {
360
+ /** The account the sync uses: `linked` when they linked it, `vatusa` when it is the one VATUSA holds. */
361
+ discord: {
362
+ id: string;
363
+ source: 'linked' | 'vatusa';
364
+ } | null;
365
+ /** Always null until TeamSpeak links arrive. */
366
+ teamspeak: {
367
+ uid: string;
368
+ } | null;
369
+ };
370
+ /** What `syncMembers` answers for one CID. */
371
+ export type SyncMemberResult = {
372
+ queued: true;
373
+ } | {
374
+ queued: false;
375
+ reason: string;
376
+ };
218
377
  /** The binding's type in a caller's `Env`: `LARRY: LarryBinding`. */
219
378
  export type LarryBinding = Service<LarryRpc>;
package/dist/index.d.ts CHANGED
@@ -1 +1 @@
1
- export type { AllowedMentions, ChannelIdSend, ChannelSend, ChannelSyncResult, ChannelsResult, ChannelsSync, DeleteRequest, DeleteResult, Deletion, DirectSend, LarryBinding, LarryRpc, ManagedChannel, MemberRole, Message, RoleSync, RoleSyncResult, RolesResult, RolesSync, Sent, } from './api';
1
+ export type { AllowedMentions, ChannelEdit, ChannelIdSend, ChannelSend, ChannelSyncResult, ChannelsResult, ChannelsSync, DeleteRequest, DeleteResult, Deletion, DirectSend, Group, GroupNotice, GroupPost, GroupPostResult, GroupsAnswer, GroupSource, GroupState, GroupStatus, LarryBinding, LarryRpc, LinkButton, Links, ManagedChannel, MemberRole, Message, MessageRef, RoleSync, RoleSyncResult, RolesResult, RolesSync, Sent, SyncMemberResult, SyncMembersResult, } from './api';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@indy-center/indy-larry-worker",
3
- "version": "1.1.0",
3
+ "version": "1.3.0",
4
4
  "description": "Send Discord messages as Larry from other Indy Center Workers, over RPC or a queue",
5
5
  "type": "module",
6
6
  "repository": {