@browxai/plugin-example 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kalebtec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @browxai/plugin-example
+
+The canonical browxai reference plugin. Exercises every primitive of
+the v1 plugin-runtime contract — a `register(api)` entry module,
+namespaced tool registration, an empty `capabilities` array (runs on a
+server with the default capability set), an empty `dependsOn` graph, a
+unit-test file, and a typed `schema.d.ts` SDK overlay. It is the
+fixture the plugin-runtime keystone test loads end-to-end, and the
+layout plugin authors copy to start their own plugin (see
+`docs/plugin-authoring.md` in the browxai repo).
+
+Three tools:
+
+- `example.echo({msg})` → `{ok, result}` — round-trip primitive.
+- `example.add({a, b})` → `{ok, sum}` — typed-arg demonstration.
+- `example.now()` → `{ok, iso, epochMs}` — argless tool shape.
+
+## Install
+
+```sh
+$ browxai plugin install @browxai/plugin-example
+```
+
+No extra capabilities required. Restart the browxai server after
+install (plugin lifecycle is resolved-once-at-server-start). The tools
+surface as `example.echo` (etc.) on MCP `tools/list`, and on the SDK as
+`client.plugins.example.echo(...)`.
+
+## Full reference
+
+The first-party plugin reference — tool tables, error envelopes, and a
+usage walkthrough for this plugin and the three canvas adapters — lives
+at <https://browxai.com/plugins/first-party/>.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+interface ToolResponse {
+    readonly content: ReadonlyArray<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+}
+interface PluginApi {
+    readonly namespace: string;
+    readonly declaredCapabilities: ReadonlyArray<string>;
+    registerTool(name: string, def: {
+        description: string;
+        inputSchema?: Record<string, any> | undefined;
+    }, handler: (args: unknown) => Promise<ToolResponse>): void;
+    callTool(name: string, args?: Record<string, unknown>): Promise<ToolResponse>;
+    log: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Build the per-tool handlers as plain functions so the plugin's
+ * unit-test suite can exercise them WITHOUT spinning up the full
+ * runtime — the test file imports these directly.
+ */
+export declare const handlers: {
+    /** `example.echo({ msg })` → `{ ok: true, result: msg }`. The
+     *  classic round-trip primitive — used by the keystone to assert
+     *  end-to-end MCP dispatch through the plugin runtime. */
+    echo: (args: unknown) => Promise<ToolResponse>;
+    /** `example.add({ a, b })` → `{ ok: true, sum: a + b }`. Trivial
+     *  math primitive — demonstrates the handler's typed-arg pattern. */
+    add: (args: unknown) => Promise<ToolResponse>;
+    /** `example.now()` → `{ ok: true, iso, epochMs }`. Argless tool
+     *  shape; demonstrates that an empty input schema is fine. */
+    now: () => Promise<ToolResponse>;
+};
+/**
+ * Plugin entry. The runtime imports this module via
+ * `await import(<entryPath>)` and calls `register(api)`. The named
+ * export takes precedence over a default export.
+ */
+export declare function register(api: PluginApi): void;
+export default register;

package/dist/index.js

@@ -0,0 +1,81 @@
+// @browxai/plugin-example — the canonical reference plugin.
+//
+// Exercises every primitive of the v1 plugin-runtime contract:
+//   - `register(api)` entry point as a named export.
+//   - Three tools, all under the declared namespace `example.`.
+//   - No declared capabilities (the simplest case — runs on a server
+//     with the default capability set).
+//   - Empty `dependsOn` (no inter-plugin composition).
+//
+// Plugin authors: copy this layout, change `package.json#browxai`,
+// add your own tools in `register(api)`. See `docs/plugin-authoring.md`.
+//
+// The `PluginApi` shape is documented in the host's plugin-authoring
+// guide. We inline a minimal type here so the plugin doesn't import
+// from a host-internal module — once `@browxai/plugin-types`
+// ships, plugins will import the interface from there.
+const json = (obj) => ({
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+});
+/**
+ * Build the per-tool handlers as plain functions so the plugin's
+ * unit-test suite can exercise them WITHOUT spinning up the full
+ * runtime — the test file imports these directly.
+ */
+// Arrow-property form (not method-syntax) so call sites can pass
+// `handlers.echo` as a value without tripping `unbound-method`. Bodies
+// are sync — they return `Promise.resolve(...)` to honour the
+// `Promise<ToolResponse>` handler contract without an empty `async`.
+export const handlers = {
+    /** `example.echo({ msg })` → `{ ok: true, result: msg }`. The
+     *  classic round-trip primitive — used by the keystone to assert
+     *  end-to-end MCP dispatch through the plugin runtime. */
+    echo: (args) => {
+        const a = (args ?? {});
+        const msg = typeof a.msg === "string" ? a.msg : "";
+        return Promise.resolve(json({ ok: true, result: msg }));
+    },
+    /** `example.add({ a, b })` → `{ ok: true, sum: a + b }`. Trivial
+     *  math primitive — demonstrates the handler's typed-arg pattern. */
+    add: (args) => {
+        const a = (args ?? {});
+        const left = typeof a.a === "number" ? a.a : 0;
+        const right = typeof a.b === "number" ? a.b : 0;
+        return Promise.resolve(json({ ok: true, sum: left + right }));
+    },
+    /** `example.now()` → `{ ok: true, iso, epochMs }`. Argless tool
+     *  shape; demonstrates that an empty input schema is fine. */
+    now: () => {
+        const ms = Date.now();
+        return Promise.resolve(json({ ok: true, iso: new Date(ms).toISOString(), epochMs: ms }));
+    },
+};
+/**
+ * Plugin entry. The runtime imports this module via
+ * `await import(<entryPath>)` and calls `register(api)`. The named
+ * export takes precedence over a default export.
+ */
+export function register(api) {
+    api.log.info("example plugin: registering tools", { namespace: api.namespace });
+    // Tool names MUST be prefixed with the plugin's namespace. The
+    // runtime throws synchronously if a registration violates this.
+    // The Zod schema is the same shape host tools use; the plugin
+    // doesn't have to import Zod itself if the inputSchema is an
+    // empty object — the schema is consulted by MCP's `tools/list` and
+    // is purely informational at the plugin layer.
+    api.registerTool(`${api.namespace}.echo`, {
+        description: "Round-trip primitive — returns whatever `msg` was passed. Useful for proving the plugin runtime is reachable end-to-end (keystone uses this).",
+        inputSchema: {},
+    }, handlers.echo);
+    api.registerTool(`${api.namespace}.add`, {
+        description: "Sums two numeric args. Trivial demonstration of the handler's typed-arg pattern.",
+        inputSchema: {},
+    }, handlers.add);
+    api.registerTool(`${api.namespace}.now`, {
+        description: "Returns the current ISO timestamp + epoch milliseconds. No args.",
+        inputSchema: {},
+    }, handlers.now);
+}
+// Also export as default for the "default export is the register fn"
+// alternative loading path (the runtime accepts either).
+export default register;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@browxai/plugin-example",
+  "version": "0.1.0",
+  "description": "Reference browxai plugin — exercises every registry feature (tool registration, capability declaration, dependency declaration). Canonical source for plugin authors.",
+  "author": "Kalebtec",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "browxai",
+    "browxai-plugin",
+    "mcp",
+    "browser-automation",
+    "ai-agent"
+  ],
+  "homepage": "https://browxai.com/plugins/first-party/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalebteccom/browxai.git",
+    "directory": "packages/plugins/example"
+  },
+  "bugs": {
+    "url": "https://github.com/kalebteccom/browxai/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema.d.ts",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "browxai": {
+    "apiVersion": "1.0.0",
+    "browxaiVersion": "^0.7.0",
+    "namespace": "example",
+    "register": "dist/index.js",
+    "capabilities": [],
+    "trust": "kalebtec",
+    "dependsOn": []
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/schema.d.ts

@@ -0,0 +1,34 @@
+// Typed SDK overlay for `@browxai/plugin-example` consumers.
+//
+// SDK consumers import the schema type + compose it via the host's
+// `BrowxaiClientWithPlugins` helper to get autocomplete on every
+// example tool — `client.plugins.example.echo({msg:"hi"})` — with full
+// argument typing.
+//
+//   import type { ExamplePluginSchema } from "@browxai/plugin-example/schema";
+//   import type { BrowxaiClientWithPlugins } from "browxai";
+//
+//   const client = (await createBrowxai({...})) as BrowxaiClientWithPlugins<ExamplePluginSchema>;
+//   await client.plugins.example.echo({msg: "hello"});
+
+// We declare the relevant subset of the BrowxaiResult envelope here
+// rather than importing it — keeps the schema declaration free of
+// runtime deps. Adopters who want the structured payload can also
+// import the host's `BrowxaiResult` type and substitute it.
+interface ExampleBrowxaiResult {
+  readonly content: ReadonlyArray<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+  >;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface ExamplePluginSchema {
+  readonly example: {
+    /** Round-trip primitive — returns `{ok:true, result:msg}`. */
+    echo(args: { msg: string }): Promise<ExampleBrowxaiResult>;
+    /** Sums two numeric args — returns `{ok:true, sum: a+b}`. */
+    add(args: { a: number; b: number }): Promise<ExampleBrowxaiResult>;
+    /** Argless tool — returns `{ok:true, iso, epochMs}`. */
+    now(args?: Record<string, never>): Promise<ExampleBrowxaiResult>;
+  };
+}