@skillcdn/console 0.4.3 → 0.4.5

package/src/plugin/bridge.ts

@@ -3,8 +3,18 @@
 // frame the console's origin alone. The shapes and their guards, with no DOM in them, so that the
 // page's side and the frame's side read the same words and the tests need no browser.
 
+import { WEEK_STARTS, type WeekStart } from "../vocabulary.js";
+
 export const PLUGIN_BRIDGE_VERSION = 1;
 
+/**
+ * The sizes a widget comes in (ADR-0061): columns and rows of the front page's grid of square
+ * cells, `small` 2×2, `medium` 4×2, `large` 4×4, `wide` 8×2, `full` 8×4. Here, so that a bundle
+ * learns them without the manifest's schema.
+ */
+export const PLUGIN_WIDGET_SIZE_NAMES = ["small", "medium", "large", "wide", "full"] as const;
+export type PluginWidgetSizeName = (typeof PLUGIN_WIDGET_SIZE_NAMES)[number];
+
 /** What the frame may ask the page to perform, each under `/api/v1/plugins/<key>/` and nothing else. */
 export const BRIDGE_METHODS = [
   "command",
@@ -14,6 +24,7 @@ export const BRIDGE_METHODS = [
   "records.versions",
   "files.get",
   "files.put",
+  "people.picture",
 ] as const;
 
 export type BridgeMethod = (typeof BRIDGE_METHODS)[number];
@@ -31,6 +42,17 @@ export interface BridgePerson {
   readonly admin: boolean;
 }
 
+/** The workspace as a page lays itself out for it: what it is called, the languages it writes in, its clock and the day its week begins on. */
+export interface BridgeWorkspace {
+  readonly name: string;
+  readonly languages: readonly string[];
+  readonly timeZone: string;
+  /** The workspace's setting (ADR-0035): `auto` leaves the week to the language of the pages. */
+  readonly weekStart: WeekStart;
+  /** The day a week begins on with the setting applied, for a calendar to start from: 1 for Monday, 7 for Sunday. */
+  readonly firstDay: number;
+}
+
 /** What the page tells the frame once it is ready: who looks, at what, in which words and colours. */
 export interface BridgeInit {
   readonly v: 1;
@@ -38,8 +60,12 @@ export interface BridgeInit {
   readonly plugin: { readonly key: string; readonly version: string };
   readonly page?: string;
   readonly widget?: string;
+  /** The size the widget's frame has (ADR-0059), one of the sizes the manifest declared for it; none for a page. */
+  readonly size?: PluginWidgetSizeName;
   readonly project: { readonly key: string; readonly name: string } | null;
   readonly person: BridgePerson;
+  /** The workspace; none from a console older than this. */
+  readonly workspace?: BridgeWorkspace;
   readonly roles: readonly string[];
   /** What follows the page's key in the address. */
   readonly path: string;
@@ -82,7 +108,20 @@ export interface BridgePath {
   readonly path: string;
 }
 
-export type BridgeToFrame = BridgeInit | BridgeResult | BridgeEvent | BridgeTheme | BridgePath;
+/** The person gave the widget another size (ADR-0059): the frame lays itself out for it. */
+export interface BridgeSize {
+  readonly v: 1;
+  readonly t: "size";
+  readonly size: PluginWidgetSizeName;
+}
+
+export type BridgeToFrame =
+  | BridgeInit
+  | BridgeResult
+  | BridgeEvent
+  | BridgeTheme
+  | BridgePath
+  | BridgeSize;
 
 export interface BridgeReady {
   readonly v: 1;
@@ -121,19 +160,41 @@ export interface BridgeDownload {
   readonly id: string;
 }
 
+/**
+ * A link a person pressed in the frame, for the console's page to open in a new tab (ADR-0067):
+ * the frame's sandbox opens no window itself, and the page opens one only for a web or a mail
+ * address, and only right after a person pressed.
+ */
+export interface BridgeOpen {
+  readonly v: 1;
+  readonly t: "open";
+  readonly url: string;
+}
+
 export interface BridgeSubscribe {
   readonly v: 1;
   readonly t: "subscribe";
   readonly kinds: readonly BridgeEventKind[];
 }
 
+/**
+ * The frame has nothing to show: the plugin is off, or the page is not one of its own. The console
+ * serves such a frame a document with no words, and the console's page says so in its own.
+ */
+export interface BridgeUnavailable {
+  readonly v: 1;
+  readonly t: "unavailable";
+}
+
 export type BridgeToPage =
   | BridgeReady
+  | BridgeUnavailable
   | BridgeCall
   | BridgeNavigate
   | BridgeResize
   | BridgeTitle
   | BridgeDownload
+  | BridgeOpen
   | BridgeSubscribe;
 
 /** A path of the console's, as `navigate` and `path` carry one: absolute, no scheme, no host, one line. */
@@ -163,6 +224,37 @@ export function isBridgePath(value: unknown): value is string {
   );
 }
 
+/** The schemes a link pressed in a frame may open in a new tab: the web, and mail. Nothing that runs. */
+const OPENABLE_SCHEMES: ReadonlySet<string> = new Set(["https:", "http:", "mailto:"]);
+export const MAX_BRIDGE_URL_LENGTH = 2048;
+
+/** True for an address the page may open in a new tab for a frame: an absolute web or mail address, one line. */
+export function isBridgeUrl(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > MAX_BRIDGE_URL_LENGTH ||
+    /\s/.test(value) ||
+    [...value].some((character) => {
+      const code = character.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f;
+    }) ||
+    !URL.canParse(value)
+  ) {
+    return false;
+  }
+  return OPENABLE_SCHEMES.has(new URL(value).protocol);
+}
+
+/**
+ * True for an address the page opens for a frame (ADR-0067): a web or a mail address that is not
+ * the console's own, given as `origin`, since a page of the console's is `navigate`'s, in the
+ * person's tab.
+ */
+export function isOpenableFrom(value: unknown, origin: string): value is string {
+  return isBridgeUrl(value) && new URL(value).origin !== origin;
+}
+
 function isTheme(value: unknown): value is Record<string, string> {
   if (!isRecord(value)) {
     return false;
@@ -177,6 +269,21 @@ function isTheme(value: unknown): value is Record<string, string> {
   );
 }
 
+function isWorkspace(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    Array.isArray(value.languages) &&
+    value.languages.every((language) => typeof language === "string") &&
+    isLine(value.timeZone, 100) &&
+    (WEEK_STARTS as readonly unknown[]).includes(value.weekStart) &&
+    typeof value.firstDay === "number" &&
+    Number.isInteger(value.firstDay) &&
+    value.firstDay >= 1 &&
+    value.firstDay <= 7
+  );
+}
+
 function isEnvelope(value: unknown): value is Record<string, unknown> & { t: string } {
   return isRecord(value) && value.v === PLUGIN_BRIDGE_VERSION && typeof value.t === "string";
 }
@@ -194,6 +301,8 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
         isLine(value.plugin.version, 64) &&
         (value.page === undefined || isLine(value.page, 32)) &&
         (value.widget === undefined || isLine(value.widget, 32)) &&
+        (value.size === undefined ||
+          (PLUGIN_WIDGET_SIZE_NAMES as readonly unknown[]).includes(value.size)) &&
         (value.project === null ||
           (isRecord(value.project) &&
             isLine(value.project.key, 64) &&
@@ -204,6 +313,7 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
         (value.person.name === null || typeof value.person.name === "string") &&
         typeof value.person.language === "string" &&
         typeof value.person.admin === "boolean" &&
+        (value.workspace === undefined || isWorkspace(value.workspace)) &&
         Array.isArray(value.roles) &&
         value.roles.every((role) => typeof role === "string") &&
         typeof value.path === "string" &&
@@ -229,6 +339,8 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
       return isTheme(value.theme);
     case "path":
       return typeof value.path === "string" && value.path.length <= MAX_BRIDGE_PATH_LENGTH;
+    case "size":
+      return (PLUGIN_WIDGET_SIZE_NAMES as readonly unknown[]).includes(value.size);
     default:
       return false;
   }
@@ -241,6 +353,7 @@ export function isBridgeToPage(value: unknown): value is BridgeToPage {
   }
   switch (value.t) {
     case "ready":
+    case "unavailable":
       return true;
     case "call":
       return (
@@ -261,6 +374,8 @@ export function isBridgeToPage(value: unknown): value is BridgeToPage {
       );
     case "download":
       return isLine(value.id, MAX_ID_LENGTH);
+    case "open":
+      return isBridgeUrl(value.url);
     case "subscribe":
       return (
         Array.isArray(value.kinds) &&
@@ -307,6 +422,12 @@ export interface BridgeFilesPutParams {
 }
 
 /** What `files.get` answers: the bytes, transferred, with the file's name and type. */
+/** A person's picture, as the page hands it to the frame (ADR-0063). */
+export interface BridgePicture {
+  readonly type: string;
+  readonly bytes: ArrayBuffer;
+}
+
 export interface BridgeFile {
   readonly name: string;
   readonly type: string;

package/src/plugin/capabilities.ts

@@ -8,6 +8,8 @@ export const PLUGIN_CAPABILITIES = [
   "files",
   "people:read",
   "people:read:all",
+  "people:read:email",
+  "people:act",
   "projects:read",
   "projects:read:all",
   "board:read",
@@ -19,10 +21,18 @@ export const PLUGIN_CAPABILITIES = [
   "jobs",
   "endpoints",
   "storage:sql",
+  "outbound:webrtc",
 ] as const;
 
 export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];
 
+/**
+ * WebRTC on a plugin's pages (ADR-0066). It stands with `outbound:<host>` as a way to the internet,
+ * and it is no host: a connection goes from a person's browser to any address a page names, which
+ * no host could bound, so that consent to a host does not open it, and it opens no host.
+ */
+export const OUTBOUND_WEBRTC: PluginCapability = "outbound:webrtc";
+
 /** The capabilities that carry a parameter: a host to reach, a plugin to call. */
 export const PLUGIN_CAPABILITY_PREFIXES = ["outbound:", "plugins:"] as const;
 
@@ -52,6 +62,15 @@ export const CAPABILITY_WORDS: Readonly<Record<PluginCapability, CapabilityWords
     opens: "everyone in the workspace, for its jobs and hooks too",
     reach: "the directory",
   },
+  "people:read:email": {
+    opens: "the work email of the people it may read, to match them to accounts elsewhere",
+    reach: "the addresses of the people its role holders may see",
+  },
+  "people:act": {
+    opens:
+      "acting for a person who did something elsewhere: a command run and a decision answered as them, within what they may do, recorded as theirs through the plugin",
+    reach: "what its role holders may do, done in their name from elsewhere",
+  },
   "projects:read": {
     opens: "the projects and members the caller may see",
     reach: "what the person sees",
@@ -97,6 +116,10 @@ export const CAPABILITY_WORDS: Readonly<Record<PluginCapability, CapabilityWords
     opens: "a schema and a login role of its own in the console's database",
     reach: "statements up to the timeout, within its schema",
   },
+  "outbound:webrtc": {
+    opens: "WebRTC on its pages: connections from each person's browser to any address",
+    reach: "what its pages are shown, sent anywhere from the person's browser; their address",
+  },
 };
 
 /** True for a capability the catalogue knows, parameter included. */
@@ -137,7 +160,11 @@ export function capabilityWords(capability: string): CapabilityWords | undefined
 
 /** True when the request's host is within what `outbound:<host>` names: the host itself, or a subdomain where the capability starts with `*.`. */
 export function outboundAllows(capability: string, host: string): boolean {
-  if (!capability.startsWith("outbound:") || !isPluginCapability(capability)) {
+  if (
+    !capability.startsWith("outbound:") ||
+    capability === OUTBOUND_WEBRTC ||
+    !isPluginCapability(capability)
+  ) {
     return false;
   }
   const named = capability.slice("outbound:".length);

package/src/plugin/context.ts

@@ -15,7 +15,9 @@ import type {
   RestTask,
   RestTaskInput,
   RestTaskPatch,
+  RestTeam,
 } from "../schemas.js";
+import type { WeekStart } from "../vocabulary.js";
 import type { PluginFileHandle } from "./args.js";
 
 /** A schema as the Standard Schema interface spells one: what every build of zod implements, so that a plugin's own copy validates its records. */
@@ -40,6 +42,16 @@ export type RecordSchemaResult<T> =
 /** The data a record of a collection holds, from its schema. */
 export type RecordData<S> = S extends RecordSchema<infer T> ? T : never;
 
+/**
+ * How long a collection keeps a record: `days` after the moment `by` names, `createdAt` or
+ * `updatedAt` of the record, or an indexed field of its data that holds a day or an instant as
+ * ISO 8601 text; then the console removes the record, with its versions, links and files.
+ */
+export interface CollectionRetention {
+  readonly days: number;
+  readonly by: string;
+}
+
 /** A collection as `defineCollection` yields it: the name, the schema, and what the console indexes and who reads. */
 export interface CollectionDefinition<S extends RecordSchema = RecordSchema> {
   readonly name: string;
@@ -51,6 +63,8 @@ export interface CollectionDefinition<S extends RecordSchema = RecordSchema> {
   readonly read: readonly string[];
   readonly readOwn: readonly string[];
   readonly history: boolean;
+  /** How long a record is kept, or `null` for as long as the plugin is. */
+  readonly retention: CollectionRetention | null;
 }
 
 export interface PluginRecord<T = Record<string, unknown>> {
@@ -199,10 +213,23 @@ export interface PluginInfo {
   readonly dataVersion: number;
   /** The settings as the administrator set them, by key, without the secrets. */
   readonly settings: Readonly<Record<string, unknown>>;
+  /**
+   * The capabilities the plugin holds: those it requires, and the optional ones an administrator
+   * turned on (ADR-0060), so that it offers what it can do. One it does not hold is refused.
+   */
+  readonly capabilities: readonly string[];
   /** The board project, or none. */
   readonly board: { readonly id: string; readonly key: string } | null;
   /** The projects the plugin is on: all, or their keys. */
   readonly projects: "all" | readonly string[];
+  /** The roles other plugins granted to this one (ADR-0072), by their key, so that a plugin says what it lacks. */
+  readonly grants: readonly PluginGrantHeld[];
+}
+
+/** A role of another plugin, held by this one. */
+export interface PluginGrantHeld {
+  readonly plugin: string;
+  readonly role: string;
 }
 
 export interface CallerPerson {
@@ -239,12 +266,43 @@ export interface ConsoleCaller {
   readonly project: CallerProject | null;
 }
 
-export type PluginCaller = PersonCaller | ConsoleCaller;
+/**
+ * Another plugin, calling with the roles granted to it (ADR-0072): from its own job, hook or
+ * webhook, as itself; or for a person who did something elsewhere, with `for`, and then with the
+ * roles the plugin and the person both hold, in the person's language. A plugin that knows only
+ * `person` and `console` refuses the kind, which fails safe.
+ */
+export interface PluginAsCaller {
+  readonly kind: "plugin";
+  /** The calling plugin's key. */
+  readonly plugin: string;
+  readonly roles: readonly string[];
+  /** The person the plugin acts for, or `null` when it acts as itself; never an administrator by that. */
+  readonly for: CallerPerson | null;
+  /** The project the call is on, if any: the one the person's own call was on. */
+  readonly project: CallerProject | null;
+}
+
+export type PluginCaller = PersonCaller | ConsoleCaller | PluginAsCaller;
 
 export interface PluginWorkspace {
   readonly name: string;
   readonly languages: readonly string[];
+  /** The zone the workspace's times of day are read in; `UTC` where none is set, as `timeZoneSet` says. */
   readonly timeZone: string;
+  /**
+   * Whether an administrator set the time zone: `false` where the workspace runs on UTC because
+   * nobody said otherwise, so that a plugin that reads a time of day says so, instead of taking
+   * UTC for a choice.
+   */
+  readonly timeZoneSet: boolean;
+  /** The day the week begins on (ADR-0035): `auto` leaves it to the language of whoever reads. */
+  readonly weekStart: WeekStart;
+  /**
+   * The console's public origin (`PUBLIC_URL`), for a link to the console in what a plugin
+   * writes elsewhere; `null` where the deployment names none.
+   */
+  readonly url: string | null;
   readonly categories: readonly {
     readonly key: string;
     readonly name: string;
@@ -252,7 +310,15 @@ export interface PluginWorkspace {
   }[];
 }
 
+/** An answer given for a person (ADR-0072): the option by its key or by its label, one of the two, and a note. */
+export interface DecisionAnswer {
+  readonly optionKey?: string;
+  readonly option?: string;
+  readonly note?: string;
+}
+
 export interface DecisionAsk {
+  /** In the language of whoever is to answer, as `people.get` says it (ADR-0065). */
   readonly question: string;
   readonly body?: string;
   /**
@@ -261,8 +327,10 @@ export interface DecisionAsk {
    * without comparing labels.
    */
   readonly options: readonly { readonly label: string; readonly key?: string }[];
-  /** Who is to answer: a person who may work in the project; the project's owners when left out. */
+  /** Who is to answer: a person who may work in the project; the administrator who enabled the plugin when left out. */
   readonly deciderId?: string;
+  /** Several to answer (ADR-0057), in place of `deciderId`: any of them may, and the first answer ends it; up to MAX_DECIDERS. */
+  readonly deciderIds?: readonly string[];
   readonly taskId?: string;
   /** The record the decision is for, by which the plugin maps the answer back. */
   readonly about: { readonly collection: string; readonly id: string };
@@ -274,6 +342,19 @@ export interface PluginConsole {
   people: {
     list(options?: { readonly q?: string }): Promise<readonly RestPerson[]>;
     get(id: string): Promise<RestPerson | null>;
+    /**
+     * The active people a role of the plugin was granted to, by name, through a project or with
+     * everyone, and everyone for `defaultRole` (ADR-0063); for a role that follows the reporting
+     * line, whoever manages someone besides (ADR-0068). An administrator holds every role, and is
+     * listed only where they were granted it or manage someone.
+     */
+    granted(role: string): Promise<readonly RestPerson[]>;
+  };
+  /** The teams of the workspace (ADR-0073): a name and its members, among the people the caller may see. */
+  teams: {
+    list(): Promise<readonly RestTeam[]>;
+    /** One team by its key (ADR-0074), what a grant and a person's `teams` name it by. */
+    get(key: string): Promise<RestTeam | null>;
   };
   projects: {
     list(): Promise<readonly RestProject[]>;
@@ -291,6 +372,14 @@ export interface PluginConsole {
     list(project: string): Promise<readonly RestDecision[]>;
     get(id: string): Promise<RestDecision | null>;
     ask(project: string, decision: DecisionAsk): Promise<RestDecision>;
+    /**
+     * Answers a decision for a person who answered elsewhere (ADR-0072), with `people:act`: one on
+     * the person's own plate, addressed to them or a plugin's addressed to someone they manage, up
+     * the reporting line (ADR-0068), and `plugin.forbidden` for any other, whatever they
+     * administer or are a member of. The answer is theirs, through this plugin. A plugin answers
+     * no decision itself.
+     */
+    answer(id: string, answer: DecisionAnswer, as: { readonly for: string }): Promise<RestDecision>;
   };
   documents: {
     list(project: string, folder?: string): Promise<readonly RestDocumentSummary[]>;
@@ -325,28 +414,90 @@ export interface PluginSql extends PluginSqlClient {
   transaction<T>(work: (tx: PluginSqlClient) => Promise<T>): Promise<T>;
 }
 
-/** Where the console puts a secret into an outbound request. */
-export type SecretPlacement = `header:${string}` | `query:${string}` | "basic";
+/**
+ * Where the console puts a secret into an outbound request: a header, as `Authorization: Bearer`,
+ * a query parameter, as basic authentication (`user:password`), or a field of a JSON or a form
+ * body.
+ */
+export type SecretPlacement =
+  | `header:${string}`
+  | "bearer"
+  | `query:${string}`
+  | "basic"
+  | `body:${string}`;
+
+/** One secret setting and where it goes. */
+export interface SecretUse {
+  readonly name: string;
+  readonly as: SecretPlacement;
+}
+
+/**
+ * A value of the answer to seal as a secret setting (ADR-0070): the path to it in the answer's
+ * JSON (`$.access_token`, `$.credentials.signing_secret`, `$.items.0.token`), and, where it
+ * expires, how long it lasts, in seconds or as a path to the seconds (`$.expires_in`). The
+ * console seals the value and hands the plugin the answer with `"[sealed]"` in its place.
+ */
+export type SecretSeal =
+  | string
+  | { readonly path: string; readonly expiresIn?: number | string | undefined };
+
+/**
+ * What became of a value `seal` named (ADR-0070). `sealed`: sealed as the setting, the answer
+ * saying `"[sealed]"` in its place. `absent`: nothing at the path (no such key, `null` or an
+ * empty string); nothing sealed, nothing taken out. `not_a_string`, `too_long` and `echoed`: a
+ * value that is no string, is over the bound of a secret (4,096 characters), or holds a secret
+ * the request carried from another setting; never sealed and never handed over, the answer saying
+ * `"[withheld]"` in its place. `not_json`: an answer that is no JSON object or array, whose body
+ * is withheld whole. Only `sealed` changed the setting.
+ */
+export type SealOutcome = "sealed" | "absent" | "not_a_string" | "too_long" | "echoed" | "not_json";
 
 export interface PluginFetchInit {
+  /** `GET` unless said; `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`, and no other. */
   readonly method?: string;
   readonly headers?: Readonly<Record<string, string>>;
   readonly body?: string | Uint8Array;
-  /** A secret setting, put where `as` says: a header, a query parameter, or as basic authentication (`user:password`). */
-  readonly secret?: { readonly name: string; readonly as: SecretPlacement };
-}
-
-/** An outbound answer, whole: the host reads it to the bound before handing it over. */
+  /** A secret setting, put where `as` says. */
+  readonly secret?: SecretUse;
+  /** Several, where a request carries more than one: a client secret in the body and a token as a bearer, say. */
+  readonly secrets?: readonly SecretUse[];
+  /** Values of the answer to seal as secret settings, by the setting's name, never handed to the plugin. */
+  readonly seal?: Readonly<Record<string, SecretSeal>>;
+}
+
+/**
+ * An outbound answer, whole: the host reads it to the bound before handing it over, a redirect as
+ * it is, never followed. Every form of a secret the request carried, and of a value sealed or
+ * withheld, is taken out of its headers and its body first, `"[withheld]"` in its place.
+ */
 export interface PluginFetchResponse {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;
   readonly bytes: Uint8Array;
+  /** What became of each value `seal` named, by the setting's name; there where the request named `seal`. */
+  readonly sealed?: Readonly<Record<string, SealOutcome>>;
   text(): string;
   json(): unknown;
 }
 
+/** How a secret stands: whether it is set and not expired, when it expires, and where it came from. */
+export interface SecretStatus {
+  /** Set, and not past its expiry. */
+  readonly set: boolean;
+  readonly setAt: string | null;
+  /** When it expires, or `null` for a secret that does not. */
+  readonly expiresAt: string | null;
+  /** `administrator` for one an administrator set; the host of the answer it was sealed from otherwise; `null` while unset. */
+  readonly source: string | null;
+}
+
 export interface PluginSecrets {
+  /** Whether the secret is set and not past its expiry. */
   has(name: string): Promise<boolean>;
+  /** How the secret stands, for a settings page to say and a job to decide whether to renew it. */
+  status(name: string): Promise<SecretStatus>;
+  /** Signs with the secret; refused for a secret declared `use: "verify"`, which signs nothing. */
   sign(name: string, payload: string | Uint8Array, algorithm: "hmac-sha256"): Promise<string>;
   verify(
     name: string,
@@ -359,6 +510,23 @@ export interface PluginSecrets {
 export interface OtherPlugin {
   readonly version: string;
   readonly api: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+  /**
+   * The same plugin, called for a person who did something elsewhere (ADR-0072): with the roles
+   * this plugin and the person both hold in it, in the person's language, what it reads of the
+   * console the person's as a member's, whatever they administer, recorded as theirs through this
+   * plugin. Needs `people:act`; the person is active, or the call is `plugin.not_found`.
+   */
+  for(personId: string): OtherPlugin;
+}
+
+/** The plugin's own endpoints, as a service elsewhere is told to call them. */
+export interface PluginEndpoints {
+  /**
+   * The full address of an endpoint the plugin defines, under the console's public origin, to
+   * register a callback or a webhook with a service elsewhere; `plugin.not_found` for a name the
+   * plugin does not define, `plugin.unavailable` where the console has no public address.
+   */
+  url(name: string): Promise<string>;
 }
 
 export interface PluginLog {
@@ -382,6 +550,7 @@ export interface PluginContext {
   fetch(url: string, init?: PluginFetchInit): Promise<PluginFetchResponse>;
   readonly secrets: PluginSecrets;
   readonly plugins: { get(key: string): Promise<OtherPlugin> };
+  readonly endpoints: PluginEndpoints;
   readonly log: PluginLog;
   now(): Date;
   /** The caller's language, `en` for the console. */
@@ -393,6 +562,14 @@ export interface PluginContext {
 /** An event a hook receives: the console's, of the plugin's board projects, or another plugin's. */
 export interface PluginHookEvent {
   readonly source: "console" | "plugin";
+  /**
+   * The event's id, one per event across both streams (`console:<number>` or `plugin:<number>`):
+   * delivery is at least once, so a hook that must not act twice keeps the ids it acted on and
+   * passes over one it has seen.
+   */
+  readonly id: string;
+  /** Which delivery of the event this is: 1 the first time, more after a failure and its retries. */
+  readonly attempt: number;
   /** `console:<kind>` or `plugin:<key>:<kind>`, as the hook was named. */
   readonly kind: string;
   readonly at: string;