@openbrf/plugin-sdk 1.0.0 → 1.2.0

package/src/imports.ts

@@ -0,0 +1,135 @@
+/**
+ * Handing a member list to the board (ADR 0043).
+ *
+ * A plugin that brings the association's member list in from elsewhere - a
+ * file mailed to an address, an export fetched from the economic manager's
+ * system - hands it to the core here, and the core holds it as an **import
+ * proposal**: an import session on the core's own import screen, marked as
+ * proposed by the plugin, which a board member previews, decides and applies,
+ * or rejects. The plugin never applies anything, and it learns nothing about
+ * what the file would do: each of those is a read of the register, and the
+ * permission behind this, addressBook:proposeImport, grants none.
+ */
+
+/** The file a plugin hands over. */
+export interface ImportProposalFile {
+  /** Shown to the board beside the proposal. 1 to 255 characters. */
+  fileName: string;
+  /**
+   * The file, CSV or XLSX, which the core parses exactly as it parses an
+   * upload, with the same limits. A source that gives JSON is written out as
+   * CSV first.
+   */
+  content: Uint8Array;
+  /**
+   * Who sent the file, as the source reports it: the address an email came
+   * from. Absent for a source that has no sender, such as a fetch from a
+   * manager's system. A claim, not a verified identity, and shown to the board
+   * as one. At most 320 characters.
+   */
+  sender?: string;
+}
+
+export interface ImportProposalReceipt {
+  proposalId: string;
+  /** Data rows read from the file, below its column titles. */
+  rowCount: number;
+  /** ISO 8601. When the proposal expires if nobody decides it. */
+  expiresAt: string;
+}
+
+/** Where one of the plugin's own proposals stands. */
+export const IMPORT_PROPOSAL_STATES = [
+  /** Waiting for the board. */
+  "pending",
+  /** A board member started the import, and it is being written. */
+  "applying",
+  "applied",
+  /** The import a board member started stopped before the end. */
+  "failed",
+  "rejected",
+  /** A newer proposal from the same plugin replaced it. */
+  "superseded",
+  /** Nobody decided it in time. */
+  "expired",
+  /** The plugin took it back. */
+  "withdrawn",
+  /** Not one of this plugin's proposals, or no longer kept. */
+  "unknown",
+] as const;
+
+export type ImportProposalState = (typeof IMPORT_PROPOSAL_STATES)[number];
+
+export interface ImportProposalStatus {
+  state: ImportProposalState;
+  /** ISO 8601. When it reached the state it is in. Null while pending or unknown. */
+  decidedAt: string | null;
+}
+
+/**
+ * Why a file was refused. Nothing was stored for it.
+ *
+ * The reasons an upload is refused for, and four of a proposal's own:
+ * `file-unchanged` when the rows are those of the last file from this plugin
+ * the board applied or of the one still pending, `sender-too-long`,
+ * `sender-invalid` when the sender is neither text nor left out, and
+ * `file-name-invalid`. Treat a reason you do not know as a refusal all the
+ * same: a later core may add one.
+ */
+export const IMPORT_PROPOSAL_REFUSAL_REASONS = [
+  "file-name-invalid",
+  "file-empty",
+  "header-row-missing",
+  "file-too-large",
+  "file-unreadable",
+  "file-mixed-encoding",
+  "too-many-rows",
+  "too-many-columns",
+  "cell-too-long",
+  "unterminated-quote",
+  "workbook-too-large",
+  "file-unchanged",
+  "sender-too-long",
+  "sender-invalid",
+] as const;
+
+export type ImportProposalRefusalReason =
+  (typeof IMPORT_PROPOSAL_REFUSAL_REASONS)[number];
+
+/**
+ * `host.imports.propose` refused the file. Carries the reason and nothing from
+ * the file, so it can be logged as it is.
+ */
+export class ImportProposalRefusedError extends Error {
+  constructor(readonly reason: string) {
+    super(`The core refused the import proposal: ${reason}.`);
+    this.name = "ImportProposalRefusedError";
+  }
+}
+
+/**
+ * Proposing imports. Requires addressBook:proposeImport.
+ *
+ * A plugin has at most one pending proposal: a new one replaces the one
+ * before, which becomes `superseded`. A proposal nobody decides expires after
+ * 14 days, and a decided one stays answerable by `status` for 90 days.
+ *
+ * What the plugin must not keep, which the catalog review checks: the file,
+ * or any part of it, is never passed to `host.jobs`, written to the log, the
+ * settings, any store the host offers or an error the plugin throws, and the
+ * plugin drops its copy once `propose` has answered. The sender likewise.
+ */
+export interface PluginImports {
+  /**
+   * Hands a member list to the core for the board to review. Resolves once the
+   * core has parsed the file and stored the proposal, or rejects with
+   * ImportProposalRefusedError and stores nothing.
+   */
+  propose(file: ImportProposalFile): Promise<ImportProposalReceipt>;
+
+  /** Where one of this plugin's own proposals stands. */
+  status(proposalId: string): Promise<ImportProposalStatus>;
+
+  /** Withdraws this plugin's pending proposal. True when there was one. */
+  withdraw(proposalId: string): Promise<boolean>;
+}

package/src/index.ts

@@ -8,6 +8,7 @@
  * a plugin ship as a self-contained bundle (ADR 0003).
  */
 
+export type { PluginAbortSignal } from "./abort-signal.ts";
 export {
   ACTION_CHANNELS,
   ACTION_EFFECTS,
@@ -23,12 +24,24 @@ export {
   type ActionPersonalData,
   type ActionPrincipal,
   type ActionRequest,
+  type ActionRetry,
   type ActionSummary,
   type ActionSurface,
+  type PendingChangeReceipt,
+  type ActionWithSchemas,
   type PluginActionFilter,
   type PluginActionRegistration,
   type PluginActions,
 } from "./actions.ts";
+export {
+  ACTION_ERROR_MCP,
+  ACTION_ERROR_REASONS,
+  type ActionErrorReason,
+  type ActionRefusal,
+  type ActionRefusalKind,
+  type ActionRefusalTransport,
+  isActionRefusal,
+} from "./action-refusal.ts";
 export {
   actionInputJsonSchema,
   actionOutputJsonSchema,
@@ -39,15 +52,44 @@ export {
   PLUGIN_API_VERSION,
   SUPPORTED_PLUGIN_API_VERSIONS,
 } from "./api-version.ts";
+export {
+  PLUGIN_BLOCK_ATTRIBUTES,
+  PLUGIN_BLOCK_CATEGORIES,
+  PLUGIN_BLOCK_ELEMENTS,
+  PLUGIN_BLOCK_ICONS,
+  PLUGIN_BLOCK_NAME_PATTERN,
+  PLUGIN_BLOCK_RENDER_TIMEOUT_MS,
+  type PluginBlockAbortSignal,
+  type PluginBlockCategory,
+  type PluginBlockContent,
+  type PluginBlockDeclaration,
+  type PluginBlockElement,
+  type PluginBlockElementName,
+  type PluginBlockIcon,
+  type PluginBlockNode,
+  type PluginBlockRegistration,
+  type PluginBlockRenderContext,
+  type PluginBlocks,
+  pluginBlockSchema,
+  pluginBlocksSchema,
+  pluginBlockType,
+} from "./blocks.ts";
 export {
   type Catalog,
+  CATALOG_INDEX_VERSIONS,
+  CATALOG_REFUSALS,
   type CatalogArtifact,
   catalogArtifactSchema,
+  type CatalogDiagnostic,
   type CatalogEntry,
   catalogEntrySchema,
+  type CatalogExtensionPoint,
+  catalogExtensionPointSchema,
   type CatalogParseResult,
   type CatalogPluginEntry,
   catalogPluginEntrySchema,
+  type CatalogRefusal,
+  type CatalogRefusalCode,
   catalogSchema,
   type CatalogThemeEntry,
   catalogThemeEntrySchema,
@@ -55,51 +97,174 @@ export {
   parseCatalogIndex,
 } from "./catalog.ts";
 export { definePlugin } from "./define-plugin.ts";
+export {
+  createTestEntitlements,
+  ENTITLEMENT_STATUSES,
+  type EntitlementState,
+  type EntitlementStatus,
+  LICENCE_FILE_MAX_BYTES,
+  LICENCE_FORMAT,
+  LICENCE_PRESENTATION_FORMAT,
+  LICENCE_PRESENTATION_MAX_BYTES,
+  type PluginEntitlements,
+  type TestEntitlementsOptions,
+  undeclaredAudienceError,
+} from "./entitlements.ts";
+export {
+  EXTENSION_MAX_OUTPUT_LENGTH,
+  EXTENSION_MAX_TIMEOUT_MS,
+  EXTENSION_POINT_ID_PATTERN,
+  EXTENSION_RESULT_REASONS,
+  EXTENSION_TIMEOUT_MS,
+  type ExtensionContext,
+  type ExtensionContributionDefinition,
+  type ExtensionContributionSummary,
+  type ExtensionPointDefinition,
+  type ExtensionResult,
+  type ExtensionResultReason,
+  type ExtensionTarget,
+  MAX_EXTENSION_POINTS,
+  type PluginExtensions,
+} from "./extensions.ts";
+export {
+  PLUGIN_FINANCE_EVENTS,
+  PluginDeliveryRefusedError,
+  type PluginDeliveryReceipt,
+  type PluginDeliveryReceiptInput,
+  type PluginDeliveryReference,
+  type PluginFeeNotice,
+  type PluginFeeNoticeHolders,
+  type PluginFeeNotification,
+  type PluginFeeNotificationSummary,
+  type PluginFinanceEvent,
+  type PluginFinanceEvents,
+  type PluginFinanceEventType,
+  type PluginFinances,
+  type PluginMemberCharge,
+  type PluginMemberChargeParty,
+  type PluginMemberChargeReason,
+} from "./finances.ts";
+export {
+  IMPORT_PROPOSAL_REFUSAL_REASONS,
+  IMPORT_PROPOSAL_STATES,
+  type ImportProposalFile,
+  type ImportProposalReceipt,
+  type ImportProposalRefusalReason,
+  ImportProposalRefusedError,
+  type ImportProposalState,
+  type ImportProposalStatus,
+  type PluginImports,
+} from "./imports.ts";
 export { formatSha512, IntegrityError, parseSha512 } from "./integrity.ts";
 export {
   PLUGIN_FINDING_REASONS,
+  PLUGIN_MANIFEST_RULES,
   type PluginFindingDetail,
   type PluginFindingReason,
+  type PluginManifestRule,
 } from "./findings.ts";
 export {
+  PLUGIN_RECIPIENT_ERROR_CODES,
+  type DeviceTokenSummary,
+  type PluginAddress,
   type PluginAddressBook,
+  type PluginAddresses,
   type PluginApartment,
+  type PluginBookableResource,
+  type PluginBookings,
+  type PluginBusyInterval,
+  type PluginCalendar,
+  type PluginContentAudience,
+  type PluginDevices,
+  type PluginDisclosure,
   type PluginHost,
   PluginHostUnavailableError,
   type PluginJobs,
   type PluginLogger,
   type PluginMail,
   type PluginMailMessage,
+  type PluginMedia,
+  type PluginMediaFile,
+  type PluginMediaStream,
+  type PluginMeetingNotice,
+  type PluginNews,
+  type PluginNewsItem,
   type PluginOccupancySummary,
+  type PluginOccurrence,
   PluginPermissionError,
+  PluginRecipientError,
+  type PluginRecipientErrorCode,
+  type PluginRecipientRequest,
+  type PluginRecipientResponse,
+  type PluginRecipients,
   type PluginResident,
   type PluginSettings,
+  type PluginInstalledTheme,
   type PluginSms,
   type PluginSmsMessage,
+  type PluginThemeInstallOptions,
+  type PluginThemeInstallResult,
+  type PluginThemeInstallWarning,
+  type PluginThemes,
 } from "./host.ts";
 export type { PluginModuleFactory } from "./module.ts";
 export {
   assertPluginPackage,
   composedActionName,
   CURRENT_PLUGIN_API_VERSION,
+  declaredExtensionPointsSchema,
+  declaredExtensionsSchema,
+  extensionGroupRefusals,
+  extensionHostPersonalDataRefused,
+  extensionPermissionsRefused,
+  extensionPointIdSchema,
+  extensionPointRefusal,
+  type ExtensionPointRefusal,
+  extensionRuleIssues,
+  MAX_DEVICE_ROUTES,
+  isCalendarDay,
+  licenceAudienceSchema,
+  licenceKeyIdSchema,
+  licencePublicKeySchema,
   type ManifestParseResult,
   type PluginActionDeclaration,
   pluginActionSchema,
   pluginActionsSchema,
+  type PluginDeviceRoute,
+  pluginDeviceRouteSchema,
+  pluginDeviceRoutesSchema,
   type PluginEntry,
   pluginEntrySchema,
+  type PluginExtensionDeclaration,
+  type PluginExtensionPointDeclaration,
+  pluginExtensionPointSchema,
+  pluginExtensionSchema,
   pluginIdSchema,
+  type PluginLicenceDeclaration,
+  pluginLicenceSchema,
   type PluginManifest,
   pluginManifestSchema,
   type PluginPackage,
   pluginPackageSchema,
+  type PluginView,
+  pluginViewSchema,
+  type PluginViewSection,
+  PLUGIN_VIEW_SECTIONS,
   parsePluginPackage,
+  proposeImportPersonalDataIssues,
+  routePathsOverlap,
 } from "./manifest.ts";
 export {
   HOST_SHARED_PACKAGES,
   type PluginPackageContents,
   pluginPackageProblems,
 } from "./package-check.ts";
+export {
+  PLUGIN_ROUTE_CAPABILITIES,
+  type PluginRouteCapability,
+  REQUIRED_CAPABILITIES_KEY,
+  RequireCapability,
+} from "./require-capability.ts";
 export type {
   StandardSchemaIssue,
   StandardSchemaResult,
@@ -111,7 +276,33 @@ export {
   PLUGIN_PERSONAL_DATA_CATEGORIES,
   type PluginPermission,
   type PluginPersonalDataCategory,
+  PROPOSE_IMPORT_ONLY_PERSONAL_DATA,
+  PROPOSE_IMPORT_PERSONAL_DATA,
 } from "./permissions.ts";
+export {
+  canonicalRecipient,
+  type PluginRecipient,
+  pluginRecipientSchema,
+  pluginRecipientsSchema,
+  RECEIVING_HOSTS_MAX_LENGTH,
+  receivingHosts,
+  recipientHost,
+  recipientOriginSchema,
+  recipientsBeyondConsent,
+  sameRecipientDeclaration,
+} from "./recipients.ts";
+export {
+  type JsonValue,
+  PLUGIN_RECORD_COLLECTION_PATTERN,
+  PLUGIN_RECORD_KEY_PATTERN,
+  PLUGIN_RECORD_LIMITS,
+  type PluginRecord,
+  PluginRecordConflictError,
+  PluginRecordIdentityNumberError,
+  type PluginRecordLimit,
+  PluginRecordLimitError,
+  type PluginRecords,
+} from "./records.ts";
 export {
   defaultSettings,
   type PluginSettingsField,
@@ -119,5 +310,7 @@ export {
   type PluginSettingsSchema,
   pluginSettingsSchema,
   type PluginSettingsValues,
+  secretValueValidator,
   settingsValidator,
+  withoutSecretFields,
 } from "./settings-schema.ts";

package/src/localized-text.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+/**
+ * Text written in both languages the interface is offered in.
+ *
+ * For what the board reads before anything has been downloaded: the catalog's
+ * own name and description of an entry, and the parts of a declaration the
+ * consent screen shows, such as a recipient's purpose. A plugin's locale files
+ * reach the instance with its package, so a key into them would have no words
+ * behind it on the screen that decides whether the package is fetched.
+ *
+ * Strict, so a misspelled language is refused rather than dropped.
+ */
+export const localizedTextSchema = z.strictObject({
+  sv: z.string().min(1).max(500),
+  en: z.string().min(1).max(500),
+});
+
+export type LocalizedText = z.infer<typeof localizedTextSchema>;