@openbrf/plugin-sdk 0.0.0-stage → 1.2.0

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"}

package/dist/findings.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Why a plugin on the data volume is not running.
+ *
+ * A finding travels as one of these codes plus the values its sentence needs,
+ * never as a sentence composed by the host. The interface is Swedish by
+ * default and this package is English, so what a board reads has to be a
+ * translation of the code: a sentence written where the finding is produced
+ * reaches the board panel in the language the server happens to be written in.
+ *
+ * Listed as values rather than as a bare union so a caller can walk them and
+ * prove it has a sentence for each. Part of the contract rather than an
+ * implementation detail - docs/plugin-contract.md lists the same set, and a
+ * plugin author reading why their package was skipped is reading one of these.
+ */
+export declare const PLUGIN_FINDING_REASONS: readonly [
+/** The `openbrf` field failed validation. */
+"manifest-invalid", 
+/** Built against a contract version this instance does not implement. */
+"api-version-unsupported", 
+/** A declared entry file is not in the package. */
+"entry-missing", 
+/** The server bundle does not export `createPlugin`. */
+"entry-invalid", 
+/** `createPlugin` returned no NestJS dynamic module. */
+"module-invalid", 
+/** Its module declares behaviour a plugin may not register. */
+"module-refused", 
+/** Its module could not be built into the application. */
+"module-failed", 
+/** The package carries its own copy of a host package it must share. */
+"module-identity", 
+/** It asks for more than was consented to. */
+"permissions-widened", 
+/** It handles a personal-data category that was not consented to. */
+"personal-data-widened", 
+/** On the volume with no record of consent. */
+"not-consented", 
+/** Switched off in the admin interface. */
+"disabled", 
+/** It threw while being loaded. */
+"load-failed", 
+/** Recorded as installed but not present. */
+"not-on-volume", 
+/** The installed version declares an action the board did not consent to. */
+"actions-widened", 
+/** An action the manifest declares could not be registered. */
+"action-refused", 
+/**
+ * The installed version says otherwise than the board consented to about
+ * whether it is an AI package, in either direction.
+ */
+"ai-changed", 
+/**
+ * The installed version reads another entitlement than the board consented
+ * to, may present the licence to a service the board was not told of, or
+ * declares a key of its issuer's the board has not consented to.
+ */
+"licence-widened", 
+/**
+ * The installed version names another issuer of its licence than the board
+ * consented to, or no longer declares a key the board consented to.
+ */
+"licence-issuer-changed", 
+/** It registered a website block its manifest does not declare. */
+"block-refused", 
+/** One of its providers reaches for a core service a plugin may not hold. */
+"forbidden-injection", 
+/**
+ * It declares the OAuth protected resource, and another installed plugin
+ * already does. The one installed first keeps it: the resource URL is the
+ * audience every issued token carries, so moving it would strand them all.
+ */
+"oauth-resource-conflict", 
+/**
+ * A plugin it extends is not installed, not loaded, or switched off. The
+ * detail names it. An addon does not serve while its host plugin does not.
+ */
+"extension-host-missing", 
+/** A plugin it extends declares no such extension point. */
+"extension-point-unknown", 
+/**
+ * A point it extends is at another major version than the one it was
+ * written for.
+ */
+"extension-version-unsupported", 
+/** It hands over a category of personal data the point does not accept. */
+"extension-personal-data-refused", 
+/**
+ * Of it and a plugin it extends, one puts blocks on the website and the
+ * other holds a permission that reads the register. The detail names
+ * those permissions.
+ */
+"extension-permission-refused", 
+/**
+ * It puts blocks on the website, and a plugin it extends handles personal
+ * data. The detail names those categories.
+ */
+"extension-host-personal-data-refused", 
+/**
+ * The plugins joined to it by extensions, through one host plugin or
+ * several, hold one that puts blocks on the website and one that reads the
+ * address book. The detail names both.
+ */
+"extension-group-refused", 
+/**
+ * It declares an extension point, or extends one, in a way the board has not
+ * consented to.
+ */
+"extensions-widened", 
+/** A definition or contribution it registered could not be accepted. */
+"extension-refused", 
+/**
+ * The installed version declares a recipient the board did not consent to:
+ * a new one, one at another origin, or one receiving more personal data.
+ */
+"recipients-widened", 
+/**
+ * The installed version declares a device route the board has not consented
+ * to, or moves one (ADR 0031).
+ */
+"device-routes-widened"];
+export type PluginFindingReason = (typeof PLUGIN_FINDING_REASONS)[number];
+/**
+ * The values a finding's sentence is completed with.
+ *
+ * Identifiers, paths, numbers and what a thrown error said - never a sentence,
+ * and never personal data. A list stays a list rather than being joined here,
+ * because its members can have sentences of their own: a board told that a
+ * package handles a category it never agreed to has to read that category in
+ * its own language, not as `residency`.
+ */
+export type PluginFindingDetail = Readonly<Record<string, string | number | readonly string[]>>;
+/**
+ * The manifest rules whose refusal a board reads in its own language.
+ *
+ * A manifest that fails validation is reported as `manifest-invalid`, and
+ * what Zod says about a field is English for the plugin's author. The rules
+ * below are not about one field: they hold two declarations against each
+ * other, and a board reading why a package was skipped needs to be told which
+ * in a sentence of its own. So the refusal carries the code with the English
+ * line, and the interface translates the code. Any other problem stays the
+ * English line, which is what an author fixes the package from.
+ */
+export declare const PLUGIN_MANIFEST_RULES: readonly [
+/** A device route overlaps the OAuth protected resource. */
+"device-route-overlaps-oauth-resource", 
+/** A plugin with a device route also reads the register or the finances. */
+"device-route-reads-register", 
+/** A plugin with a website block also reads the register or the finances. */
+"blocks-read-register", 
+/** A plugin with a device route also proposes imports. */
+"device-route-proposes-import", 
+/** A plugin with a website block also proposes imports. */
+"blocks-propose-import"];
+export type PluginManifestRule = (typeof PLUGIN_MANIFEST_RULES)[number];
+//# sourceMappingURL=findings.d.ts.map

package/dist/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;AACjC,6CAA6C;AAC7C,kBAAkB;AAClB,yEAAyE;AACzE,yBAAyB;AACzB,mDAAmD;AACnD,eAAe;AACf,wDAAwD;AACxD,eAAe;AACf,wDAAwD;AACxD,gBAAgB;AAChB,+DAA+D;AAC/D,gBAAgB;AAChB,0DAA0D;AAC1D,eAAe;AACf,wEAAwE;AACxE,iBAAiB;AACjB,8CAA8C;AAC9C,qBAAqB;AACrB,qEAAqE;AACrE,uBAAuB;AACvB,+CAA+C;AAC/C,eAAe;AACf,2CAA2C;AAC3C,UAAU;AACV,mCAAmC;AACnC,aAAa;AACb,6CAA6C;AAC7C,eAAe;AACf,6EAA6E;AAC7E,iBAAiB;AACjB,+DAA+D;AAC/D,gBAAgB;AAChB;;;GAGG;AACH,YAAY;AACZ;;;;GAIG;AACH,iBAAiB;AACjB;;;GAGG;AACH,wBAAwB;AACxB,mEAAmE;AACnE,eAAe;AACf,6EAA6E;AAC7E,qBAAqB;AACrB;;;;GAIG;AACH,yBAAyB;AACzB;;;GAGG;AACH,wBAAwB;AACxB,4DAA4D;AAC5D,yBAAyB;AACzB;;;GAGG;AACH,+BAA+B;AAC/B,2EAA2E;AAC3E,iCAAiC;AACjC;;;;GAIG;AACH,8BAA8B;AAC9B;;;GAGG;AACH,sCAAsC;AACtC;;;;GAIG;AACH,yBAAyB;AACzB;;;GAGG;AACH,oBAAoB;AACpB,wEAAwE;AACxE,mBAAmB;AACnB;;;GAGG;AACH,oBAAoB;AACpB;;;GAGG;AACH,uBAAuB,CACf,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CACxC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CACpD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;AAChC,4DAA4D;AAC5D,sCAAsC;AACtC,4EAA4E;AAC5E,6BAA6B;AAC7B,6EAA6E;AAC7E,sBAAsB;AACtB,0DAA0D;AAC1D,8BAA8B;AAC9B,2DAA2D;AAC3D,uBAAuB,CACf,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/findings.js

@@ -0,0 +1,146 @@
+/**
+ * Why a plugin on the data volume is not running.
+ *
+ * A finding travels as one of these codes plus the values its sentence needs,
+ * never as a sentence composed by the host. The interface is Swedish by
+ * default and this package is English, so what a board reads has to be a
+ * translation of the code: a sentence written where the finding is produced
+ * reaches the board panel in the language the server happens to be written in.
+ *
+ * Listed as values rather than as a bare union so a caller can walk them and
+ * prove it has a sentence for each. Part of the contract rather than an
+ * implementation detail - docs/plugin-contract.md lists the same set, and a
+ * plugin author reading why their package was skipped is reading one of these.
+ */
+export const PLUGIN_FINDING_REASONS = [
+    /** The `openbrf` field failed validation. */
+    "manifest-invalid",
+    /** Built against a contract version this instance does not implement. */
+    "api-version-unsupported",
+    /** A declared entry file is not in the package. */
+    "entry-missing",
+    /** The server bundle does not export `createPlugin`. */
+    "entry-invalid",
+    /** `createPlugin` returned no NestJS dynamic module. */
+    "module-invalid",
+    /** Its module declares behaviour a plugin may not register. */
+    "module-refused",
+    /** Its module could not be built into the application. */
+    "module-failed",
+    /** The package carries its own copy of a host package it must share. */
+    "module-identity",
+    /** It asks for more than was consented to. */
+    "permissions-widened",
+    /** It handles a personal-data category that was not consented to. */
+    "personal-data-widened",
+    /** On the volume with no record of consent. */
+    "not-consented",
+    /** Switched off in the admin interface. */
+    "disabled",
+    /** It threw while being loaded. */
+    "load-failed",
+    /** Recorded as installed but not present. */
+    "not-on-volume",
+    /** The installed version declares an action the board did not consent to. */
+    "actions-widened",
+    /** An action the manifest declares could not be registered. */
+    "action-refused",
+    /**
+     * The installed version says otherwise than the board consented to about
+     * whether it is an AI package, in either direction.
+     */
+    "ai-changed",
+    /**
+     * The installed version reads another entitlement than the board consented
+     * to, may present the licence to a service the board was not told of, or
+     * declares a key of its issuer's the board has not consented to.
+     */
+    "licence-widened",
+    /**
+     * The installed version names another issuer of its licence than the board
+     * consented to, or no longer declares a key the board consented to.
+     */
+    "licence-issuer-changed",
+    /** It registered a website block its manifest does not declare. */
+    "block-refused",
+    /** One of its providers reaches for a core service a plugin may not hold. */
+    "forbidden-injection",
+    /**
+     * It declares the OAuth protected resource, and another installed plugin
+     * already does. The one installed first keeps it: the resource URL is the
+     * audience every issued token carries, so moving it would strand them all.
+     */
+    "oauth-resource-conflict",
+    /**
+     * A plugin it extends is not installed, not loaded, or switched off. The
+     * detail names it. An addon does not serve while its host plugin does not.
+     */
+    "extension-host-missing",
+    /** A plugin it extends declares no such extension point. */
+    "extension-point-unknown",
+    /**
+     * A point it extends is at another major version than the one it was
+     * written for.
+     */
+    "extension-version-unsupported",
+    /** It hands over a category of personal data the point does not accept. */
+    "extension-personal-data-refused",
+    /**
+     * Of it and a plugin it extends, one puts blocks on the website and the
+     * other holds a permission that reads the register. The detail names
+     * those permissions.
+     */
+    "extension-permission-refused",
+    /**
+     * It puts blocks on the website, and a plugin it extends handles personal
+     * data. The detail names those categories.
+     */
+    "extension-host-personal-data-refused",
+    /**
+     * The plugins joined to it by extensions, through one host plugin or
+     * several, hold one that puts blocks on the website and one that reads the
+     * address book. The detail names both.
+     */
+    "extension-group-refused",
+    /**
+     * It declares an extension point, or extends one, in a way the board has not
+     * consented to.
+     */
+    "extensions-widened",
+    /** A definition or contribution it registered could not be accepted. */
+    "extension-refused",
+    /**
+     * The installed version declares a recipient the board did not consent to:
+     * a new one, one at another origin, or one receiving more personal data.
+     */
+    "recipients-widened",
+    /**
+     * The installed version declares a device route the board has not consented
+     * to, or moves one (ADR 0031).
+     */
+    "device-routes-widened",
+];
+/**
+ * The manifest rules whose refusal a board reads in its own language.
+ *
+ * A manifest that fails validation is reported as `manifest-invalid`, and
+ * what Zod says about a field is English for the plugin's author. The rules
+ * below are not about one field: they hold two declarations against each
+ * other, and a board reading why a package was skipped needs to be told which
+ * in a sentence of its own. So the refusal carries the code with the English
+ * line, and the interface translates the code. Any other problem stays the
+ * English line, which is what an author fixes the package from.
+ */
+export const PLUGIN_MANIFEST_RULES = [
+    /** A device route overlaps the OAuth protected resource. */
+    "device-route-overlaps-oauth-resource",
+    /** A plugin with a device route also reads the register or the finances. */
+    "device-route-reads-register",
+    /** A plugin with a website block also reads the register or the finances. */
+    "blocks-read-register",
+    /** A plugin with a device route also proposes imports. */
+    "device-route-proposes-import",
+    /** A plugin with a website block also proposes imports. */
+    "blocks-propose-import",
+];
+//# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,6CAA6C;IAC7C,kBAAkB;IAClB,yEAAyE;IACzE,yBAAyB;IACzB,mDAAmD;IACnD,eAAe;IACf,wDAAwD;IACxD,eAAe;IACf,wDAAwD;IACxD,gBAAgB;IAChB,+DAA+D;IAC/D,gBAAgB;IAChB,0DAA0D;IAC1D,eAAe;IACf,wEAAwE;IACxE,iBAAiB;IACjB,8CAA8C;IAC9C,qBAAqB;IACrB,qEAAqE;IACrE,uBAAuB;IACvB,+CAA+C;IAC/C,eAAe;IACf,2CAA2C;IAC3C,UAAU;IACV,mCAAmC;IACnC,aAAa;IACb,6CAA6C;IAC7C,eAAe;IACf,6EAA6E;IAC7E,iBAAiB;IACjB,+DAA+D;IAC/D,gBAAgB;IAChB;;;OAGG;IACH,YAAY;IACZ;;;;OAIG;IACH,iBAAiB;IACjB;;;OAGG;IACH,wBAAwB;IACxB,mEAAmE;IACnE,eAAe;IACf,6EAA6E;IAC7E,qBAAqB;IACrB;;;;OAIG;IACH,yBAAyB;IACzB;;;OAGG;IACH,wBAAwB;IACxB,4DAA4D;IAC5D,yBAAyB;IACzB;;;OAGG;IACH,+BAA+B;IAC/B,2EAA2E;IAC3E,iCAAiC;IACjC;;;;OAIG;IACH,8BAA8B;IAC9B;;;OAGG;IACH,sCAAsC;IACtC;;;;OAIG;IACH,yBAAyB;IACzB;;;OAGG;IACH,oBAAoB;IACpB,wEAAwE;IACxE,mBAAmB;IACnB;;;OAGG;IACH,oBAAoB;IACpB;;;OAGG;IACH,uBAAuB;CACf,CAAC;AAiBX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,4DAA4D;IAC5D,sCAAsC;IACtC,4EAA4E;IAC5E,6BAA6B;IAC7B,6EAA6E;IAC7E,sBAAsB;IACtB,0DAA0D;IAC1D,8BAA8B;IAC9B,2DAA2D;IAC3D,uBAAuB;CACf,CAAC"}