@openbrf/plugin-sdk 0.0.0-stage → 1.0.0

package/dist/manifest.d.ts

@@ -0,0 +1,392 @@
+import { z } from "zod";
+/**
+ * The plugin manifest.
+ *
+ * It lives in the `openbrf` field of the plugin's own package.json rather
+ * than in a separate file: npm already installs package.json, already
+ * validates its name and version, and already refuses to install a package
+ * without one. A second manifest file could go missing, disagree with the
+ * package it sits in, or be left behind by a partial extraction, and the
+ * loader would have to decide which of the two to believe.
+ */
+/**
+ * A plugin id.
+ *
+ * Used as a URL segment (`/api/plugin/<id>/...`), an i18n namespace
+ * (`plugin-<id>`), a database key and a directory name, so it is restricted to
+ * what is safe in all four. In particular it may not contain a dot or a
+ * slash: a plugin id is resolved against paths, and `..` must not be
+ * expressible.
+ */
+export declare const pluginIdSchema: z.ZodString;
+export declare const pluginEntrySchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodString>;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * One action the plugin proposes.
+ *
+ * Declared in the manifest rather than at registration, because the board reads
+ * it on the install consent screen before anything has been downloaded, and
+ * nothing that can refuse a plugin may run after the code that executes it. The
+ * plugin's bundle supplies the schemas and the handler; what it may ask for is
+ * settled here.
+ *
+ * `capability` is a free string because this package cannot import the core
+ * capability union - it is published to plugin authors and the union is the
+ * instance's. It is resolved against the real list at the boot gate, which also
+ * refuses the ones no action of any kind may hold.
+ */
+export declare const pluginActionSchema: z.ZodObject<{
+    id: z.ZodString;
+    capability: z.ZodString;
+    effect: z.ZodEnum<{
+        delete: "delete";
+        read: "read";
+        write: "write";
+    }>;
+    personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        account: "account";
+        apartment: "apartment";
+        auditTrail: "auditTrail";
+        email: "email";
+        financial: "financial";
+        freeText: "freeText";
+        health: "health";
+        name: "name";
+        personalIdentityNumber: "personalIdentityNumber";
+        phone: "phone";
+        photograph: "photograph";
+        postalAddress: "postalAddress";
+        protected: "protected";
+        residency: "residency";
+    }>>>;
+    surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        ai: "ai";
+        mcp: "mcp";
+        ui: "ui";
+    }>>>;
+}, z.core.$strip>;
+/**
+ * The declared actions, as every boundary that reads them must read them.
+ *
+ * One schema rather than the same array written twice, because the invariant
+ * below has to hold at both: the catalog entry the consent screen renders from,
+ * and the manifest the loader enforces against it.
+ *
+ * An id appears once. Two declarations sharing one id are not a redundancy that
+ * sorts itself out - each of the three places that reads them resolves the
+ * collision differently. The binder takes the LAST, through a Map; consent
+ * compares canonical strings as a SET, so reordering the pair leaves the
+ * comparison equal and asks the board nothing; and arming stores the bare id,
+ * which names both. A republished version that only swapped the order of a
+ * duplicated pair would therefore keep its arming and go live at the OTHER
+ * declaration's capability, personal data and surfaces, with nobody having
+ * decided that. An action is one operation with one capability; two of them
+ * wearing one id is not a declaration this can read.
+ *
+ * Undefaulted, so each use site says for itself whether an absent list means
+ * "none declared" or "you did not answer". A manifest and a catalog entry mean
+ * the first and add `.default([])`; the install request means the second, since
+ * a board's echo that silently became an empty list would read as consent to no
+ * action at all - and a plugin that declares one would then be refused with a
+ * mismatch nothing the board could do would satisfy.
+ */
+export declare const pluginActionsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    capability: z.ZodString;
+    effect: z.ZodEnum<{
+        delete: "delete";
+        read: "read";
+        write: "write";
+    }>;
+    personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        account: "account";
+        apartment: "apartment";
+        auditTrail: "auditTrail";
+        email: "email";
+        financial: "financial";
+        freeText: "freeText";
+        health: "health";
+        name: "name";
+        personalIdentityNumber: "personalIdentityNumber";
+        phone: "phone";
+        photograph: "photograph";
+        postalAddress: "postalAddress";
+        protected: "protected";
+        residency: "residency";
+    }>>>;
+    surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        ai: "ai";
+        mcp: "mcp";
+        ui: "ui";
+    }>>>;
+}, z.core.$strip>>;
+/**
+ * The declared actions over a given reading of one action.
+ *
+ * The manifest reads an action as `pluginActionSchema` does; the catalog index
+ * reads the same fields strictly, because the index refuses a field its
+ * version does not define. Both keep the rule above, which is why the list is
+ * built here rather than written again.
+ */
+export declare function declaredActionsSchema<T extends z.ZodType<{
+    id: string;
+}>>(action: T): z.ZodArray<T>;
+/**
+ * The public name a declared action is offered under.
+ *
+ * The plugin's id with dashes folded to underscores, then the action's id. The
+ * folding has a consequence worth knowing: a plugin `a-b` declaring `c` and a
+ * plugin `a` declaring `b_c` compose the same name, so the registry refuses the
+ * second one to arrive and docs/plugin-contract.md says so.
+ */
+export declare function composedActionName(pluginId: string, actionId: string): string;
+export declare const pluginManifestSchema: z.ZodObject<{
+    apiVersion: z.ZodInt;
+    id: z.ZodString;
+    entry: z.ZodObject<{
+        server: z.ZodOptional<z.ZodString>;
+        client: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "addressBook:read": "addressBook:read";
+        "addressBook:readContact": "addressBook:readContact";
+        "jobs:schedule": "jobs:schedule";
+        "mail:send": "mail:send";
+        "sms:send": "sms:send";
+    }>>>;
+    personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        apartment: "apartment";
+        email: "email";
+        name: "name";
+        phone: "phone";
+        residency: "residency";
+    }>>>;
+    settingsSchema: z.ZodOptional<z.ZodObject<{
+        fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"text">;
+            default: z.ZodOptional<z.ZodString>;
+            minLength: z.ZodOptional<z.ZodInt>;
+            maxLength: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"number">;
+            default: z.ZodOptional<z.ZodNumber>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            integer: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"boolean">;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"select">;
+            default: z.ZodOptional<z.ZodString>;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                labelKey: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+    view: z.ZodOptional<z.ZodObject<{
+        module: z.ZodDefault<z.ZodString>;
+        titleKey: z.ZodString;
+    }, z.core.$strip>>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        capability: z.ZodString;
+        effect: z.ZodEnum<{
+            delete: "delete";
+            read: "read";
+            write: "write";
+        }>;
+        personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            account: "account";
+            apartment: "apartment";
+            auditTrail: "auditTrail";
+            email: "email";
+            financial: "financial";
+            freeText: "freeText";
+            health: "health";
+            name: "name";
+            personalIdentityNumber: "personalIdentityNumber";
+            phone: "phone";
+            photograph: "photograph";
+            postalAddress: "postalAddress";
+            protected: "protected";
+            residency: "residency";
+        }>>>;
+        surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            ai: "ai";
+            mcp: "mcp";
+            ui: "ui";
+        }>>>;
+    }, z.core.$strip>>>;
+    oauthProtectedResource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginManifest = z.infer<typeof pluginManifestSchema>;
+export type PluginActionDeclaration = z.infer<typeof pluginActionSchema>;
+export type PluginEntry = z.infer<typeof pluginEntrySchema>;
+/**
+ * Dependency fields npm installs at install time.
+ *
+ * The installer omits peer, dev and optional dependencies and runs no scripts,
+ * but it still hands npm the package: anything listed here would send that npm
+ * to a registry, which an instance never contacts. optionalDependencies is
+ * listed although it is omitted, because a package relying on one being
+ * present works in development and quietly not on an instance.
+ */
+export declare const RUNTIME_DEPENDENCY_FIELDS: readonly ["dependencies", "optionalDependencies", "bundleDependencies", "bundledDependencies"];
+/** Package names in a dependency field, whether a map or npm's bundle list. */
+export declare function dependencyNames(value: unknown): string[];
+/** Whether a dependency field is an empty map or an empty list. */
+export declare function isEmptyDependencyField(value: unknown): boolean;
+/**
+ * The subset of package.json the loader reads. Everything else in the file is
+ * npm's business, apart from the dependency fields, which must name nothing.
+ */
+export declare const pluginPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    openbrf: z.ZodObject<{
+        apiVersion: z.ZodInt;
+        id: z.ZodString;
+        entry: z.ZodObject<{
+            server: z.ZodOptional<z.ZodString>;
+            client: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            "addressBook:read": "addressBook:read";
+            "addressBook:readContact": "addressBook:readContact";
+            "jobs:schedule": "jobs:schedule";
+            "mail:send": "mail:send";
+            "sms:send": "sms:send";
+        }>>>;
+        personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            apartment: "apartment";
+            email: "email";
+            name: "name";
+            phone: "phone";
+            residency: "residency";
+        }>>>;
+        settingsSchema: z.ZodOptional<z.ZodObject<{
+            fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                key: z.ZodString;
+                labelKey: z.ZodString;
+                hintKey: z.ZodOptional<z.ZodString>;
+                required: z.ZodDefault<z.ZodBoolean>;
+                type: z.ZodLiteral<"text">;
+                default: z.ZodOptional<z.ZodString>;
+                minLength: z.ZodOptional<z.ZodInt>;
+                maxLength: z.ZodOptional<z.ZodInt>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                labelKey: z.ZodString;
+                hintKey: z.ZodOptional<z.ZodString>;
+                required: z.ZodDefault<z.ZodBoolean>;
+                type: z.ZodLiteral<"number">;
+                default: z.ZodOptional<z.ZodNumber>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                integer: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                labelKey: z.ZodString;
+                hintKey: z.ZodOptional<z.ZodString>;
+                required: z.ZodDefault<z.ZodBoolean>;
+                type: z.ZodLiteral<"boolean">;
+                default: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                labelKey: z.ZodString;
+                hintKey: z.ZodOptional<z.ZodString>;
+                required: z.ZodDefault<z.ZodBoolean>;
+                type: z.ZodLiteral<"select">;
+                default: z.ZodOptional<z.ZodString>;
+                options: z.ZodArray<z.ZodObject<{
+                    value: z.ZodString;
+                    labelKey: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>], "type">>;
+        }, z.core.$strip>>;
+        view: z.ZodOptional<z.ZodObject<{
+            module: z.ZodDefault<z.ZodString>;
+            titleKey: z.ZodString;
+        }, z.core.$strip>>;
+        actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            capability: z.ZodString;
+            effect: z.ZodEnum<{
+                delete: "delete";
+                read: "read";
+                write: "write";
+            }>;
+            personalData: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                account: "account";
+                apartment: "apartment";
+                auditTrail: "auditTrail";
+                email: "email";
+                financial: "financial";
+                freeText: "freeText";
+                health: "health";
+                name: "name";
+                personalIdentityNumber: "personalIdentityNumber";
+                phone: "phone";
+                photograph: "photograph";
+                postalAddress: "postalAddress";
+                protected: "protected";
+                residency: "residency";
+            }>>>;
+            surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                ai: "ai";
+                mcp: "mcp";
+                ui: "ui";
+            }>>>;
+        }, z.core.$strip>>>;
+        oauthProtectedResource: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    dependencies: z.ZodOptional<z.ZodUnknown>;
+    optionalDependencies: z.ZodOptional<z.ZodUnknown>;
+    bundleDependencies: z.ZodOptional<z.ZodUnknown>;
+    bundledDependencies: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type PluginPackage = z.infer<typeof pluginPackageSchema>;
+export interface ManifestParseFailure {
+    ok: false;
+    /** One line per problem, already naming the field. */
+    issues: string[];
+}
+export type ManifestParseResult = {
+    ok: true;
+    value: PluginPackage;
+} | ManifestParseFailure;
+/**
+ * Parses a plugin's package.json.
+ *
+ * Returns a result rather than throwing, because the only caller that matters
+ * is the boot-time scan, and a malformed plugin directory must be skipped and
+ * reported rather than being allowed to take the register offline (ADR 0003).
+ * A thrown error would make "skip and report" the caller's discipline instead
+ * of the function's contract.
+ */
+export declare function parsePluginPackage(input: unknown): ManifestParseResult;
+/** Convenience for a plugin's own CI: throws with every problem at once. */
+export declare function assertPluginPackage(input: unknown): PluginPackage;
+/** The api version a plugin authored against this SDK should declare. */
+export declare const CURRENT_PLUGIN_API_VERSION = 1;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,aAOxB,CAAC;AAqBJ,eAAO,MAAM,iBAAiB;;;iBAiB3B,CAAC;AAoBJ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4C,CAAC;AAE7E;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,EACvE,MAAM,EAAE,CAAC,iBAkBV;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkE7B,CAAC;AAEL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AACzE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,YACpC,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,CACb,CAAC;AAEX,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAKxD;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS9D;AA6BD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,mBAAmB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAAG,oBAAoB,CAAC;AAE5D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAWtE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAQjE;AAED,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,IAAqB,CAAC"}