@openbrf/plugin-sdk 1.0.0 → 1.4.0

package/src/entitlements.ts

@@ -0,0 +1,150 @@
+/**
+ * What a paid plugin reads about its licence (ADR 0042).
+ *
+ * The host holds the licences the board entered and verifies them offline,
+ * against the keys the plugin's manifest declares and the instance's own id
+ * and key, on the association's calendar day. A plugin gets the finding and
+ * never the file, and decides for itself what it withholds without an active
+ * entitlement: the host loads and serves it either way.
+ */
+
+/** The version of the licence file format this contract reads. */
+export const LICENCE_FORMAT = "openbrf-licence/1";
+
+/** The version of the presentation format `present()` writes. */
+export const LICENCE_PRESENTATION_FORMAT = "openbrf-licence-presentation/1";
+
+/** The largest licence file the host accepts, in bytes. */
+export const LICENCE_FILE_MAX_BYTES = 16_384;
+
+/** The largest presentation a service has to read, in bytes. */
+export const LICENCE_PRESENTATION_MAX_BYTES = 24_576;
+
+/**
+ * The finding for the entitlement the manifest names, judged today.
+ *
+ * Dates are `YYYY-MM-DD` on the association's calendar day, and inclusive: a
+ * licence valid until a day is active through the whole of it.
+ *
+ * - `active`: a licence one of the plugin's keys verified names the
+ *   entitlement, is bound to this instance, and covers today and this release.
+ * - `absent`: no licence the plugin's keys verified names the entitlement.
+ * - `expired`: today is after its `validUntil`.
+ * - `version-not-covered`: this release was published after its
+ *   `updatesUntil`. An earlier release stays covered.
+ * - `wrong-instance`: it was issued to another instance, by id or by key.
+ * - `tampered`: it verified when it was entered and no longer does.
+ * - `not-yet-valid`: it was issued after today, which is a wrong clock on
+ *   one side or the other.
+ *
+ * Without an active licence the finding is that of the licence entered most
+ * recently, so a board that has just entered the wrong file is told about
+ * that file.
+ */
+export type EntitlementState =
+  | {
+      status: "active";
+      licenceId: string;
+      validUntil: string | null;
+      updatesUntil: string | null;
+    }
+  | { status: "absent" }
+  | { status: "expired"; licenceId: string; validUntil: string }
+  | {
+      status: "version-not-covered";
+      licenceId: string;
+      updatesUntil: string;
+      released: string;
+    }
+  | { status: "wrong-instance"; licenceId: string }
+  | { status: "tampered" }
+  | { status: "not-yet-valid"; licenceId: string; issuedOn: string };
+
+export type EntitlementStatus = EntitlementState["status"];
+
+export const ENTITLEMENT_STATUSES = [
+  "active",
+  "absent",
+  "expired",
+  "version-not-covered",
+  "wrong-instance",
+  "tampered",
+  "not-yet-valid",
+] as const satisfies readonly EntitlementStatus[];
+
+/**
+ * A licensed plugin's view of its entitlement.
+ *
+ * Read on every call rather than once at boot, so a licence the board enters,
+ * one that ends, and the next one taking over all reach a running plugin
+ * without a restart.
+ */
+export interface PluginEntitlements {
+  /** The entitlement the manifest names, judged today. */
+  get(): Promise<EntitlementState>;
+  /**
+   * The active licence with a fresh signature by the instance key, for one of
+   * the audiences the manifest declares, as the text to send that service.
+   * Null without an active licence.
+   *
+   * Signed without a network call; sending it is the plugin's. A presentation
+   * is good at its audience for five minutes and once, so make one per
+   * request rather than keeping one.
+   *
+   * Throws a RangeError for an audience the manifest does not declare, since
+   * that is a defect in the plugin rather than a state of the licence.
+   */
+  present(audience: string): Promise<string | null>;
+}
+
+export interface TestEntitlementsOptions {
+  /** What `get()` answers. */
+  state: EntitlementState;
+  /** The manifest's `licence.audiences`. None by default. */
+  audiences?: readonly string[];
+  /** What `present()` answers while the state is active. */
+  presentation?: (audience: string) => string;
+}
+
+/**
+ * A stand-in for `host.entitlements` in a plugin's own tests.
+ *
+ * It answers with the state it was given and keeps the host's two rules about
+ * presenting: an undeclared audience is refused, and nothing is presented
+ * without an active licence. A plugin that wants to test the service end of a
+ * presentation signs licences with a throwaway key generated in the test;
+ * nothing here needs one.
+ */
+export function createTestEntitlements(
+  options: TestEntitlementsOptions,
+): PluginEntitlements & { state: EntitlementState } {
+  const audiences = new Set(options.audiences ?? []);
+  const double = {
+    state: options.state,
+    get: (): Promise<EntitlementState> => Promise.resolve(double.state),
+    present: (audience: string): Promise<string | null> => {
+      if (!audiences.has(audience)) {
+        return Promise.reject(undeclaredAudienceError());
+      }
+      if (double.state.status !== "active") {
+        return Promise.resolve(null);
+      }
+      return Promise.resolve(
+        options.presentation?.(audience) ?? `test-presentation:${audience}`,
+      );
+    },
+  };
+  return double;
+}
+
+/**
+ * The refusal of an audience the manifest does not declare, worded once for
+ * the host and its test double. The audience is left out: it is whatever the
+ * plugin passed.
+ */
+export function undeclaredAudienceError(): RangeError {
+  return new RangeError(
+    "present() was asked for an audience the plugin's manifest does not " +
+      "declare under licence.audiences.",
+  );
+}

package/src/extensions.ts

@@ -0,0 +1,212 @@
+import type { PluginAbortSignal } from "./abort-signal.ts";
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/**
+ * Plugins that extend plugins (ADR 0030).
+ *
+ * An extension point (utökningspunkt) is a named slot a plugin declares in its
+ * manifest and offers to other plugins; that plugin is the point's host plugin.
+ * An addon (utökning) is a plugin that extends another at one of its points,
+ * and what it registers there is a contribution (bidrag): a title and a
+ * handler. Each is a plugin in every other respect, installed, consented to and
+ * switched on by itself, and neither receives the other's permissions.
+ *
+ * The host carries every call between them. It validates the input against the
+ * host plugin's schema before the call and the output after it, copies both as
+ * JSON values so that nothing but data crosses, and answers for what the addon
+ * did in the result rather than by throwing: a screen that loses one source
+ * should go on with the others.
+ *
+ * Swedish domain terms follow GLOSSARY.md.
+ */
+
+/**
+ * What an extension point id may look like, in the manifest and at the host.
+ *
+ * Lowercase letters, digits and single hyphens, two to thirty-two characters:
+ * the shape a plugin id has, shorter, because it is shown beside one.
+ */
+export const EXTENSION_POINT_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/** How many points a plugin may declare, and how many an addon may extend. */
+export const MAX_EXTENSION_POINTS = 8;
+
+/** How long a contribution may take when its point names no time of its own. */
+export const EXTENSION_TIMEOUT_MS = 5_000;
+
+/** The longest a point may give a contribution. */
+export const EXTENSION_MAX_TIMEOUT_MS = 15_000;
+
+/**
+ * The longest answer a contribution may give, in characters of its JSON text.
+ * A longer one is `output-invalid`, refused before it is parsed or validated.
+ */
+export const EXTENSION_MAX_OUTPUT_LENGTH = 1_048_576;
+
+/**
+ * Why `invoke` answered without a value.
+ *
+ * Everything an addon can do wrong, and the one state the host plugin cannot
+ * see from its own side, so a host plugin can tell a broken addon from one that
+ * is switched off without either being thrown at it.
+ */
+export const EXTENSION_RESULT_REASONS = [
+  /**
+   * The addon is not installed, not loaded, switched off, or has registered no
+   * contribution at this point.
+   */
+  "not-serving",
+  /**
+   * The handler did not answer in time. Its signal was aborted.
+   *
+   * The time bounds only how long the host waits for the handler's promise.
+   * Work the handler does synchronously, and a `toJSON` or getter in its
+   * answer, runs on the host's one thread with no limit, as any plugin code
+   * does: a handler that loops stalls the instance.
+   */
+  "timed-out",
+  /** The handler threw. What it threw is in the server log, never here. */
+  "failed",
+  /**
+   * The answer does not meet the point's output schema, has no JSON form, or
+   * is longer than EXTENSION_MAX_OUTPUT_LENGTH as JSON.
+   */
+  "output-invalid",
+] as const;
+
+export type ExtensionResultReason = (typeof EXTENSION_RESULT_REASONS)[number];
+
+/** What the host plugin hands `define` for one point its manifest declares. */
+export interface ExtensionPointDefinition<Input = unknown, Output = unknown> {
+  /**
+   * What the host plugin sends a contribution. A strict object at every depth,
+   * built with the host's zod, with no record, catchall, `unknown` or `any`
+   * anywhere inside it.
+   */
+  readonly input: StandardSchemaV1<unknown, Input>;
+  /**
+   * What a contribution must answer. A strict object at every depth, built with
+   * the host's zod, with no record, catchall, `unknown` or `any` anywhere inside
+   * it: a key the schema does not name is a key an addon could hand over
+   * something nobody consented to in.
+   */
+  readonly output: StandardSchemaV1<unknown, Output>;
+  /**
+   * How long a contribution may take, in milliseconds.
+   * EXTENSION_TIMEOUT_MS by default, at most EXTENSION_MAX_TIMEOUT_MS.
+   */
+  readonly timeoutMs?: number;
+}
+
+/** What the host tells a contribution about the call it is answering. */
+export interface ExtensionContext {
+  /** The plugin whose point is being answered. */
+  readonly hostPlugin: string;
+  readonly point: string;
+  /** The point's major version, which is the one the addon named. */
+  readonly version: number;
+  /** For the logs, so a call can be followed from one plugin to the other. */
+  readonly requestId: string;
+  readonly now: Date;
+  /** Aborted when the call times out or the host plugin gives up on it. */
+  readonly signal: PluginAbortSignal;
+}
+
+/** What an addon hands `contribute` for one point its manifest extends. */
+export interface ExtensionContributionDefinition<
+  Input = unknown,
+  Output = unknown,
+> {
+  /**
+   * A bare key in the addon's own namespace, as an action's is. The host
+   * qualifies it as `plugin-<addon>:<key>`.
+   */
+  readonly titleKey: string;
+  readonly descriptionKey?: string;
+  /**
+   * Answers one call.
+   *
+   * Runs with the addon's own host object, under the permissions the board
+   * consented to for the addon, and with no person behind it: an extension
+   * point is a call from one plugin to another, not somebody's request. It
+   * must accept input fields it does not know, because a host plugin may add
+   * an optional field to a point without raising its version.
+   */
+  readonly handler: (
+    input: Input,
+    context: ExtensionContext,
+  ) => Promise<Output>;
+}
+
+/** One contribution that is serving at a point, as its host plugin sees it. */
+export interface ExtensionContributionSummary {
+  /** The addon's plugin id, which `invoke` takes. */
+  readonly addon: string;
+  /** Qualified into the addon's namespace, `plugin-<addon>:<key>`. */
+  readonly titleKey: string;
+  readonly descriptionKey: string | null;
+}
+
+/** What `invoke` answers: a value, or why there is none. */
+export type ExtensionResult<Output> =
+  | { readonly ok: true; readonly value: Output }
+  | { readonly ok: false; readonly reason: ExtensionResultReason };
+
+/** The plugin and the point an addon contributes to. */
+export interface ExtensionTarget {
+  readonly plugin: string;
+  readonly point: string;
+}
+
+/**
+ * Extension points, as a plugin sees them.
+ *
+ * A host plugin uses `define`, `list` and `invoke`; an addon uses
+ * `contribute`. `define` and `contribute` are declarations, callable from the
+ * module factory onwards and buffered until the application exists, as
+ * `host.actions.register` is. A definition or contribution the host cannot
+ * accept - a point or target the manifest does not declare, a schema that is
+ * not a strict object built with the host's zod, a second one for the same
+ * point - is found when the buffer is flushed and stops the plugin with
+ * `extension-refused`, rather than throwing here.
+ *
+ * `list` and `invoke` keep the ordinary gate and work from `onModuleInit`
+ * onwards.
+ */
+export interface PluginExtensions {
+  /** Host plugin: the schemas of a point its manifest declares. */
+  define<Input, Output>(
+    point: string,
+    definition: ExtensionPointDefinition<Input, Output>,
+  ): void;
+
+  /**
+   * Host plugin: the contributions to one of its points that are serving now,
+   * in addon id order.
+   *
+   * Throws for a point the manifest does not declare or the plugin has not
+   * defined.
+   */
+  list(point: string): Promise<readonly ExtensionContributionSummary[]>;
+
+  /**
+   * Host plugin: calls one addon's contribution.
+   *
+   * Throws for a mistake of the host plugin's own: a point its manifest does
+   * not declare or it has not defined, or an input its own schema refuses. An
+   * aborted `signal` rejects with the signal's reason. Everything the addon
+   * does is answered in the result.
+   */
+  invoke<Output>(
+    point: string,
+    addon: string,
+    input: unknown,
+    options?: { signal?: PluginAbortSignal },
+  ): Promise<ExtensionResult<Output>>;
+
+  /** Addon: the handler for a point its manifest extends. Once per point. */
+  contribute<Input, Output>(
+    target: ExtensionTarget,
+    contribution: ExtensionContributionDefinition<Input, Output>,
+  ): void;
+}

package/src/finances.ts

@@ -0,0 +1,317 @@
+/**
+ * The association's finances, as a plugin may read them, record a delivery
+ * against them and hear about them.
+ *
+ * What is here is the free half of the boundary ROADMAP.md publishes: the
+ * notices and charges core already records, read on the same masking rules as
+ * the files the board hands over, a receipt that says one of them was
+ * delivered, and an event that says one was issued. What carries them out of
+ * Open BRF - an accounting system, a bankgiro file, a reminder - is the
+ * plugin's own work.
+ *
+ * Three rules hold on every member here regardless of permission, and they are
+ * the address book's (`PluginAddressBook`) read for money:
+ *
+ *   A person with protected personal data is never named. A notice for their
+ *   household carries its apartment and its amount and withholds every name;
+ *   a charge on them carries its date and its amount and withholds who, where
+ *   and why. The row says so with a `withheld` branch rather than an empty
+ *   string, so a reader cannot take a withheld value for an absent one.
+ *
+ *   A personal identity number is never returned. No row carries one.
+ *
+ *   There is no payment state, because core records none. Nothing here says
+ *   whether a notice was paid, what is outstanding or what a balance is, and a
+ *   delivery receipt is not that either: the accounting system settles the
+ *   debt, and a second answer to whether something was paid is worse than none.
+ */
+
+/**
+ * One delivery of a notice or a charge, as the plugin that made it recorded it.
+ *
+ * A receipt says that something left the association by a route, at a time,
+ * under a reference the receiving system knows it by. It never says that the
+ * money arrived, and it is not a status: a notice may carry several receipts,
+ * from several plugins, and none of them changes the notice.
+ */
+export interface PluginDeliveryReceipt {
+  id: string;
+  /** The plugin that recorded it. */
+  pluginId: string;
+  /**
+   * The route, in the recording plugin's own word for it: `fortnox`,
+   * `autogiro`, `email`. Lowercase letters, digits and hyphens, at most 32.
+   */
+  channel: string;
+  /**
+   * What the receiving system calls it, or the statement that it is withheld.
+   *
+   * Withheld on every receipt another plugin recorded: a plugin reads its own
+   * references only. And withheld with the row it is on: on a notice whose
+   * holders are withheld and a charge whose party or reason is, by the
+   * register as it stands at the read rather than when the receipt was
+   * recorded. A reference is the recording plugin's free text, and one written
+   * while a household could be named can name it as well as the names can.
+   * The receipt itself stays, so a plugin can still tell that the row was
+   * delivered.
+   */
+  reference: PluginDeliveryReference;
+  /** When it was delivered, as the plugin stated it. An ISO 8601 instant. */
+  deliveredAt: string;
+  /** When the receipt was recorded. An ISO 8601 instant. */
+  recordedAt: string;
+}
+
+/**
+ * What the receiving system calls a delivery - a voucher number, a file name, a
+ * message id, at most 128 characters - or the statement that it is withheld.
+ */
+export type PluginDeliveryReference =
+  { state: "visible"; text: string } | { state: "withheld" };
+
+/** What a plugin states when it records a delivery. */
+export interface PluginDeliveryReceiptInput {
+  target:
+    { kind: "feeNotice"; id: string } | { kind: "memberCharge"; id: string };
+  channel: string;
+  reference: string;
+  /** When it was delivered. Now, when left out; never a time still to come. */
+  deliveredAt?: Date;
+}
+
+/** Who a notice names, or the statement that the names are withheld. */
+export type PluginFeeNoticeHolders =
+  | {
+      state: "visible";
+      /** The tenant-owners' names, in the register's own order. */
+      names: string[];
+    }
+  | { state: "withheld" };
+
+/** One apartment's notice in one run (avi). */
+export interface PluginFeeNotice {
+  id: string;
+  apartment: {
+    id: string;
+    /** "<street> <number> <apartment number>". Never withheld. */
+    label: string;
+    number: string;
+  };
+  /**
+   * The tenant-owners holding the apartment when the period closed. Withheld
+   * where anybody in the household carries protected personal data or has had
+   * processing restricted (GDPR art. 18).
+   */
+  holders: PluginFeeNoticeHolders;
+  /** Kronor with two decimals: "3450.50". What was billed, never a balance. */
+  amount: string;
+  paymentReference: string;
+  deliveries: PluginDeliveryReceipt[];
+}
+
+/** A fee notification run (avisering) without its notices. */
+export interface PluginFeeNotificationSummary {
+  id: string;
+  /** The period billed, inclusive at both ends. "YYYY-MM-DD". */
+  from: string;
+  to: string;
+  /** The due date the board stated. Nothing in core computes from it. */
+  dueOn: string;
+  /** When the run was issued. An ISO 8601 instant. */
+  issuedAt: string;
+  /** How many notices the run carries. */
+  notices: number;
+  /** The sum of what was billed, as kronor with two decimals. */
+  total: string;
+}
+
+/** A fee notification run with its notices. */
+export interface PluginFeeNotification extends Omit<
+  PluginFeeNotificationSummary,
+  "notices"
+> {
+  notices: PluginFeeNotice[];
+}
+
+/** Who a charge is on, or the statement that it is withheld. */
+export type PluginMemberChargeParty =
+  | {
+      kind: "person";
+      state: "visible";
+      personId: string;
+      name: string;
+      /**
+       * Where they held a residency on the day of the charge, as the debiting
+       * list prints it, or null where they held none.
+       */
+      apartment: string | null;
+    }
+  | {
+      /**
+       * A person the plugin is not told about: one carrying protected personal
+       * data, one whose processing is restricted (GDPR art. 18), or one the
+       * register no longer holds.
+       */
+      kind: "person";
+      state: "withheld";
+    }
+  | {
+      kind: "apartment";
+      /** Null once the apartment has been corrected out of the register. */
+      apartmentId: string | null;
+      apartment: string | null;
+    };
+
+/** The board's own words for a charge, or the statement they are withheld. */
+export type PluginMemberChargeReason =
+  { state: "visible"; text: string } | { state: "withheld" };
+
+/** One charge to a member or an apartment (debitering). */
+export interface PluginMemberCharge {
+  id: string;
+  /** "YYYY-MM-DD" on the association's own calendar. */
+  chargedOn: string;
+  chargedTo: PluginMemberChargeParty;
+  /** Kronor with two decimals. What was charged, never a balance. */
+  amount: string;
+  vatTreatment: "EXEMPT" | "RATE";
+  /** Whole percent, and null exactly when the treatment is EXEMPT. */
+  vatRatePercent: number | null;
+  /**
+   * Withheld with the party, and on a charge to a household where somebody
+   * protected or restricted lived on the day of the charge: what the board
+   * wrote about a household can say who lives in it as well as a name can.
+   */
+  reason: PluginMemberChargeReason;
+  /** "YYYY-MM-DD" the basis went to the economic manager, or null. */
+  handedToManagerOn: string | null;
+  deliveries: PluginDeliveryReceipt[];
+}
+
+/**
+ * The events the host delivers, by type, with the version it delivers.
+ *
+ * A version moves when a field is removed or changes meaning; a field added
+ * keeps it. The host lists what it delivers in
+ * `host.finances.events.supported`, so a plugin built against a newer SDK can
+ * tell an event this instance will never send from one that has not happened.
+ */
+export const PLUGIN_FINANCE_EVENTS = {
+  "feeNotification.issued": 1,
+  "memberCharge.recorded": 1,
+  "memberCharge.corrected": 1,
+  "memberCharge.removed": 1,
+} as const;
+
+export type PluginFinanceEventType = keyof typeof PLUGIN_FINANCE_EVENTS;
+
+interface PluginFinanceEventBase {
+  /** Unique per event, and the same on every redelivery of it. */
+  eventId: string;
+  /** When the act was committed. An ISO 8601 instant. */
+  occurredAt: string;
+}
+
+/**
+ * Something happened to the association's finances.
+ *
+ * Identifiers only. An event carries nothing that names a person or states a
+ * figure, so it needs no masking of its own: the plugin reads the row through
+ * `host.finances`, on the same rules as every other read.
+ */
+export type PluginFinanceEvent =
+  | (PluginFinanceEventBase & {
+      type: "feeNotification.issued";
+      version: 1;
+      notificationId: string;
+    })
+  | (PluginFinanceEventBase & {
+      type: "memberCharge.recorded" | "memberCharge.corrected";
+      version: 1;
+      chargeId: string;
+    })
+  | (PluginFinanceEventBase & {
+      type: "memberCharge.removed";
+      version: 1;
+      /** The charge is gone; only its id is left to say which one it was. */
+      chargeId: string;
+    });
+
+export interface PluginFinanceEvents {
+  /** What this host delivers, by type and version. */
+  readonly supported: Readonly<Record<string, number>>;
+  /**
+   * Receives every finance event from now on.
+   *
+   * Call it once, from `onModuleInit`. Delivery is at least once, from a queue
+   * the host keeps for this plugin, and the event is enqueued in the same
+   * transaction as the act it reports - so an act that rolled back never
+   * produces one and one that committed always does. A handler that throws is
+   * retried; one that keeps throwing has the event dropped once the retries
+   * are spent. Order is not guaranteed. Ignore a `type` you do not know.
+   *
+   * Events reach a plugin that is serving and subscribed when the act
+   * commits. A plugin switched off, or not yet subscribed, misses them, and
+   * reads what it missed with `notifications()` and `charges()` when it starts.
+   */
+  subscribe(
+    handler: (event: PluginFinanceEvent) => Promise<void> | void,
+  ): Promise<void>;
+}
+
+/**
+ * The association's finances, scoped to what the plugin declared.
+ *
+ * The reads and the events require finances:read; recording a delivery
+ * requires finances:recordDelivery.
+ */
+export interface PluginFinances {
+  /** The fee notification runs, newest period first. */
+  notifications(): Promise<PluginFeeNotificationSummary[]>;
+  /** One run with its notices, or null where there is no such run. */
+  notification(id: string): Promise<PluginFeeNotification | null>;
+  /**
+   * The charges dated within a period, both ends inclusive, as "YYYY-MM-DD".
+   * In date order, and in the order they were entered within a day.
+   */
+  charges(period: { from: string; to: string }): Promise<PluginMemberCharge[]>;
+  /** One charge, or null where there is no such charge. */
+  charge(id: string): Promise<PluginMemberCharge | null>;
+  /**
+   * Records that a notice or a charge was delivered, and returns the receipt.
+   *
+   * Idempotent: the same target, channel and reference from the same plugin
+   * returns the receipt already recorded rather than a second one, so a job
+   * retried after a crash cannot record one delivery twice. A reference that
+   * holds a Swedish personal identity number is refused.
+   *
+   * The receipt returned carries the reference visible: it is what the plugin
+   * has just stated. A later read withholds it with the row it is on.
+   */
+  recordDelivery(
+    input: PluginDeliveryReceiptInput,
+  ): Promise<PluginDeliveryReceipt>;
+  events: PluginFinanceEvents;
+}
+
+/**
+ * A delivery the host would not record, and why.
+ *
+ * `reason` is stable and meant for the plugin's own code; the message is
+ * English for the server log.
+ */
+export class PluginDeliveryRefusedError extends Error {
+  constructor(
+    readonly reason:
+      | "target-not-found"
+      | "channel-invalid"
+      | "reference-invalid"
+      | "reference-holds-personal-identity-number"
+      | "delivered-at-invalid"
+      | "delivered-in-the-future",
+    message: string,
+  ) {
+    super(message);
+    this.name = "PluginDeliveryRefusedError";
+  }
+}