@openbrf/plugin-sdk 0.0.0-stage → 1.2.0

package/LICENSE-EXCEPTION.md

@@ -0,0 +1,28 @@
+# Open BRF Module Exception
+
+Version 1.0
+
+## The exception
+
+As an additional permission under section 7 of the GNU Affero General Public License, version 3 ("AGPL-3.0"), the copyright holders of Open BRF give you permission to combine Open BRF with modules.
+
+A "module" is a plugin, theme, or other extension package that interacts with the Open BRF core exclusively through the documented public extension interfaces: the plugin API, the theme/token contract, the public HTTP API, and the extension points declared in the module manifest format (together, the "Module API").
+
+If you create and convey a module:
+
+1. The module is **not** considered a work based on Open BRF for the purposes of AGPL-3.0, regardless of the linking or loading mechanism.
+2. You may license the module under terms of your own choosing, including proprietary terms; nothing requires you to convey the module's source code.
+3. Running a combined work consisting of an unmodified Open BRF core and one or more modules, including offering it to users over a network, does not extend the obligations of AGPL-3.0 (including section 13) to the modules.
+
+This exception does **not** apply to:
+
+- Modifications of the Open BRF core itself, which remain governed by AGPL-3.0 in full. A "module" that patches, replaces, or bundles modified core code is a modification of the core, not a module.
+- The obligations of AGPL-3.0 regarding the core: anyone conveying or network-hosting a modified core must still offer its Corresponding Source.
+
+As provided by section 7 of AGPL-3.0, you may remove this additional permission from your copy, but you may not add further restrictions.
+
+## Why this exists
+
+The legal status of in-process plugins to (A)GPL software is a decades-old gray zone. Rather than relying on it, Open BRF states the rule explicitly, in both directions: the core is and remains copyleft, and the module ecosystem - community and commercial alike - is legally safe to build in. Vendure pioneered this model for GPL; Open BRF applies it to AGPL.
+
+This exception is granted by Apteo AB as copyright holder of Open BRF. Contributions are accepted under a [CLA](CLA.md) precisely so that this grant remains valid for the whole codebase.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @openbrf/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The plugin contract of [Open BRF](https://github.com/openbrf/openbrf): the
+manifest schema, the permission set, the interfaces of the services the host
+hands a plugin, and the schema of the catalog that lists plugins and themes.
+
+The major version is the plugin API version. Anything a plugin could notice
+raises it, and an additive change keeps it. 1.x is API version 1.
+
+## Installing
+
+```sh
+npm install --save-dev @openbrf/plugin-sdk
+```
+
+A development dependency, never a dependency. An instance installs a plugin
+offline from its verified tarball and refuses a `package.json` that declares
+any `dependencies`. Nothing in this package has to resolve at runtime: the host
+passes everything a plugin uses in through `PluginHost`, so a plugin imports
+the SDK for types and for the checks its own CI runs.
+
+`@nestjs/common` 12 is a peer dependency. A plugin declares `@nestjs/common`,
+`@nestjs/core` and `zod` as peer dependencies too, and never bundles them; the
+host supplies the running copies.
+
+## The server entry
+
+A prebuilt CommonJS bundle that exports `createPlugin`. It receives the host
+object and returns a NestJS module, whose controllers the host mounts under
+`/api/plugin/<id>/`, inside the application's authorization guard.
+
+```ts
+import { Controller, Get, Injectable, Module } from "@nestjs/common";
+import type { PluginModuleFactory } from "@openbrf/plugin-sdk";
+
+export const createPlugin: PluginModuleFactory = (host) => {
+  @Injectable()
+  class OccupancyService {
+    async summary() {
+      return host.addressBook.summary();
+    }
+  }
+
+  @Controller()
+  class OccupancyController {
+    constructor(private readonly service: OccupancyService) {}
+
+    @Get("summary")
+    async summary() {
+      return this.service.summary();
+    }
+  }
+
+  @Module({})
+  class OccupancyModule {}
+
+  return {
+    module: OccupancyModule,
+    controllers: [OccupancyController],
+    providers: [OccupancyService],
+  };
+};
+```
+
+## Checking a plugin before it is published
+
+The checks an instance runs at install and at boot are exported, so a
+plugin's CI refuses what an instance would refuse:
+
+- `assertPluginPackage(packageJson)` throws with every problem in the
+  manifest at once; `parsePluginPackage` returns them instead.
+- `pluginPackageProblems(contents)` takes the parsed `package.json`, the file
+  list, the server bundle's source and the two locale files, and returns every
+  problem that would stop the package installing or loading, one sentence
+  each.
+- `catalogEntrySchema` is the schema of the entry a listing adds to the
+  catalog.
+
+## Documentation
+
+- [The plugin contract](https://github.com/openbrf/openbrf/blob/main/docs/plugin-contract.md):
+  the manifest, permissions, personal data, the server and client entries,
+  settings, translations, distribution and installation.
+- [ADR 0003](https://github.com/openbrf/openbrf/blob/main/docs/adr/0003-plugin-loading-and-module-resolution.md):
+  how a plugin is loaded and how it resolves the host's packages.
+- [ADR 0020](https://github.com/openbrf/openbrf/blob/main/docs/adr/0020-the-public-catalog-and-the-published-packages.md):
+  the public catalog and the published packages.
+
+## Licence
+
+AGPL-3.0-only, with the
+[Open BRF Module Exception](https://github.com/openbrf/openbrf/blob/main/LICENSE-EXCEPTION.md).
+A plugin that reaches the core only through the documented extension
+interfaces is a module under that exception and may be licensed on any terms.
+Both texts are in the package.

package/dist/abort-signal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `AbortSignal` the host hands a plugin, and takes from one.
+ *
+ * The host passes a real `AbortSignal`. This package compiles against the
+ * language alone and cannot name the platform's type, so it is looked up in
+ * the plugin's own program: where that has an `AbortSignal`, from the DOM
+ * library or from Node's types, this is it, and the signal can be passed on to
+ * `fetch` and to anything else that takes one. Where it has none, this is the
+ * part of one a plugin can use without them.
+ */
+export type PluginAbortSignal = typeof globalThis extends {
+    readonly AbortSignal: {
+        readonly prototype: infer Signal;
+    };
+} ? Signal : PluginAbortSignalShape;
+/** What every `AbortSignal` has, for a program without the platform's types. */
+interface PluginAbortSignalShape {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+export {};
+//# sourceMappingURL=abort-signal.d.ts.map

package/dist/abort-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-signal.d.ts","sourceRoot":"","sources":["../src/abort-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,UAAU,SAAS;IACxD,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;CAC5D,GACG,MAAM,GACN,sBAAsB,CAAC;AAE3B,gFAAgF;AAChF,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE"}

package/dist/abort-signal.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=abort-signal.js.map

package/dist/abort-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-signal.js","sourceRoot":"","sources":["../src/abort-signal.ts"],"names":[],"mappings":""}

package/dist/action-refusal.d.ts

@@ -0,0 +1,101 @@
+import type { ActionRetry } from "./actions.ts";
+/**
+ * Why the registry refused a call, in a form a caller can act on.
+ *
+ * A caller here is often a model rather than a person, which changes what a
+ * refusal has to carry. A person reads a sentence and decides what to do; a
+ * model needs to know whether trying again could ever work, and what to change
+ * if it could. So every refusal has a code, a status, and a published rule for
+ * how a connector should render it.
+ *
+ * The vocabulary lives here rather than in the API because a plugin dispatching
+ * through `host.actions.invoke` has no other way to read it: the catalogue
+ * endpoint serves the same table over HTTP, and a plugin in the same process
+ * has no route to that. The API imports it back, so there is one list.
+ */
+export declare const ACTION_ERROR_REASONS: readonly ["unknown-action", "forbidden-capability", "forbidden-surface", "insufficient-scope", "not-serving", "read-only", "confirmation-required", "output-invalid", "rate-limited", "internal"];
+export type ActionErrorReason = (typeof ACTION_ERROR_REASONS)[number];
+/**
+ * How a connector should tell its caller about a refusal.
+ *
+ * A protocol error means the call never happened; a tool result means it
+ * happened and was refused, and only the second is something to tell the
+ * person about.
+ */
+export type ActionRefusalTransport = "protocol" | "tool-result";
+/**
+ * How a connector should render each refusal, published as data.
+ *
+ * Served on the catalogue endpoint as well, so that two connectors - one
+ * reading it over HTTP, one in process - cannot disagree about whether a 403
+ * is worth retrying. Keyed by the registry's reasons and by the two refusals
+ * that are not the registry's own: a body the action's input schema refuses,
+ * and a refusal raised by the service behind the action.
+ */
+export declare const ACTION_ERROR_MCP: Readonly<Record<ActionErrorReason | "invalid-body" | "domain", {
+    readonly transport: ActionRefusalTransport;
+    readonly retry: ActionRetry;
+}>>;
+/**
+ * Which of the three ways a call was refused.
+ *
+ * "registry" is the registry's own refusal, and `reason` is then one of
+ * ACTION_ERROR_REASONS. "invalid-body" is an input the action's schema
+ * refused, and `reason` is "invalid-body". "domain" is the service behind the
+ * action refusing on the merits, and `reason` is one the action declared in
+ * its `errors`.
+ */
+export type ActionRefusalKind = "registry" | "invalid-body" | "domain";
+/**
+ * What `host.actions.invoke` rejects with when the call was refused.
+ *
+ * One shape for all three kinds, so that a connector renders a refusal from
+ * the fields it carries rather than by recognising the host's classes, which a
+ * plugin cannot import. Recognise one with `isActionRefusal`, not with
+ * `instanceof`: the host builds it, and a plugin's bundled copy of this
+ * package is not the host's.
+ *
+ * A plugin route that rethrows one answers its caller with the same status,
+ * body and headers the registry would have.
+ */
+export interface ActionRefusal extends Error {
+    readonly name: "ActionRefusal";
+    readonly kind: ActionRefusalKind;
+    readonly reason: string;
+    /** The HTTP status the refusal answers with. */
+    readonly status: number;
+    readonly transport: ActionRefusalTransport;
+    /**
+     * From ACTION_ERROR_MCP for the registry's refusals and an invalid body. For
+     * a domain refusal, the verdict the action declared for that reason in its
+     * `errors`, or "never" for a reason it did not declare.
+     */
+    readonly retry: ActionRetry;
+    /**
+     * The particulars the refusal publishes, keyed by the field they travel in.
+     *
+     * `scopes` on an insufficient-scope refusal names the scope the call needed.
+     * `issues` on an invalid body lists `{ path, message }` for each failing
+     * field, and never the submitted value.
+     */
+    details(): Record<string, readonly unknown[]>;
+    /**
+     * The bearer challenge to answer a connected app with, as the value of a
+     * `WWW-Authenticate` header (RFC 6750, ADR 0009).
+     *
+     * Set on an insufficient-scope refusal, where it names every scope the
+     * instance issues so the client can ask for what it is missing in one round
+     * trip. Absent wherever no challenge would help.
+     */
+    readonly challenge?: string;
+}
+/**
+ * Whether a value `host.actions.invoke` rejected with is a refusal.
+ *
+ * Structural rather than `instanceof`, for the reason on ActionRefusal. False
+ * means the call failed rather than being refused - the host could not be
+ * reached, or something broke - and a connector answers that as an internal
+ * error without inspecting it.
+ */
+export declare function isActionRefusal(value: unknown): value is ActionRefusal;
+//# sourceMappingURL=action-refusal.d.ts.map

package/dist/action-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-refusal.d.ts","sourceRoot":"","sources":["../src/action-refusal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,oBAAoB,YAC/B,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,UAAU,CACF,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,aAAa,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CACrC,MAAM,CACJ,iBAAiB,GAAG,cAAc,GAAG,QAAQ,EAC7C;IACE,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B,CACF,CAcF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;;;;;;OAMG;IACH,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC;IAC9C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAkBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAyBtE"}

package/dist/action-refusal.js

@@ -0,0 +1,96 @@
+/**
+ * Why the registry refused a call, in a form a caller can act on.
+ *
+ * A caller here is often a model rather than a person, which changes what a
+ * refusal has to carry. A person reads a sentence and decides what to do; a
+ * model needs to know whether trying again could ever work, and what to change
+ * if it could. So every refusal has a code, a status, and a published rule for
+ * how a connector should render it.
+ *
+ * The vocabulary lives here rather than in the API because a plugin dispatching
+ * through `host.actions.invoke` has no other way to read it: the catalogue
+ * endpoint serves the same table over HTTP, and a plugin in the same process
+ * has no route to that. The API imports it back, so there is one list.
+ */
+export const ACTION_ERROR_REASONS = [
+    "unknown-action",
+    "forbidden-capability",
+    "forbidden-surface",
+    "insufficient-scope",
+    "not-serving",
+    "read-only",
+    "confirmation-required",
+    "output-invalid",
+    "rate-limited",
+    "internal",
+];
+/**
+ * How a connector should render each refusal, published as data.
+ *
+ * Served on the catalogue endpoint as well, so that two connectors - one
+ * reading it over HTTP, one in process - cannot disagree about whether a 403
+ * is worth retrying. Keyed by the registry's reasons and by the two refusals
+ * that are not the registry's own: a body the action's input schema refuses,
+ * and a refusal raised by the service behind the action.
+ */
+export const ACTION_ERROR_MCP = {
+    "unknown-action": { transport: "protocol", retry: "never" },
+    "invalid-body": { transport: "tool-result", retry: "after-edit" },
+    "forbidden-capability": { transport: "tool-result", retry: "never" },
+    "forbidden-surface": { transport: "tool-result", retry: "never" },
+    "insufficient-scope": { transport: "tool-result", retry: "never" },
+    "not-serving": { transport: "tool-result", retry: "never" },
+    "read-only": { transport: "tool-result", retry: "after-backoff" },
+    "confirmation-required": { transport: "tool-result", retry: "never" },
+    "output-invalid": { transport: "protocol", retry: "never" },
+    "rate-limited": { transport: "tool-result", retry: "after-backoff" },
+    internal: { transport: "protocol", retry: "after-backoff" },
+    domain: { transport: "tool-result", retry: "never" },
+};
+const KINDS = [
+    "registry",
+    "invalid-body",
+    "domain",
+];
+const TRANSPORTS = [
+    "protocol",
+    "tool-result",
+];
+const RETRIES = [
+    "never",
+    "after-edit",
+    "after-backoff",
+];
+const REGISTRY_REASONS = ACTION_ERROR_REASONS;
+/**
+ * Whether a value `host.actions.invoke` rejected with is a refusal.
+ *
+ * Structural rather than `instanceof`, for the reason on ActionRefusal. False
+ * means the call failed rather than being refused - the host could not be
+ * reached, or something broke - and a connector answers that as an internal
+ * error without inspecting it.
+ */
+export function isActionRefusal(value) {
+    if (!(value instanceof Error) || value.name !== "ActionRefusal") {
+        return false;
+    }
+    const refusal = value;
+    if (typeof refusal.reason !== "string" ||
+        typeof refusal.status !== "number" ||
+        typeof refusal.details !== "function" ||
+        !KINDS.includes(refusal.kind) ||
+        !TRANSPORTS.includes(refusal.transport) ||
+        !RETRIES.includes(refusal.retry) ||
+        (refusal.challenge !== undefined && typeof refusal.challenge !== "string")) {
+        return false;
+    }
+    switch (refusal.kind) {
+        case "registry":
+            return REGISTRY_REASONS.includes(refusal.reason);
+        case "invalid-body":
+            return refusal.reason === "invalid-body";
+        default:
+            return true;
+    }
+}
+//# sourceMappingURL=action-refusal.js.map

package/dist/action-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-refusal.js","sourceRoot":"","sources":["../src/action-refusal.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gBAAgB;IAChB,sBAAsB;IACtB,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,WAAW;IACX,uBAAuB;IACvB,gBAAgB;IAChB,cAAc;IACd,UAAU;CACF,CAAC;AAaX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAQzB;IACF,gBAAgB,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE;IAC3D,cAAc,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE;IACjE,sBAAsB,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;IACpE,mBAAmB,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;IACjE,oBAAoB,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;IAClE,aAAa,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;IAC3D,WAAW,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE;IACjE,uBAAuB,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;IACrE,gBAAgB,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE;IAC3D,cAAc,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE;IACpE,QAAQ,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE;IAC3D,MAAM,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE;CACrD,CAAC;AAyDF,MAAM,KAAK,GAAuB;IAChC,UAAU;IACV,cAAc;IACd,QAAQ;CACqB,CAAC;AAChC,MAAM,UAAU,GAAuB;IACrC,UAAU;IACV,aAAa;CACqB,CAAC;AACrC,MAAM,OAAO,GAAuB;IAClC,OAAO;IACP,YAAY;IACZ,eAAe;CACQ,CAAC;AAC1B,MAAM,gBAAgB,GAAuB,oBAAoB,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QAChE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,KAC+B,CAAC;IAChD,IACE,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;QAClC,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ;QAClC,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU;QACrC,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;QACvC,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC;QAChC,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,EAC1E,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,UAAU;YACb,OAAO,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACnD,KAAK,cAAc;YACjB,OAAO,OAAO,CAAC,MAAM,KAAK,cAAc,CAAC;QAC3C;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/action-schema.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+/**
+ * An action's schemas, as the JSON Schema a caller is published.
+ *
+ * The only call to `z.toJSONSchema` in the product. Every option here is set
+ * against a failure that would otherwise be silent, so they are worth reading
+ * one at a time.
+ *
+ * `io: "input"` because output mode makes a key with a default REQUIRED, and a
+ * model reading that will dutifully supply a value for every field the platform
+ * was perfectly happy to choose itself.
+ *
+ * `cycles: "throw"` because a self-referential schema has no JSON Schema
+ * without `$ref`, and a silently emitted `$ref` to a positional name is worse
+ * than a refusal at registration.
+ *
+ * `reused: "inline"` because `$defs` invents names from the position a schema
+ * happens to hold, and those names would reach a committed artefact and a
+ * third-party client. Inlining costs bytes and keeps the document stable.
+ *
+ * The function form of `unrepresentable` because the default error names
+ * neither the action nor the path, and a build failing with "unrepresentable
+ * type" and nothing else is a half hour of searching.
+ *
+ * One property is worth stating because it is NOT what one would assume: a bare
+ * `.transform()` does not throw under input mode - it is erased and the
+ * pre-transform type is emitted. The guarantee is placed where it is real, on
+ * the output helper, which does throw. So an action whose pair is converted at
+ * registration cannot carry a transform anywhere.
+ *
+ * `.refine()`, `.check()`, `.superRefine()` and `.brand()` are erased with no
+ * marker under both modes. That is why the rule for a published schema is
+ * structural constraints first: what the document says has to be at least as
+ * strict as what the runtime enforces, or a caller is told a value is
+ * acceptable that the service will refuse.
+ */
+/** Refuses a schema built with a second copy of zod, whose internals differ. */
+export declare function isHostZodSchema(schema: unknown): schema is z.ZodType;
+export declare function actionInputJsonSchema(schema: StandardSchemaV1<unknown, unknown>, actionName: string): Record<string, unknown>;
+export declare function actionOutputJsonSchema(schema: StandardSchemaV1<unknown, unknown>, actionName: string): Record<string, unknown>;
+//# sourceMappingURL=action-schema.d.ts.map

package/dist/action-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.d.ts","sourceRoot":"","sources":["../src/action-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC,OAAO,CAOpE;AA4BD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC1C,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB"}

package/dist/action-schema.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * An action's schemas, as the JSON Schema a caller is published.
+ *
+ * The only call to `z.toJSONSchema` in the product. Every option here is set
+ * against a failure that would otherwise be silent, so they are worth reading
+ * one at a time.
+ *
+ * `io: "input"` because output mode makes a key with a default REQUIRED, and a
+ * model reading that will dutifully supply a value for every field the platform
+ * was perfectly happy to choose itself.
+ *
+ * `cycles: "throw"` because a self-referential schema has no JSON Schema
+ * without `$ref`, and a silently emitted `$ref` to a positional name is worse
+ * than a refusal at registration.
+ *
+ * `reused: "inline"` because `$defs` invents names from the position a schema
+ * happens to hold, and those names would reach a committed artefact and a
+ * third-party client. Inlining costs bytes and keeps the document stable.
+ *
+ * The function form of `unrepresentable` because the default error names
+ * neither the action nor the path, and a build failing with "unrepresentable
+ * type" and nothing else is a half hour of searching.
+ *
+ * One property is worth stating because it is NOT what one would assume: a bare
+ * `.transform()` does not throw under input mode - it is erased and the
+ * pre-transform type is emitted. The guarantee is placed where it is real, on
+ * the output helper, which does throw. So an action whose pair is converted at
+ * registration cannot carry a transform anywhere.
+ *
+ * `.refine()`, `.check()`, `.superRefine()` and `.brand()` are erased with no
+ * marker under both modes. That is why the rule for a published schema is
+ * structural constraints first: what the document says has to be at least as
+ * strict as what the runtime enforces, or a caller is told a value is
+ * acceptable that the service will refuse.
+ */
+/** Refuses a schema built with a second copy of zod, whose internals differ. */
+export function isHostZodSchema(schema) {
+    return (typeof schema === "object" &&
+        schema !== null &&
+        "_zod" in schema &&
+        schema._zod !== undefined);
+}
+function convert(schema, actionName, io) {
+    if (!isHostZodSchema(schema)) {
+        throw new Error(`${actionName}: an action schema must be built with the host's zod.`);
+    }
+    const document = z.toJSONSchema(schema, {
+        target: "draft-2020-12",
+        io,
+        cycles: "throw",
+        reused: "inline",
+        unrepresentable: ({ path, message }) => {
+            throw new Error(`${actionName}: ${message} at ${[io, ...path.map(String)].join(".")}`);
+        },
+    });
+    // zod hangs a non-enumerable `~standard` on the root. A shallow copy leaves
+    // it behind, so what a caller is handed is a plain JSON document.
+    return { ...document };
+}
+export function actionInputJsonSchema(schema, actionName) {
+    return convert(schema, actionName, "input");
+}
+export function actionOutputJsonSchema(schema, actionName) {
+    return convert(schema, actionName, "output");
+}
+//# sourceMappingURL=action-schema.js.map

package/dist/action-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.js","sourceRoot":"","sources":["../src/action-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QACf,MAA6B,CAAC,IAAI,KAAK,SAAS,CAClD,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CACd,MAAe,EACf,UAAkB,EAClB,EAAsB;IAEtB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,uDAAuD,CACrE,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE;QACtC,MAAM,EAAE,eAAe;QACvB,EAAE;QACF,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,QAAQ;QAChB,eAAe,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;YACrC,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,KAAK,OAAO,OAAO,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACtE,CAAC;QACJ,CAAC;KACF,CAA4B,CAAC;IAC9B,4EAA4E;IAC5E,kEAAkE;IAClE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,MAA0C,EAC1C,UAAkB;IAElB,OAAO,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,MAA0C,EAC1C,UAAkB;IAElB,OAAO,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC"}