@openbrf/plugin-sdk 1.0.0 → 1.2.0

package/dist/extensions.d.ts

@@ -0,0 +1,183 @@
+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 declare const EXTENSION_POINT_ID_PATTERN: RegExp;
+/** How many points a plugin may declare, and how many an addon may extend. */
+export declare const MAX_EXTENSION_POINTS = 8;
+/** How long a contribution may take when its point names no time of its own. */
+export declare const EXTENSION_TIMEOUT_MS = 5000;
+/** The longest a point may give a contribution. */
+export declare const EXTENSION_MAX_TIMEOUT_MS = 15000;
+/**
+ * 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 declare const EXTENSION_MAX_OUTPUT_LENGTH = 1048576;
+/**
+ * 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 declare const EXTENSION_RESULT_REASONS: readonly [
+/**
+ * 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"];
+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;
+}
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"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"}

package/dist/extensions.js

@@ -0,0 +1,67 @@
+/**
+ * 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",
+];
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,+BAA+B,CAAC;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C,mDAAmD;AACnD,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,SAAS,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;;;OAGG;IACH,aAAa;IACb;;;;;;;OAOG;IACH,WAAW;IACX,yEAAyE;IACzE,QAAQ;IACR;;;OAGG;IACH,gBAAgB;CACR,CAAC"}

package/dist/finances.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 declare const PLUGIN_FINANCE_EVENTS: {
+    readonly "feeNotification.issued": 1;
+    readonly "memberCharge.recorded": 1;
+    readonly "memberCharge.corrected": 1;
+    readonly "memberCharge.removed": 1;
+};
+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 declare class PluginDeliveryRefusedError extends Error {
+    readonly reason: "target-not-found" | "channel-invalid" | "reference-invalid" | "reference-holds-personal-identity-number" | "delivered-at-invalid" | "delivered-in-the-future";
+    constructor(reason: "target-not-found" | "channel-invalid" | "reference-invalid" | "reference-holds-personal-identity-number" | "delivered-at-invalid" | "delivered-in-the-future", message: string);
+}
+export {};
+//# sourceMappingURL=finances.d.ts.map

package/dist/finances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finances.d.ts","sourceRoot":"","sources":["../src/finances.ts"],"names":[],"mappings":"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"}

package/dist/finances.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/**
+ * 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,
+};
+/**
+ * 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 {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "PluginDeliveryRefusedError";
+    }
+}
+//# sourceMappingURL=finances.js.map

package/dist/finances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finances.js","sourceRoot":"","sources":["../src/finances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoKH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,wBAAwB,EAAE,CAAC;IAC3B,uBAAuB,EAAE,CAAC;IAC1B,wBAAwB,EAAE,CAAC;IAC3B,sBAAsB,EAAE,CAAC;CACjB,CAAC;AA6FX;;;;;GAKG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAExC,MAAM;IADjB,YACW,MAMoB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;sBATN,MAAM;QAUf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}