Reorganize repo structure and standards references
This commit is contained in:
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 });
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user