@openbrf/plugin-sdk 1.0.0 → 1.4.0

package/src/host.ts

@@ -1,5 +1,14 @@
-import type { PluginActions } from "./actions.ts";
-import type { PluginPermission } from "./permissions.ts";
+import type { ActionRequest, PluginActions } from "./actions.ts";
+import type { PluginBlocks } from "./blocks.ts";
+import type { PluginExtensions } from "./extensions.ts";
+import type { PluginEntitlements } from "./entitlements.ts";
+import type { PluginFinances } from "./finances.ts";
+import type { PluginImports } from "./imports.ts";
+import type {
+  PluginPermission,
+  PluginPersonalDataCategory,
+} from "./permissions.ts";
+import type { PluginRecords } from "./records.ts";
 import type { PluginSettingsValues } from "./settings-schema.ts";
 
 /**
@@ -47,8 +56,26 @@ export interface PluginSettings {
    * The stored values, with declared defaults applied. Reads the current
    * values on each call rather than caching, so a change made in the admin
    * interface reaches a long-running job without a restart.
+   *
+   * A secret field is in it in clear, which is the one place its value
+   * leaves the host: never write it to the log, a job's payload or anything
+   * a route returns.
    */
   read(): Promise<PluginSettingsValues>;
+  /**
+   * Replaces or clears one of the plugin's own secret fields: `null` clears
+   * it.
+   *
+   * For a credential the far end replaces, such as an OAuth refresh token
+   * that is new after every use. Only a field the manifest declares as
+   * `secret`, checked against its declared bounds; the change is written to
+   * the audit log under the field's key, never with its value.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  writeSecret(key: string, value: string | null): Promise<void>;
 }
 
 export interface PluginMailMessage {
@@ -147,6 +174,12 @@ export interface PluginApartment {
 export interface PluginResident {
   personId: string;
   name: string;
+  /**
+   * The family name alone, for a reader that shows no first names: a household
+   * as the name on the door shows it, without the first names that say who
+   * lives alone and name the children.
+   */
+  lastName: string;
   /** MEMBER holds the tenant-ownership; RESIDENT occupies without holding it. */
   role: "MEMBER" | "RESIDENT";
   apartment: PluginApartment | null;
@@ -156,6 +189,22 @@ export interface PluginResident {
   email?: string | null;
   /** Present only with the addressBook:readContact permission. */
   phone?: string | null;
+  /**
+   * Whether a publication consent to the person's name on screens inside the
+   * building stands (the `NAME_IN_BUILDING` scope), recorded by the board on
+   * the person's panel like every other scope. A different consent from a name
+   * on the website, because the two are different things to agree to.
+   */
+  nameInBuilding: boolean;
+}
+
+/** Narrows a read of the residents. */
+export interface PluginResidentFilter {
+  /**
+   * Only the residents of this entrance, so a plugin that shows one entrance
+   * never loads the others. An id no address has returns nobody.
+   */
+  addressId?: string;
 }
 
 export interface PluginOccupancySummary {
@@ -175,14 +224,631 @@ export interface PluginOccupancySummary {
  * personal identity number is never returned, and nothing is writable.
  * Requires addressBook:read; the contact fields additionally require
  * addressBook:readContact.
+ *
+ * A person who has objected to this plugin's processing, and whose objection
+ * the board granted, is absent as well (ADR 0035) - absent, not flagged, so a
+ * plugin cannot list who objected. Closing the objection brings the person
+ * back on the next read.
  */
 export interface PluginAddressBook {
   apartments(): Promise<PluginApartment[]>;
-  /** Current residencies only. Moved-out rows are not plugin business. */
-  residents(): Promise<PluginResident[]>;
+  /**
+   * Current residencies only. Moved-out rows are not plugin business.
+   *
+   * The filter was added after this contract version shipped; an older host
+   * ignores it and returns every entrance, so a plugin that must not load the
+   * others filters the result by `apartment.address.id` as well.
+   */
+  residents(filter?: PluginResidentFilter): Promise<PluginResident[]>;
   summary(): Promise<PluginOccupancySummary>;
 }
 
+/** The bounds `host.audit.record` holds an entry to. */
+export const PLUGIN_AUDIT_LIMITS = {
+  /** Characters in `event`, which is also part of a text key. */
+  event: 64,
+  /** Characters in `targetKind`. */
+  targetKind: 64,
+  /** Characters in `targetId`. */
+  targetId: 200,
+  /** Values in `detail`. */
+  detailValues: 8,
+  /** Characters in a key of `detail`, letters and digits. */
+  detailKey: 64,
+  /** Characters in a string value of `detail`. */
+  detailValue: 200,
+} as const;
+
+/** One entry a plugin writes to the instance's audit log. */
+export interface PluginAuditEntry {
+  /**
+   * What happened, as lowercase letters, digits, dots and hyphens, starting
+   * with a letter: `screen.residents-enabled`. The audit log shows it through
+   * the plugin's own text key `audit.<event>`.
+   */
+  event: string;
+  /** What the act was done to, in the plugin's own words: `screen`. */
+  targetKind?: string;
+  /** Which one: the screen's id. */
+  targetId?: string;
+  /**
+   * At most eight values about the act, never a copy of what the plugin read.
+   * A key is letters and digits, starting with a letter: `screenCount`. A
+   * person is named as the actor, never here, and a key or value holding a
+   * personal identity number is refused.
+   */
+  detail?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Writing to the instance's audit log (ADR 0035).
+ *
+ * The entry is written as `PLUGIN_RECORDED`, with the plugin's id and the
+ * event, on the plugin channel. With a request, the actor is the person the
+ * host marked on it, as for `actions`; with `null`, the entry has no actor - a
+ * plugin's own job, say. An entry that breaks a bound is refused with a
+ * RangeError and nothing is written. Needs no permission: an entry is about
+ * what the plugin did, which the association is entitled to a record of.
+ */
+export interface PluginAudit {
+  record(request: ActionRequest | null, entry: PluginAuditEntry): Promise<void>;
+}
+
+/** What a theme install is told about the package besides its bytes. */
+export interface PluginThemeInstallOptions {
+  /**
+   * The package's sha512, as whoever published it stated it: `sha512-<base64>`
+   * or 128 hex characters, the two spellings a catalog entry may use. The
+   * bytes are checked against it before anything is unpacked.
+   */
+  sha512: string;
+}
+
+/**
+ * A finding the install lint reported without refusing the theme: a token or
+ * a manifest field this core does not know, which the token contract says to
+ * ignore rather than refuse. Rule codes and numbers, never prose.
+ */
+export interface PluginThemeInstallWarning {
+  rule: string;
+  detail: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface PluginThemeInstallResult {
+  /** The theme's id, from its manifest. */
+  id: string;
+  version: string;
+  warnings: readonly PluginThemeInstallWarning[];
+}
+
+/** A theme this plugin installed, as `host.themes.list` returns it. */
+export interface PluginInstalledTheme {
+  id: string;
+  version: string;
+  /** ISO 8601. When the version now installed was installed first. */
+  installedAt: string;
+}
+
+/**
+ * Installing themes on the instance (ADR 0046). Requires themes:install.
+ *
+ * A theme a plugin hands over takes the path a theme from the catalog takes:
+ * its sha512 checked before anything is unpacked, the package read and held to
+ * the same install lint, the statutory register contrast included, and the
+ * files and the row written together under the same lock per theme id. A
+ * package the lint refuses is refused here with the same findings, and what
+ * the instance already had stays as it was.
+ *
+ * `install` takes the request the plugin's own route received and installs as
+ * the person behind it, who must hold association:manage, the capability the
+ * theme screen requires. A request a connected app's token reached is refused,
+ * and a background job has no request, so a plugin installs a theme only when
+ * an administrator asks it to.
+ *
+ * A plugin installs over a theme it installed itself and over nothing else:
+ * not the catalog's, not one composed on the instance, not another plugin's.
+ * It installs and nothing else. Activating and removing stay on the theme
+ * screen, and a theme stays installed when the plugin is removed.
+ *
+ * A refusal is thrown as an error carrying a `reason` code and, for
+ * `lint-failed`, the `findings`. Let it propagate from a route and the client
+ * is answered with its status, reason and findings, as the theme screen is.
+ */
+export interface PluginThemes {
+  install(
+    request: ActionRequest,
+    archive: Uint8Array,
+    options: PluginThemeInstallOptions,
+  ): Promise<PluginThemeInstallResult>;
+  /** The themes this plugin installed, so it can offer an update. */
+  list(): Promise<PluginInstalledTheme[]>;
+}
+
+/**
+ * Who a news item or an event is for: the members, or anyone at all.
+ *
+ * On every item the content services return, because the host cannot know
+ * where the plugin puts it. A screen inside the building may show a members'
+ * item and a public calendar feed should not; which of the two the plugin is
+ * doing is what its consent screen tells the board (ADR 0032).
+ */
+export type PluginContentAudience = "anyone" | "members";
+
+/** One published news item, as a plugin reads it. */
+export interface PluginNewsItem {
+  readonly id: string;
+  readonly title: string;
+  /** The body's text, one string per paragraph or heading, in order. */
+  readonly paragraphs: readonly string[];
+  /**
+   * The pictures the body shows, in order.
+   *
+   * Empty while a news body holds prose only, which is all the core's news
+   * editor writes and all the website shows of one.
+   */
+  readonly pictures: readonly { mediaFileId: string; alt: string }[];
+  readonly audience: PluginContentAudience;
+  /** ISO 8601 instant. */
+  readonly publishedAt: string;
+  /**
+   * Whether the board marked the item "show on screens": that it may be shown
+   * on a screen in the building (ADR 0050). Off until the board sets it. A
+   * plugin that puts items where anybody passing can read them shows only the
+   * marked ones.
+   */
+  readonly onScreens: boolean;
+}
+
+/**
+ * The association's published news. Requires the news:read permission.
+ *
+ * What the website publishes and nothing more: a draft, an item taken down, a
+ * deleted one and one the board wrote to Styrelsen or Administratörer in the
+ * feed are absent. Never an author, a comment, a like or who has read an item.
+ *
+ * To a plugin that declares a device route, an item whose title, paragraphs or
+ * picture alt texts name somebody the register holds, one of their email
+ * addresses or phone numbers, or an apartment number is absent as well, and
+ * the read goes on to older items to make up the count, as far back as the
+ * newest 500 published items (ADR 0032).
+ */
+export interface PluginNews {
+  /**
+   * Published items, newest first.
+   *
+   * `limit` is 1 to 50 and defaults to 50. `since` is an ISO 8601 instant and
+   * keeps the items published at or after it. `audience` keeps only the items
+   * for that audience; without it both are returned, each saying which it is.
+   * A value outside those bounds is refused with a RangeError.
+   */
+  published(options?: {
+    audience?: PluginContentAudience;
+    limit?: number;
+    since?: string;
+  }): Promise<readonly PluginNewsItem[]>;
+}
+
+/** One occurrence of a published event. */
+export interface PluginOccurrence {
+  readonly eventId: string;
+  readonly occurrenceId: string;
+  /** The board's own words, as written and never translated. */
+  readonly title: string;
+  readonly description: string | null;
+  readonly category: string | null;
+  readonly location: string | null;
+  /** ISO 8601 instant. */
+  readonly startsAt: string;
+  /** ISO 8601 instant. */
+  readonly endsAt: string;
+  /** Whether the board has called this one occurrence off. */
+  readonly calledOff: boolean;
+  /**
+   * Places left when the event takes sign-ups with a limit, and null when it
+   * takes none or has no limit. Never who took them.
+   */
+  readonly placesLeft: number | null;
+  readonly audience: PluginContentAudience;
+  /**
+   * Whether the board marked the event, with all its occurrences, "show on
+   * screens" (ADR 0050), as a news item's mark.
+   */
+  readonly onScreens: boolean;
+}
+
+/**
+ * The notice of a general meeting the board has called.
+ *
+ * What the notice states (EFL 6 kap. 22 §): the time, the place, how to take
+ * part digitally and the matters on the agenda. Never who was summoned, who
+ * attended, the voting register or a proxy.
+ */
+export interface PluginMeetingNotice {
+  readonly meetingId: string;
+  readonly kind: "ordinary" | "extraordinary";
+  /** ISO 8601 instant. */
+  readonly startsAt: string;
+  readonly place: string;
+  readonly digitalParticipation: string | null;
+  readonly agenda: readonly { position: number; title: string }[];
+}
+
+/**
+ * The association's calendar. Requires the calendar:read permission.
+ *
+ * Published events only: a series that is not published is absent, and an
+ * occurrence the board called off is present and says so.
+ *
+ * To a plugin that declares a device route, an event whose title,
+ * description, category or location names somebody the register holds or an
+ * apartment number is absent with every occurrence, and a notice whose place,
+ * digital participation or any agenda title does is absent whole (ADR 0032).
+ */
+export interface PluginCalendar {
+  /**
+   * Occurrences starting in [from, to), soonest first.
+   *
+   * `from` and `to` are ISO 8601 instants at most 92 days apart, and
+   * `audience` works as it does for the news. A range that is not one is
+   * refused with a RangeError.
+   */
+  occurrences(range: {
+    from: string;
+    to: string;
+    audience?: PluginContentAudience;
+  }): Promise<readonly PluginOccurrence[]>;
+  /**
+   * Notices of the general meetings called and not yet held, soonest first.
+   *
+   * A notice summons the members, so every one of them is for the members.
+   */
+  meetingNotices(): Promise<readonly PluginMeetingNotice[]>;
+}
+
+/** A bookable resource the house offers, and how it is booked. */
+export interface PluginBookableResource {
+  readonly id: string;
+  /** The board's own name for it, as written. */
+  readonly name: string;
+  readonly mode: "timeSlots" | "wholeDay" | "dateRange";
+  /** The slot length in the time-slot mode, and null otherwise. */
+  readonly slotMinutes: number | null;
+  /** Minutes after local midnight the resource opens, in the time-slot mode. */
+  readonly opensAtMinute: number | null;
+  /** Minutes after local midnight the resource closes, in the time-slot mode. */
+  readonly closesAtMinute: number | null;
+}
+
+/** A period a resource is taken. Never by whom. */
+export interface PluginBusyInterval {
+  readonly resourceId: string;
+  /** ISO 8601 instant. */
+  readonly start: string;
+  /** ISO 8601 instant. */
+  readonly end: string;
+}
+
+/**
+ * Free and busy for the house's bookable resources. Requires the
+ * bookings:readAvailability permission.
+ *
+ * Less than a resident's own booking screen shows: when a resource is taken,
+ * and nothing about who took it - no booker, no apartment and no booking's
+ * identifier.
+ *
+ * To a plugin that declares a device route, a resource whose name names
+ * somebody the register holds or an apartment number is absent from both
+ * reads, and `busy` starts no earlier than the moment of the call, so no
+ * booking that has ended is in it (ADR 0032).
+ */
+export interface PluginBookings {
+  /** The resources open for booking, by name. A withdrawn one is absent. */
+  resources(): Promise<readonly PluginBookableResource[]>;
+  /**
+   * When each resource is taken in [from, to), per resource and in order.
+   *
+   * `from` and `to` are ISO 8601 instants at most 31 days apart, refused with
+   * a RangeError otherwise. Bookings that overlap or touch are merged into one
+   * interval, so a run of slots cannot be read as one household's habits. A
+   * resource id that is not an offered resource's answers nothing.
+   */
+  busy(range: {
+    from: string;
+    to: string;
+    resourceIds?: readonly string[];
+  }): Promise<readonly PluginBusyInterval[]>;
+}
+
+/**
+ * The bytes of a picture, as a web stream of `Uint8Array` chunks.
+ *
+ * The host hands a real `ReadableStream`. This package compiles against the
+ * language alone and cannot name the platform's type, so it is looked up in the
+ * plugin's own program, as the block's abort signal is: where that has a
+ * `ReadableStream`, from the DOM library or from Node's types, this is it, and
+ * the stream can go into a `Response` or `Readable.fromWeb` as it is. Where it
+ * has none, this is the part of one a plugin can read without them.
+ */
+export type PluginMediaStream = typeof globalThis extends {
+  readonly ReadableStream: { readonly prototype: infer Stream };
+}
+  ? Stream
+  : PluginMediaStreamShape;
+
+/** What every `ReadableStream` has, for a program without the platform's types. */
+interface PluginMediaStreamShape {
+  readonly locked: boolean;
+  cancel(reason?: unknown): Promise<void>;
+  getReader(): {
+    read(): Promise<
+      { done: false; value: Uint8Array } | { done: true; value?: undefined }
+    >;
+    cancel(reason?: unknown): Promise<void>;
+    releaseLock(): void;
+  };
+}
+
+/**
+ * A stored picture the plugin opened.
+ *
+ * What a reply serving it needs and nothing else: not the name it was uploaded
+ * under, which is somebody's own words, and not who uploaded it.
+ */
+export interface PluginMediaFile {
+  /** Identified from the bytes when they were uploaded: an image type. */
+  readonly contentType: string;
+  /** The size of the picture as uploaded, in bytes. */
+  readonly byteSize: number;
+  /**
+   * A keyed hash of the bytes, hex encoded. The same value the core serves the
+   * picture's entity tag from, so a plugin may use it as one too.
+   */
+  readonly checksum: string;
+  /**
+   * Who the picture is for: `anyone`, or the `members`, as the board held it.
+   * The host does not filter for you, because it cannot know where you put it;
+   * see {@link PluginContentAudience}.
+   */
+  readonly audience: PluginContentAudience;
+  /**
+   * The picture's bytes. Read it to the end or cancel it: the host holds the
+   * stored file open until one or the other.
+   */
+  readonly stream: PluginMediaStream;
+}
+
+/**
+ * The association's stored pictures. Requires the media:read permission.
+ *
+ * Only a picture held for anyone or for the members whose upload declared that
+ * it shows no identifiable person (ADR 0032). A photograph of people needs a
+ * publication consent, and the consent the core records is for the website,
+ * not for wherever a plugin puts the picture. Nothing here lists or finds a
+ * picture: a plugin opens one whose id it already holds, such as one the board
+ * picked in the plugin's own view.
+ */
+export interface PluginMedia {
+  /**
+   * Opens one picture.
+   *
+   * Null when the file does not exist and when it is not one a plugin may
+   * read, the two alike, so the answer says nothing about a file the plugin
+   * may not see. A `mediaFileId` that is not a string is refused with a
+   * RangeError.
+   */
+  open(mediaFileId: string): Promise<PluginMediaFile | null>;
+}
+
+/** One of the association's addresses: an entrance, and nobody behind it. */
+export interface PluginAddress {
+  readonly id: string;
+  readonly street: string;
+  /** The street number, as written: "12", "12 B". */
+  readonly number: string;
+}
+
+/**
+ * The association's addresses. Requires the addresses:read permission.
+ *
+ * A fact about the building: never an apartment, a resident or a member, which
+ * is what addressBook:read is for.
+ */
+export interface PluginAddresses {
+  /** Every address, in the order the core's own screens show them. */
+  list(): Promise<readonly PluginAddress[]>;
+}
+
+/**
+ * What a request to a recipient sends as personal data, and about whom.
+ *
+ * The host writes one audit entry per subject before anything is sent, and
+ * a second after, with the outcome; each reaches that person's data subject
+ * access report. A disclosure that names nobody, such as text a board member
+ * typed, is recorded once with no person.
+ */
+export interface PluginDisclosure {
+  /**
+   * The categories the body carries. One or more, each among those the
+   * recipient's declaration says it receives, or nothing is sent.
+   */
+  personalData: readonly PluginPersonalDataCategory[];
+  /**
+   * The ids of the persons the body is about, at most 100. Each must be a
+   * person the host would hand the plugin: a person with protected personal
+   * data, one under a restriction of processing, or an id the register does
+   * not hold refuses the request, and the error does not say which.
+   */
+  subjects: readonly string[];
+}
+
+export interface PluginRecipientRequest {
+  /** `GET` when left out. */
+  method?: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /**
+   * Sent as given, apart from the ones the host writes: `host`,
+   * `content-length`, `transfer-encoding`, `connection` and the other
+   * hop-by-hop headers are refused.
+   */
+  headers?: Readonly<Record<string, string>>;
+  /** At most 16 MiB. */
+  body?: string | Uint8Array;
+  /**
+   * Required whenever the body carries personal data. A request without it
+   * is recorded nowhere, which is right for fetching a list of models and
+   * wrong for anything about a person.
+   */
+  disclosure?: PluginDisclosure;
+  /**
+   * The whole exchange, name lookup and redirects included. 60 seconds when
+   * left out, at most 300.
+   */
+  timeoutMs?: number;
+}
+
+export interface PluginRecipientResponse {
+  /** Whatever the recipient answered, 4xx and 5xx included. */
+  status: number;
+  /** Lowercased names; a repeated header is joined with ", ". */
+  headers: Readonly<Record<string, string>>;
+  /** The whole body, at most 16 MiB. */
+  body: Uint8Array;
+  /** The body as UTF-8. */
+  text(): string;
+  /** The body parsed as JSON. */
+  json(): unknown;
+}
+
+/** Why `host.recipients.fetch` sent nothing, or got no answer. */
+export const PLUGIN_RECIPIENT_ERROR_CODES = [
+  /** The manifest declares no recipient by that id. */
+  "recipient-not-declared",
+  /** The path is not a path on the recipient's origin. */
+  "path-refused",
+  /** The method, a header, the body or the timeout is not one the host sends. */
+  "request-refused",
+  /** The disclosure names a category the recipient is not declared to receive. */
+  "personal-data-not-declared",
+  /** The disclosure names a person the plugin may not send data about. */
+  "subject-refused",
+  /** The origin's host is not an address this instance may connect to. */
+  "address-refused",
+  /** The recipient redirected to another origin, or more than five times. */
+  "redirect-refused",
+  /** No answer: the connection failed or the deadline passed. */
+  "unreachable",
+  /** The answer's body was longer than 16 MiB. */
+  "response-too-large",
+] as const;
+
+export type PluginRecipientErrorCode =
+  (typeof PLUGIN_RECIPIENT_ERROR_CODES)[number];
+
+/**
+ * A request to a recipient the host refused or could not complete.
+ *
+ * The message never repeats the path, a header or the body: a plugin may put
+ * a resident's name in any of them, and the error ends up in the log.
+ */
+export class PluginRecipientError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly recipient: string,
+    readonly code: PluginRecipientErrorCode,
+  ) {
+    super(
+      `Plugin "${pluginId}" could not reach its recipient "${recipient}": ${code}.`,
+    );
+    this.name = "PluginRecipientError";
+  }
+}
+
+/**
+ * The way out to the places the manifest's `recipients` declares (ADR 0037).
+ *
+ * `fetch` reaches the declared origin of the recipient named and nothing
+ * else, through the instance's outbound address rules, and follows a
+ * redirect only within that origin. A request whose body carries personal
+ * data says so in `disclosure`, and the host records it per person before
+ * and after the send.
+ *
+ * Needs no permission: the declaration is what the board consented to.
+ * Added after this contract version shipped, like `actions`: a plugin built
+ * against a newer host than the one it is installed on must feature-detect
+ * before using it.
+ */
+export interface PluginRecipients {
+  fetch(
+    id: string,
+    /** Starts with `/`, and may carry a query: `/v1/messages?beta=true`. */
+    path: string,
+    init?: PluginRecipientRequest,
+  ): Promise<PluginRecipientResponse>;
+}
+
+/**
+ * One device token, as the plugin and the board see it. Never the token.
+ */
+export interface DeviceTokenSummary {
+  readonly id: string;
+  /** The id of the device route it was issued for. */
+  readonly route: string;
+  /** The plugin's own name for the device, such as its screen id. */
+  readonly subject: string;
+  /** The board's name for it, such as "Entrance B, ground floor". */
+  readonly label: string;
+  readonly issuedAt: string;
+  /** Updated at most once a minute while the device calls. */
+  readonly lastUsedAt: string | null;
+  readonly revokedAt: string | null;
+}
+
+/**
+ * Device tokens for the plugin's own device routes (ADR 0031).
+ *
+ * A device token reaches one device route of this plugin, names a device and
+ * never a person, and is cut at once when revoked. The plugin issues one only
+ * on a board member's request, and the board can revoke any of them from the
+ * core's own devices screen, whatever the plugin's screen says.
+ */
+export interface PluginDevices {
+  /**
+   * Issues a device token, and returns it once. It is stored as a digest and
+   * cannot be read again.
+   *
+   * `request` is the one the plugin's own route received. It has to come from
+   * the web interface, not a connected app's token, from a person who holds
+   * `site:manage` at that moment; anything else is refused. `route` is the id
+   * of one of the plugin's declared device routes. `subject` is the plugin's
+   * handle on the device, 1 to 64 letters, digits, `.`, `_`, `:` or `-`, and
+   * `label` the board's name for it, at most 80 characters. A plugin holds at
+   * most 200 live tokens.
+   */
+  issue(
+    request: ActionRequest,
+    options: { route: string; subject: string; label: string },
+  ): Promise<{ token: string; device: DeviceTokenSummary }>;
+
+  /** The plugin's own tokens, newest first. Revoked ones included. */
+  list(filter?: {
+    route?: string;
+    subject?: string;
+  }): Promise<readonly DeviceTokenSummary[]>;
+
+  /**
+   * Revokes one of the plugin's own tokens, at once. True when it was live.
+   *
+   * Pass the request when a person asked for it, so the audit log names them;
+   * without one the revocation is recorded as the plugin's.
+   */
+  revoke(tokenId: string, request?: ActionRequest): Promise<boolean>;
+
+  /**
+   * Which token a request on one of the plugin's device routes came with.
+   * Throws for any other request.
+   */
+  current(request: object): DeviceTokenSummary;
+}
+
 /**
  * The host object a plugin's module factory receives.
  *
@@ -219,6 +885,104 @@ export interface PluginHost {
    * finding with the message deliberately withheld.
    */
   actions: PluginActions;
+  /**
+   * The association's fee notices and charges, delivery receipts against them,
+   * and the events that say one was issued.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin must
+   * feature-detect it (`host.finances === undefined`) before using it.
+   */
+  finances: PluginFinances;
+  /**
+   * The website blocks this plugin declared, and their render functions.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  blocks: PluginBlocks;
+  /**
+   * The instance's audit log, for what this plugin did.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  audit: PluginAudit;
+  /**
+   * The extension points this plugin offers or extends (ADR 0030): a host
+   * plugin defines its points and calls the addons serving there, and an
+   * addon contributes its handler.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  extensions: PluginExtensions;
+  /**
+   * The association's published content: its news, its calendar, when its
+   * bookable resources are taken, its pictures and its addresses (ADR 0032).
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using them.
+   */
+  news: PluginNews;
+  calendar: PluginCalendar;
+  bookings: PluginBookings;
+  media: PluginMedia;
+  addresses: PluginAddresses;
+  /**
+   * The way out to the recipients this plugin declared.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  recipients: PluginRecipients;
+  /**
+   * The plugin's own records: configuration it keeps under a collection and a
+   * key, and never anything about a person (ADR 0033).
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  records: PluginRecords;
+  /**
+   * Device tokens for the plugin's declared device routes.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  devices: PluginDevices;
+  /**
+   * Installing themes, and listing the ones this plugin installed.
+   *
+   * Added after this contract version shipped. An older host refuses a
+   * manifest asking for themes:install before it loads the plugin, so a plugin
+   * that declares the permission never meets a host without this member.
+   */
+  themes: PluginThemes;
+  /**
+   * Handing a member list to the board for review (ADR 0043).
+   *
+   * Added after this contract version shipped. An older host refuses a
+   * manifest asking for addressBook:proposeImport before it loads the plugin,
+   * so a plugin that declares the permission never meets a host without this
+   * member; checking for it is a defensive guard only.
+   */
+  imports: PluginImports;
+  /**
+   * The plugin's licence, judged by the host (ADR 0042).
+   *
+   * Present only on a plugin whose manifest declares a `licence`, and added
+   * after this contract version shipped, so a plugin feature-detects it as it
+   * does `actions`. A paid plugin on a host without it has no way to tell a
+   * licensed instance from an unlicensed one, and should stay dormant.
+   */
+  entitlements?: PluginEntitlements;
 }
 
 /**