Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,461 @@
import { describe, expect, expectTypeOf, test } from "vitest";
import {
createPluginSettingsClient,
defineHook,
type HookHandler,
type PluginContext,
type PluginHookEntityPayload,
type PluginHookPayloads,
type PluginHookWorkflowDefinitionPayload,
type PluginHookWorkflowExecutedPayload,
type PluginHookWorkflowFailedPayload,
type PluginSettingsClientMessageEvent,
type PluginSettingsClientMessageTarget,
PluginSettingsClientError,
PluginSettingsClientTimeoutError,
type PluginSettingsFrameGetMessage,
type PluginSettingsFrameMessage,
type PluginSettingsFrameReadyMessage,
type PluginSettingsFrameResultMessage,
type PluginSettingsFrameSetMessage,
type TypedHookHandler,
PLUGIN_PAYLOAD_ABI_IMPORTS,
PLUGIN_PAYLOAD_ABI_VERSION,
PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME,
PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
PLUGIN_SDK_PACKAGE_VERSION,
} from "./index.js";
function makeContext(overrides: Partial<PluginContext> = {}): PluginContext {
const log = {
info: () => undefined,
warn: () => undefined,
error: () => undefined,
};
return {
pluginId: "de.toolctrl.test",
pluginVersion: "1.0.0",
tenantId: "t-1",
hookName: "ping",
capabilities: ["log"],
log,
audit: { record: async () => undefined },
...overrides,
};
}
function makeSettingsFrameWindow() {
const posted: Array<{ message: PluginSettingsFrameMessage; targetOrigin: string }> = [];
const listeners = new Set<(event: PluginSettingsClientMessageEvent) => void>();
const parent: PluginSettingsClientMessageTarget = {
postMessage: (message, targetOrigin) => {
posted.push({ message, targetOrigin });
},
};
return {
parent,
posted,
emit: (event: PluginSettingsClientMessageEvent) => {
for (const listener of listeners) {
listener(event);
}
},
listenerCount: () => listeners.size,
addEventListener: (type: "message", listener: (event: PluginSettingsClientMessageEvent) => void) => {
expect(type).toBe("message");
listeners.add(listener);
},
removeEventListener: (type: "message", listener: (event: PluginSettingsClientMessageEvent) => void) => {
expect(type).toBe("message");
listeners.delete(listener);
},
};
}
describe("@toolctrl/plugin-sdk", () => {
test("exports a stable version constant", () => {
expect(PLUGIN_SDK_PACKAGE_VERSION).toBe("0.0.0");
});
test("exports the structured payload ABI contract", () => {
expect(PLUGIN_PAYLOAD_ABI_VERSION).toBe(1);
expect(PLUGIN_PAYLOAD_ABI_IMPORTS).toEqual(["env.toolctrl_payload_len", "env.toolctrl_payload_byte"]);
});
test("exports the settings iframe postMessage protocol contract", () => {
expect(PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION).toBe(1);
expect(PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME).toBe("plugin-settings-channel");
const getMessage: PluginSettingsFrameGetMessage = {
type: "plugin.settings.get",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "get-1",
key: "theme",
};
const setMessage: PluginSettingsFrameSetMessage = {
type: "plugin.settings.set",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "set-1",
key: "theme",
value: { mode: "dark", compact: true },
};
const resultMessage: PluginSettingsFrameResultMessage = {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "get-1",
ok: true,
key: "theme",
value: "dark",
};
expectTypeOf<PluginSettingsFrameMessage>().toEqualTypeOf<
PluginSettingsFrameReadyMessage | typeof getMessage | typeof setMessage
>();
expectTypeOf<PluginSettingsFrameResultMessage>().toEqualTypeOf<typeof resultMessage | Extract<PluginSettingsFrameResultMessage, { ok: false }>>();
expect(getMessage.type).toBe("plugin.settings.get");
expect(setMessage.value).toEqual({ mode: "dark", compact: true });
expect(resultMessage.ok).toBe(true);
});
test("createPluginSettingsClient posts ready, get, and set messages", async () => {
const frameWindow = makeSettingsFrameWindow();
const client = createPluginSettingsClient({
pluginId: "de.toolctrl.test",
channelId: "channel-1",
targetOrigin: "https://app.example.test",
requestId: () => "request-1",
window: frameWindow,
});
client.ready({ requestId: "ready-1" });
const getPromise = client.get("theme");
const setPromise = client.set("mode", "dark", { requestId: "set-1" });
expect(frameWindow.posted).toEqual([
{
targetOrigin: "https://app.example.test",
message: {
type: "plugin.settings.ready",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "ready-1",
},
},
{
targetOrigin: "https://app.example.test",
message: {
type: "plugin.settings.get",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "request-1",
key: "theme",
},
},
{
targetOrigin: "https://app.example.test",
message: {
type: "plugin.settings.set",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "set-1",
key: "mode",
value: "dark",
},
},
]);
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "request-1",
ok: true,
key: "theme",
value: { mode: "dark" },
},
});
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "set-1",
ok: true,
key: "mode",
value: "dark",
},
});
await expect(getPromise).resolves.toEqual({ mode: "dark" });
await expect(setPromise).resolves.toBe("dark");
client.destroy();
expect(frameWindow.listenerCount()).toBe(0);
});
test("createPluginSettingsClient reads the injected channel meta tag", () => {
const frameWindow = makeSettingsFrameWindow();
const client = createPluginSettingsClient({
pluginId: "de.toolctrl.test",
window: frameWindow,
document: {
querySelector: (selector) => {
expect(selector).toBe(`meta[name="${PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME}"]`);
return { getAttribute: () => "channel-from-meta" };
},
},
});
expect(client.channelId).toBe("channel-from-meta");
client.destroy();
});
test("createPluginSettingsClient ignores result messages that do not match the parent and request scope", async () => {
const frameWindow = makeSettingsFrameWindow();
const client = createPluginSettingsClient({
pluginId: "de.toolctrl.test",
channelId: "channel-1",
timeoutMs: 0,
window: frameWindow,
});
const promise = client.get("theme", { requestId: "get-1" });
for (const data of [
{ version: 2, pluginId: "de.toolctrl.test", channelId: "channel-1", requestId: "get-1" },
{ version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION, pluginId: "other", channelId: "channel-1", requestId: "get-1" },
{ version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION, pluginId: "de.toolctrl.test", channelId: "other", requestId: "get-1" },
{ version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION, pluginId: "de.toolctrl.test", channelId: "channel-1", requestId: "other" },
]) {
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
ok: true,
key: "theme",
value: "spoofed",
...data,
},
});
}
frameWindow.emit({
source: { postMessage: () => undefined },
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "get-1",
ok: true,
key: "theme",
value: "spoofed-source",
},
});
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "get-1",
ok: true,
key: "theme",
value: "dark",
},
});
await expect(promise).resolves.toBe("dark");
client.destroy();
});
test("createPluginSettingsClient rejects host errors and mismatched response keys", async () => {
const frameWindow = makeSettingsFrameWindow();
const client = createPluginSettingsClient({
pluginId: "de.toolctrl.test",
channelId: "channel-1",
timeoutMs: 0,
window: frameWindow,
});
const failed = client.set("theme", "dark", { requestId: "set-1" });
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "set-1",
ok: false,
error: "settings_update_failed",
message: "Write failed",
},
});
await expect(failed).rejects.toBeInstanceOf(PluginSettingsClientError);
await expect(failed).rejects.toMatchObject({ code: "settings_update_failed", message: "Write failed" });
const mismatched = client.get("theme", { requestId: "get-1" });
frameWindow.emit({
source: frameWindow.parent,
data: {
type: "plugin.settings.result",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId: "de.toolctrl.test",
channelId: "channel-1",
requestId: "get-1",
ok: true,
key: "other",
value: "dark",
},
});
await expect(mismatched).rejects.toThrow("Plugin settings response key mismatch");
client.destroy();
});
test("createPluginSettingsClient rejects timed out requests", async () => {
const frameWindow = makeSettingsFrameWindow();
const client = createPluginSettingsClient({
pluginId: "de.toolctrl.test",
channelId: "channel-1",
timeoutMs: 1,
window: frameWindow,
});
await expect(client.get("theme", { requestId: "get-1" })).rejects.toBeInstanceOf(PluginSettingsClientTimeoutError);
client.destroy();
});
test("defineHook preserves the typed handler", async () => {
const handler = defineHook<{ name: string }, { greeting: string }>((input) => ({
greeting: `Hello, ${input.name}!`,
}));
const result = await handler({ name: "World" }, makeContext());
expect(result.greeting).toBe("Hello, World!");
});
test("HookHandler accepts async handlers", async () => {
const handler: HookHandler<number, number> = async (n) => n * 2;
expect(await handler(21, makeContext())).toBe(42);
});
test("TypedHookHandler exposes canonical entity hook payloads", async () => {
expectTypeOf<PluginHookPayloads["entity.updated"]>().toEqualTypeOf<PluginHookEntityPayload>();
const handler: TypedHookHandler<"entity.updated", { target: string }> = (input) => ({
target: `${input.entityType}:${input.entityId}`,
});
const result = await handler(
{
entityType: "contact",
entityId: "row_1",
tenantId: "tenant_1",
userId: "user_1",
changedFields: ["email"],
occurredAt: "2026-05-27T12:00:00.000Z",
},
makeContext({ hookName: "entity.updated" })
);
expect(result).toEqual({ target: "contact:row_1" });
});
test("TypedHookHandler exposes workflow.executed metadata without raw execution bodies", async () => {
expectTypeOf<PluginHookPayloads["workflow.executed"]>().toEqualTypeOf<PluginHookWorkflowExecutedPayload>();
expectTypeOf<PluginHookWorkflowExecutedPayload>().not.toHaveProperty("input");
expectTypeOf<PluginHookWorkflowExecutedPayload>().not.toHaveProperty("output");
expectTypeOf<PluginHookWorkflowExecutedPayload>().not.toHaveProperty("error");
const handler: TypedHookHandler<"workflow.executed", { terminal: true }> = (input) => {
expect(input.status).toBe("success");
expect(input.errorCode).toBeNull();
return { terminal: true };
};
const result = await handler(
{
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: "user_1",
type: "trigger",
status: "success",
durationMs: 42,
errorCode: null,
appliesToAllTenants: false,
occurredAt: "2026-05-27T12:00:00.000Z",
},
makeContext({ hookName: "workflow.executed" })
);
expect(result).toEqual({ terminal: true });
});
test("TypedHookHandler exposes workflow.failed failure-only metadata", async () => {
expectTypeOf<PluginHookPayloads["workflow.failed"]>().toEqualTypeOf<PluginHookWorkflowFailedPayload>();
expectTypeOf<PluginHookWorkflowFailedPayload>().not.toHaveProperty("input");
expectTypeOf<PluginHookWorkflowFailedPayload>().not.toHaveProperty("output");
expectTypeOf<PluginHookWorkflowFailedPayload>().not.toHaveProperty("error");
const handler: TypedHookHandler<"workflow.failed", { failureCode: string }> = (input) => ({
failureCode: input.errorCode,
});
const result = await handler(
{
tenantId: "tenant_1",
workflowId: "workflow_1",
workflowExecutionId: "execution_1",
userId: null,
type: "trigger",
status: "error",
durationMs: 42,
errorCode: "workflow_execution_failed",
appliesToAllTenants: false,
occurredAt: "2026-05-27T12:00:00.000Z",
},
makeContext({ hookName: "workflow.failed" })
);
expect(result).toEqual({ failureCode: "workflow_execution_failed" });
});
test("TypedHookHandler exposes workflow definition metadata without workflow bodies", async () => {
expectTypeOf<PluginHookPayloads["workflow.updated"]>().toEqualTypeOf<PluginHookWorkflowDefinitionPayload>();
expectTypeOf<PluginHookWorkflowDefinitionPayload>().not.toHaveProperty("blocks");
expectTypeOf<PluginHookWorkflowDefinitionPayload>().not.toHaveProperty("credentials");
expectTypeOf<PluginHookWorkflowDefinitionPayload>().not.toHaveProperty("input");
const handler: TypedHookHandler<"workflow.updated", { changed: number }> = (input) => ({
changed: input.changedFields?.length ?? 0,
});
const result = await handler(
{
tenantId: "tenant_1",
workflowId: "workflow_1",
userId: "user_1",
status: "live",
appliesToAllTenants: false,
changedFields: ["status"],
occurredAt: "2026-05-27T12:00:00.000Z",
},
makeContext({ hookName: "workflow.updated" })
);
expect(result).toEqual({ changed: 1 });
});
});
@@ -0,0 +1,483 @@
/**
* @toolctrl/plugin-sdk — Phase 06 Task #21 foundation.
*
* Type definitions plugin authors `import` against. The package ships
* type-only declarations in this foundation step; the AssemblyScript /
* Rust toolchain bindings that resolve to actual WASM imports are
* deferred to Phase 06 Task #23 (audit + docs).
*
* Authoring shape:
*
* import type { HookHandler, PluginContext } from "@toolctrl/plugin-sdk";
*
* export const handleHello: HookHandler<{ name: string }, { greeting: string }> = (
* input,
* ctx,
* ) => {
* ctx.log.info({ name: input.name }, "hello");
* return { greeting: `Hello, ${input.name}!` };
* };
*/
export const PLUGIN_SDK_PACKAGE_VERSION = "0.0.0";
export const PLUGIN_PAYLOAD_ABI_VERSION = 1;
export const PLUGIN_PAYLOAD_ABI_IMPORTS = ["env.toolctrl_payload_len", "env.toolctrl_payload_byte"] as const;
export const PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION = 1;
export const PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME = "plugin-settings-channel";
/**
* Capability names a host exposes to a plugin — mirrors the closed enum
* in `@toolctrl/plugin-runtime`. Kept duplicated here so plugin authors
* don't need to install the runtime package as a build-time dep.
*/
export type PluginCapabilityName =
| "http.outbound"
| "db.read"
| "db.write"
| "storage.read"
| "storage.write"
| "log"
| "audit"
| "tenant.info"
| "secret.read";
/**
* Foundation hook names the host can emit. Mirrors the runtime hook
* registry so plugin authors can type their handlers without importing
* `@toolctrl/plugin-runtime`.
*/
export type PluginHookName =
| "tenant.created"
| "user.created"
| "entity.created"
| "entity.updated"
| "entity.deleted"
| "workflow.created"
| "workflow.updated"
| "workflow.deleted"
| "workflow.executed"
| "workflow.failed";
export interface PluginHookTenantCreatedPayload {
readonly tenantId: string;
readonly slug: string;
readonly ownerEmail?: string | null;
readonly plan?: string | null;
readonly createdAt: string;
}
export interface PluginHookUserCreatedPayload {
readonly userId: string;
readonly tenantId?: string | null;
readonly email: string;
readonly locale?: string | null;
readonly createdAt: string;
}
export interface PluginHookEntityPayload {
readonly entityType: string;
readonly entityId: string;
readonly tenantId: string | null;
readonly userId?: string | null;
readonly changedFields?: ReadonlyArray<string>;
readonly occurredAt: string;
}
export interface PluginHookWorkflowExecutedPayload {
readonly tenantId: string;
readonly workflowId: string;
readonly workflowExecutionId: string;
readonly userId?: string | null;
readonly type: "manual" | "api" | "stream" | "trigger";
readonly status: "success" | "error";
readonly durationMs: number;
readonly errorCode: string | null;
readonly appliesToAllTenants: boolean;
readonly occurredAt: string;
}
export interface PluginHookWorkflowFailedPayload extends Omit<PluginHookWorkflowExecutedPayload, "status" | "errorCode"> {
readonly status: "error";
readonly errorCode: string;
}
export interface PluginHookWorkflowDefinitionPayload {
readonly tenantId: string | null;
readonly workflowId: string;
readonly userId: string | null;
readonly status: "draft" | "live" | "archived";
readonly appliesToAllTenants: boolean;
readonly changedFields?: ReadonlyArray<string>;
readonly occurredAt: string;
}
export type PluginHookPayloads = {
readonly "tenant.created": PluginHookTenantCreatedPayload;
readonly "user.created": PluginHookUserCreatedPayload;
readonly "entity.created": PluginHookEntityPayload;
readonly "entity.updated": PluginHookEntityPayload;
readonly "entity.deleted": PluginHookEntityPayload;
readonly "workflow.created": PluginHookWorkflowDefinitionPayload;
readonly "workflow.updated": PluginHookWorkflowDefinitionPayload;
readonly "workflow.deleted": PluginHookWorkflowDefinitionPayload;
readonly "workflow.executed": PluginHookWorkflowExecutedPayload;
readonly "workflow.failed": PluginHookWorkflowFailedPayload;
};
/** Subset of pino's logger surface the host exposes via the `log` cap. */
export interface PluginLogger {
info(fields: Record<string, unknown>, msg: string): void;
warn(fields: Record<string, unknown>, msg: string): void;
error(fields: Record<string, unknown>, msg: string): void;
}
/** HTTP host binding — gated on the `http.outbound` capability. */
export interface PluginHttpClient {
fetch(input: { url: string; method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; headers?: Record<string, string>; body?: string }): Promise<{
status: number;
headers: Record<string, string>;
body: string;
}>;
}
/** Tenant-scoped KV store — gated on `storage.read` / `storage.write`. */
export interface PluginStorage {
get(key: string): Promise<string | null>;
put(key: string, value: string, opts?: { ttlSeconds?: number }): Promise<void>;
}
/** Audit-event sink — always allowed. */
export interface PluginAudit {
record(input: { action: string; target?: string; meta?: Record<string, unknown> }): Promise<void>;
}
/** Read-only tenant metadata — always allowed. */
export interface PluginTenantInfo {
id: string;
slug: string;
plan: string;
}
/**
* Aggregate host API surface, partial because each plugin only sees
* the bindings whose capabilities it declared in `plugin.toml`.
*/
export interface HostApi {
log: PluginLogger;
audit: PluginAudit;
tenant?: PluginTenantInfo;
http?: PluginHttpClient;
storage?: PluginStorage;
secret?: { get(key: string): Promise<string | null> };
}
export type PluginSettingValue = null | boolean | number | string | ReadonlyArray<PluginSettingValue> | { readonly [key: string]: PluginSettingValue };
export type PluginSettingsFrameReadyMessage = {
readonly type: "plugin.settings.ready";
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
readonly pluginId: string;
readonly channelId: string;
readonly requestId?: string;
};
export type PluginSettingsFrameGetMessage = {
readonly type: "plugin.settings.get";
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
readonly pluginId: string;
readonly channelId: string;
readonly requestId: string;
readonly key: string;
};
export type PluginSettingsFrameSetMessage = {
readonly type: "plugin.settings.set";
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
readonly pluginId: string;
readonly channelId: string;
readonly requestId: string;
readonly key: string;
readonly value: PluginSettingValue;
};
export type PluginSettingsFrameMessage = PluginSettingsFrameReadyMessage | PluginSettingsFrameGetMessage | PluginSettingsFrameSetMessage;
export type PluginSettingsFrameResultMessage =
| {
readonly type: "plugin.settings.result";
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
readonly pluginId: string;
readonly channelId: string;
readonly requestId: string;
readonly ok: true;
readonly key: string;
readonly value: PluginSettingValue;
}
| {
readonly type: "plugin.settings.result";
readonly version: typeof PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION;
readonly pluginId: string;
readonly channelId: string;
readonly requestId: string;
readonly ok: false;
readonly error: "invalid_payload" | "settings_unavailable" | "settings_update_failed";
readonly message: string;
};
export interface PluginSettingsClientMessageTarget {
postMessage(message: PluginSettingsFrameMessage, targetOrigin: string): void;
}
export interface PluginSettingsClientMessageEvent {
readonly source: unknown;
readonly data: unknown;
}
export interface PluginSettingsClientWindow {
readonly parent: PluginSettingsClientMessageTarget;
addEventListener(type: "message", listener: (event: PluginSettingsClientMessageEvent) => void): void;
removeEventListener(type: "message", listener: (event: PluginSettingsClientMessageEvent) => void): void;
}
export interface PluginSettingsClientDocument {
querySelector(selector: string): { getAttribute(name: string): string | null } | null;
}
export interface PluginSettingsClientRequestOptions {
readonly requestId?: string;
readonly timeoutMs?: number;
}
export interface PluginSettingsClientOptions {
readonly pluginId: string;
readonly channelId?: string;
readonly targetOrigin?: string;
readonly timeoutMs?: number;
readonly requestId?: () => string;
readonly window?: PluginSettingsClientWindow;
readonly document?: PluginSettingsClientDocument;
}
export interface PluginSettingsClient {
readonly pluginId: string;
readonly channelId: string;
ready(options?: { readonly requestId?: string }): void;
get(key: string, options?: PluginSettingsClientRequestOptions): Promise<PluginSettingValue>;
set(key: string, value: PluginSettingValue, options?: PluginSettingsClientRequestOptions): Promise<PluginSettingValue>;
destroy(): void;
}
type PluginSettingsClientPendingRequest = {
readonly key: string;
readonly timeout: ReturnType<typeof setTimeout> | null;
resolve(value: PluginSettingValue): void;
reject(error: Error): void;
};
export class PluginSettingsClientError extends Error {
readonly code: PluginSettingsFrameResultMessage extends infer Message
? Message extends { readonly ok: false; readonly error: infer Code }
? Code
: never
: never;
constructor(code: PluginSettingsClientError["code"], message: string) {
super(message);
this.name = "PluginSettingsClientError";
this.code = code;
}
}
export class PluginSettingsClientTimeoutError extends Error {
constructor(requestId: string) {
super(`Plugin settings request timed out: ${requestId}`);
this.name = "PluginSettingsClientTimeoutError";
}
}
function getDefaultPluginSettingsWindow(): PluginSettingsClientWindow | undefined {
const maybeWindow = (globalThis as { window?: PluginSettingsClientWindow }).window;
return maybeWindow?.parent && typeof maybeWindow.addEventListener === "function" && typeof maybeWindow.removeEventListener === "function"
? maybeWindow
: undefined;
}
function getDefaultPluginSettingsDocument(): PluginSettingsClientDocument | undefined {
const maybeDocument = (globalThis as { document?: PluginSettingsClientDocument }).document;
return maybeDocument && typeof maybeDocument.querySelector === "function" ? maybeDocument : undefined;
}
function readPluginSettingsChannelId(documentRef: PluginSettingsClientDocument | undefined): string | undefined {
return documentRef?.querySelector(`meta[name="${PLUGIN_SETTINGS_FRAME_CHANNEL_META_NAME}"]`)?.getAttribute("content") ?? undefined;
}
function isPluginSettingsFrameResultMessage(value: unknown): value is PluginSettingsFrameResultMessage {
return typeof value === "object" && value !== null && (value as { type?: unknown }).type === "plugin.settings.result";
}
/**
* Build a small settings iframe client around the host postMessage protocol.
* Responses are accepted only from `window.parent` and only when protocol
* version, plugin id, channel id, and request id match a pending request.
*/
export function createPluginSettingsClient(options: PluginSettingsClientOptions): PluginSettingsClient {
const frameWindow = options.window ?? getDefaultPluginSettingsWindow();
if (!frameWindow) {
throw new Error("Plugin settings client requires a window with a parent postMessage target");
}
const pluginId = options.pluginId;
const channelId = options.channelId ?? readPluginSettingsChannelId(options.document ?? getDefaultPluginSettingsDocument());
if (!channelId) {
throw new Error("Missing plugin settings channel");
}
const targetOrigin = options.targetOrigin ?? "*";
const defaultTimeoutMs = options.timeoutMs ?? 10_000;
const nextRequestId =
options.requestId ??
(() => {
let next = 0;
return () => `plugin-settings-${++next}`;
})();
const pending = new Map<string, PluginSettingsClientPendingRequest>();
const onMessage = (event: PluginSettingsClientMessageEvent) => {
if (event.source !== frameWindow.parent || !isPluginSettingsFrameResultMessage(event.data)) {
return;
}
const message = event.data;
if (message.version !== PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION || message.pluginId !== pluginId || message.channelId !== channelId) {
return;
}
const request = pending.get(message.requestId);
if (!request) {
return;
}
pending.delete(message.requestId);
if (request.timeout) {
clearTimeout(request.timeout);
}
if (message.ok) {
if (message.key !== request.key) {
request.reject(new Error(`Plugin settings response key mismatch for request: ${message.requestId}`));
return;
}
request.resolve(message.value);
return;
}
request.reject(new PluginSettingsClientError(message.error, message.message));
};
frameWindow.addEventListener("message", onMessage);
const post = (message: PluginSettingsFrameMessage) => {
frameWindow.parent.postMessage(message, targetOrigin);
};
const request = (
type: "plugin.settings.get" | "plugin.settings.set",
key: string,
value: PluginSettingValue | undefined,
requestOptions?: PluginSettingsClientRequestOptions
) => {
const requestId = requestOptions?.requestId ?? nextRequestId();
const timeoutMs = requestOptions?.timeoutMs ?? defaultTimeoutMs;
return new Promise<PluginSettingValue>((resolve, reject) => {
const timeout =
timeoutMs > 0
? setTimeout(() => {
pending.delete(requestId);
reject(new PluginSettingsClientTimeoutError(requestId));
}, timeoutMs)
: null;
pending.set(requestId, { key, timeout, resolve, reject });
post(
type === "plugin.settings.get"
? {
type,
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId,
channelId,
requestId,
key,
}
: {
type,
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId,
channelId,
requestId,
key,
value: value as PluginSettingValue,
}
);
});
};
return {
pluginId,
channelId,
ready: (readyOptions) =>
post({
type: "plugin.settings.ready",
version: PLUGIN_SETTINGS_FRAME_PROTOCOL_VERSION,
pluginId,
channelId,
requestId: readyOptions?.requestId,
}),
get: (key, requestOptions) => request("plugin.settings.get", key, undefined, requestOptions),
set: (key, value, requestOptions) => request("plugin.settings.set", key, value, requestOptions),
destroy: () => {
frameWindow.removeEventListener("message", onMessage);
for (const [requestId, pendingRequest] of pending) {
if (pendingRequest.timeout) {
clearTimeout(pendingRequest.timeout);
}
pendingRequest.reject(new Error(`Plugin settings client destroyed before response: ${requestId}`));
}
pending.clear();
},
};
}
/**
* Per-invocation context: bound capabilities + invocation metadata.
*/
export interface PluginContext {
pluginId: string;
pluginVersion: string;
tenantId: string;
hookName: string;
capabilities: ReadonlyArray<PluginCapabilityName>;
log: PluginLogger;
audit: PluginAudit;
tenant?: PluginTenantInfo;
http?: PluginHttpClient;
storage?: PluginStorage;
secret?: { get(key: string): Promise<string | null> };
}
/** A hook handler — synchronous or promise-returning. */
export interface HookHandler<Input = unknown, Output = unknown> {
(input: Input, ctx: PluginContext): Output | Promise<Output>;
}
export type TypedHookHandler<Name extends PluginHookName, Output = unknown> = HookHandler<PluginHookPayloads[Name], Output>;
/**
* Helper to brand a function as a typed hook handler — `defineHook`
* exists so authors can rely on inference of `Input` and `Output`
* without restating the type at the call site.
*/
export function defineHook<Input, Output>(handler: HookHandler<Input, Output>): HookHandler<Input, Output> {
return handler;
}