@decocms/runtime 1.2.15 → 1.3.1

package/src/triggers.test.ts

@@ -0,0 +1,411 @@
+import { describe, expect, it, spyOn } from "bun:test";
+import { z } from "zod";
+import { createTriggers, type TriggerStorage } from "./triggers.ts";
+
+// biome-ignore lint: test mocks don't need full type compliance
+const mockCtx = (connectionId?: string) =>
+  ({
+    env: connectionId
+      ? { MESH_REQUEST_CONTEXT: { connectionId } }
+      : { MESH_REQUEST_CONTEXT: {} },
+    ctx: { waitUntil: () => {} },
+  }) as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+const triggers = createTriggers([
+  {
+    type: "github.push",
+    description: "Triggered when code is pushed",
+    params: z.object({
+      repo: z.string().describe("Repository full name (owner/repo)"),
+    }),
+  },
+  {
+    type: "github.pull_request.opened",
+    description: "Triggered when a PR is opened",
+    params: z.object({
+      repo: z.string().describe("Repository full name"),
+    }),
+  },
+]);
+
+describe("createTriggers", () => {
+  it("tools() returns TRIGGER_LIST and TRIGGER_CONFIGURE", () => {
+    const tools = triggers.tools();
+    expect(tools).toHaveLength(2);
+    expect(tools[0].id).toBe("TRIGGER_LIST");
+    expect(tools[1].id).toBe("TRIGGER_CONFIGURE");
+  });
+
+  it("TRIGGER_LIST returns trigger definitions with paramsSchema", async () => {
+    const listTool = triggers.tools()[0];
+    const result = (await listTool.execute({
+      context: {},
+      runtimeContext: mockCtx(),
+    })) as {
+      triggers: Array<{ type: string; paramsSchema: Record<string, unknown> }>;
+    };
+
+    expect(result.triggers).toHaveLength(2);
+    expect(result.triggers[0].type).toBe("github.push");
+    expect(result.triggers[0].paramsSchema).toEqual({
+      repo: {
+        type: "string",
+        description: "Repository full name (owner/repo)",
+      },
+    });
+    expect(result.triggers[1].type).toBe("github.pull_request.opened");
+  });
+
+  it("TRIGGER_LIST includes enum values from z.enum params", async () => {
+    const enumTriggers = createTriggers([
+      {
+        type: "test.event",
+        description: "Test",
+        params: z.object({
+          action: z.enum(["opened", "closed", "merged"]).describe("PR action"),
+        }),
+      },
+    ]);
+    const listTool = enumTriggers.tools()[0];
+    const result = (await listTool.execute({
+      context: {},
+      runtimeContext: mockCtx(),
+    })) as {
+      triggers: Array<{ paramsSchema: Record<string, { enum?: string[] }> }>;
+    };
+    expect(result.triggers[0].paramsSchema.action.enum).toEqual([
+      "opened",
+      "closed",
+      "merged",
+    ]);
+  });
+
+  it("TRIGGER_CONFIGURE stores callback credentials and notify delivers", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const mockResponse = new Response("ok", { status: 202 });
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(mockResponse);
+
+    // Configure a trigger with callback
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: { repo: "owner/repo" },
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "test-token-123",
+      },
+      runtimeContext: mockCtx("conn-1"),
+    });
+
+    // Notify should POST to the callback URL
+    triggers.notify("conn-1", "github.push", {
+      repository: { full_name: "owner/repo" },
+    });
+
+    // Wait for the fire-and-forget fetch
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://mesh.example.com/api/trigger-callback",
+      expect.objectContaining({
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer test-token-123",
+        },
+      }),
+    );
+
+    const callBody = JSON.parse(
+      (fetchSpy.mock.calls[0][1] as RequestInit).body as string,
+    );
+    expect(callBody.type).toBe("github.push");
+    expect(callBody.data.repository.full_name).toBe("owner/repo");
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disabling one trigger keeps credentials when another is still active", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+
+    // Enable two trigger types
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-multi",
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+    await configureTool.execute({
+      context: {
+        type: "github.pull_request.opened",
+        params: {},
+        enabled: true,
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+
+    // Disable one — credentials should stay for the other
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: false,
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+
+    triggers.notify("conn-multi", "github.pull_request.opened", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchSpy).toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disabling the last trigger clears credentials", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+
+    // Enable a trigger
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-cleanup",
+      },
+      runtimeContext: mockCtx("conn-cleanup"),
+    });
+
+    // Disable it — last trigger, credentials should be cleared
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: false,
+      },
+      runtimeContext: mockCtx("conn-cleanup"),
+    });
+
+    triggers.notify("conn-cleanup", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+
+    fetchSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+
+  it("notify is a no-op when no credentials exist", async () => {
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    triggers.notify("unknown-conn", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it("notify logs error on non-2xx response", async () => {
+    const configureTool = triggers.tools()[1];
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    // Ensure credentials exist (reuse from prior test state or set up fresh)
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-err",
+      },
+      runtimeContext: mockCtx("conn-err"),
+    });
+
+    fetchSpy.mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+
+    triggers.notify("conn-err", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Callback delivery failed"),
+    );
+
+    fetchSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("TRIGGER_CONFIGURE throws without connectionId", async () => {
+    const configureTool = triggers.tools()[1];
+    expect(
+      configureTool.execute({
+        context: { type: "github.push", params: {}, enabled: true },
+        runtimeContext: mockCtx(),
+      }),
+    ).rejects.toThrow("Connection ID not available");
+  });
+});
+
+describe("createTriggers with storage", () => {
+  function createMockStorage(): TriggerStorage & {
+    data: Map<string, unknown>;
+  } {
+    const data = new Map<string, unknown>();
+    return {
+      data,
+      get: async (id) => (data.get(id) as any) ?? null,
+      set: async (id, state) => {
+        data.set(id, state);
+      },
+      delete: async (id) => {
+        data.delete(id);
+      },
+    };
+  }
+
+  const defs = [
+    {
+      type: "github.push" as const,
+      description: "Push",
+      params: z.object({
+        repo: z.string().describe("Repo"),
+      }),
+    },
+  ];
+
+  it("persists trigger state to storage on configure", async () => {
+    const storage = createMockStorage();
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "persisted-token",
+      },
+      runtimeContext: mockCtx("conn-persist"),
+    });
+
+    expect(storage.data.has("conn-persist")).toBe(true);
+    const stored = storage.data.get("conn-persist") as any;
+    expect(stored.credentials.callbackToken).toBe("persisted-token");
+    expect(stored.activeTriggerTypes).toEqual(["github.push"]);
+  });
+
+  it("deletes from storage when last trigger is disabled", async () => {
+    const storage = createMockStorage();
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "to-delete",
+      },
+      runtimeContext: mockCtx("conn-del"),
+    });
+
+    expect(storage.data.has("conn-del")).toBe(true);
+
+    await configureTool.execute({
+      context: { type: "github.push", params: {}, enabled: false },
+      runtimeContext: mockCtx("conn-del"),
+    });
+
+    expect(storage.data.has("conn-del")).toBe(false);
+  });
+
+  it("restores credentials from storage on notify after restart", async () => {
+    const storage = createMockStorage();
+
+    // Simulate prior session: write state directly to storage
+    storage.data.set("conn-restart", {
+      credentials: {
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "restored-token",
+      },
+      activeTriggerTypes: ["github.push"],
+    });
+
+    // New instance (simulates restart) — in-memory cache is empty
+    const t = createTriggers({ definitions: defs, storage });
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+
+    t.notify("conn-restart", "github.push", { test: true });
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://mesh.example.com/api/trigger-callback",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "Bearer restored-token",
+        }),
+      }),
+    );
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disable after restart clears persisted credentials from storage", async () => {
+    const storage = createMockStorage();
+
+    // Simulate prior session
+    storage.data.set("conn-disable-restart", {
+      credentials: {
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "stale-token",
+      },
+      activeTriggerTypes: ["github.push"],
+    });
+
+    // New instance (simulates restart)
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    // Disable the trigger — should load from storage, then clean up
+    await configureTool.execute({
+      context: { type: "github.push", params: {}, enabled: false },
+      runtimeContext: mockCtx("conn-disable-restart"),
+    });
+
+    expect(storage.data.has("conn-disable-restart")).toBe(false);
+
+    // notify should be a no-op
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    t.notify("conn-disable-restart", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+    consoleSpy.mockRestore();
+  });
+});

package/src/triggers.ts

@@ -0,0 +1,307 @@
+import {
+  TriggerConfigureInputSchema,
+  TriggerListOutputSchema,
+  type TriggerDefinition,
+} from "@decocms/bindings/trigger";
+import { z, type ZodObject, type ZodRawShape } from "zod";
+import type { DefaultEnv } from "./index.ts";
+import { createTool, type CreatedTool } from "./tools.ts";
+
+interface CallbackCredentials {
+  callbackUrl: string;
+  callbackToken: string;
+}
+
+interface TriggerState {
+  credentials: CallbackCredentials;
+  activeTriggerTypes: string[];
+}
+
+/**
+ * Storage interface for persisting trigger state across MCP restarts.
+ *
+ * Implement this with your storage backend (KV, DB, file system, etc.)
+ * and pass it to `createTriggers({ storage })`.
+ *
+ * Keys are connection IDs, values are serializable trigger state objects.
+ */
+export interface TriggerStorage {
+  get(connectionId: string): Promise<TriggerState | null>;
+  set(connectionId: string, state: TriggerState): Promise<void>;
+  delete(connectionId: string): Promise<void>;
+}
+
+interface TriggerDef<
+  TType extends string = string,
+  TParams extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>,
+> {
+  type: TType;
+  description: string;
+  params: TParams;
+}
+
+interface TriggersOptions<TDefs extends TriggerDef[]> {
+  definitions: TDefs;
+  storage?: TriggerStorage;
+}
+
+interface Triggers<TDefs extends TriggerDef[]> {
+  /**
+   * Returns TRIGGER_LIST and TRIGGER_CONFIGURE tools
+   * ready to be spread into your `withRuntime({ tools })` array.
+   */
+  tools(): CreatedTool[];
+
+  /**
+   * Notify Mesh that an event occurred.
+   * The SDK matches it to stored callback credentials and POSTs to Mesh.
+   * Fire-and-forget — errors are logged, not thrown.
+   */
+  notify<T extends TDefs[number]["type"]>(
+    connectionId: string,
+    type: T,
+    data: Record<string, unknown>,
+  ): void;
+}
+
+// In-memory cache backed by optional persistent storage
+class TriggerStateManager {
+  private credentials = new Map<string, CallbackCredentials>();
+  private activeTriggers = new Map<string, Set<string>>();
+  private storage: TriggerStorage | null;
+
+  constructor(storage?: TriggerStorage) {
+    this.storage = storage ?? null;
+  }
+
+  getCredentials(connectionId: string): CallbackCredentials | undefined {
+    return this.credentials.get(connectionId);
+  }
+
+  async loadFromStorage(connectionId: string): Promise<void> {
+    if (!this.storage || this.credentials.has(connectionId)) return;
+    const state = await this.storage.get(connectionId);
+    if (state) {
+      this.credentials.set(connectionId, state.credentials);
+      this.activeTriggers.set(connectionId, new Set(state.activeTriggerTypes));
+    }
+  }
+
+  async enable(
+    connectionId: string,
+    triggerType: string,
+    newCredentials?: CallbackCredentials,
+  ): Promise<void> {
+    if (newCredentials) {
+      this.credentials.set(connectionId, newCredentials);
+    }
+
+    const types = this.activeTriggers.get(connectionId) ?? new Set();
+    types.add(triggerType);
+    this.activeTriggers.set(connectionId, types);
+
+    await this.persist(connectionId);
+  }
+
+  async disable(connectionId: string, triggerType: string): Promise<void> {
+    // Ensure state is loaded (may be empty after restart)
+    await this.loadFromStorage(connectionId);
+    const types = this.activeTriggers.get(connectionId);
+    if (types) {
+      types.delete(triggerType);
+      if (types.size === 0) {
+        this.activeTriggers.delete(connectionId);
+        this.credentials.delete(connectionId);
+        await this.storage?.delete(connectionId);
+        return;
+      }
+    }
+
+    await this.persist(connectionId);
+  }
+
+  private async persist(connectionId: string): Promise<void> {
+    if (!this.storage) return;
+    const creds = this.credentials.get(connectionId);
+    const types = this.activeTriggers.get(connectionId);
+    if (!creds || !types || types.size === 0) return;
+    await this.storage.set(connectionId, {
+      credentials: creds,
+      activeTriggerTypes: [...types],
+    });
+  }
+}
+
+/**
+ * Create a trigger SDK for your MCP.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { z } from "zod";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [
+ *     {
+ *       type: "github.push",
+ *       description: "Triggered when code is pushed to a repository",
+ *       params: z.object({
+ *         repo: z.string().describe("Repository full name (owner/repo)"),
+ *       }),
+ *     },
+ *   ],
+ *   // Optional: persist trigger state across restarts
+ *   storage: myKVStorage,
+ * });
+ *
+ * // In withRuntime:
+ * export default withRuntime({
+ *   tools: [() => triggers.tools()],
+ * });
+ *
+ * // In webhook handler:
+ * triggers.notify(connectionId, "github.push", payload);
+ * ```
+ */
+export function createTriggers<const TDefs extends TriggerDef[]>(
+  input: TDefs | TriggersOptions<TDefs>,
+): Triggers<TDefs> {
+  const { definitions, storage } = Array.isArray(input)
+    ? { definitions: input as TDefs, storage: undefined }
+    : input;
+
+  const state = new TriggerStateManager(storage);
+
+  const triggerDefinitions: TriggerDefinition[] = definitions.map((def) => {
+    const shape = def.params.shape;
+    const paramsSchema: Record<
+      string,
+      { type: "string"; description?: string; enum?: string[] }
+    > = {};
+
+    for (const [key, value] of Object.entries(shape)) {
+      const zodField = value as z.ZodTypeAny;
+      const entry: {
+        type: "string";
+        description?: string;
+        enum?: string[];
+      } = {
+        type: "string" as const,
+        description: zodField.description,
+      };
+
+      // Extract enum values from z.enum() schemas
+      if ("options" in zodField && Array.isArray(zodField.options)) {
+        entry.enum = zodField.options as string[];
+      }
+
+      paramsSchema[key] = entry;
+    }
+
+    return {
+      type: def.type,
+      description: def.description,
+      paramsSchema,
+    };
+  });
+
+  const TRIGGER_LIST = createTool({
+    id: "TRIGGER_LIST" as const,
+    description: "List available trigger definitions",
+    inputSchema: z.object({}),
+    outputSchema: TriggerListOutputSchema,
+    execute: async () => {
+      return { triggers: triggerDefinitions };
+    },
+  });
+
+  const TRIGGER_CONFIGURE = createTool({
+    id: "TRIGGER_CONFIGURE" as const,
+    description: "Configure a trigger with parameters",
+    inputSchema: TriggerConfigureInputSchema,
+    outputSchema: z.object({ success: z.boolean() }),
+    execute: async ({ context, runtimeContext }) => {
+      const connectionId = (runtimeContext?.env as unknown as DefaultEnv)
+        ?.MESH_REQUEST_CONTEXT?.connectionId;
+
+      if (!connectionId) {
+        throw new Error("Connection ID not available");
+      }
+
+      if (context.enabled) {
+        const creds =
+          context.callbackUrl && context.callbackToken
+            ? {
+                callbackUrl: context.callbackUrl,
+                callbackToken: context.callbackToken,
+              }
+            : undefined;
+        await state.enable(connectionId, context.type, creds);
+      } else {
+        await state.disable(connectionId, context.type);
+      }
+
+      return { success: true };
+    },
+  });
+
+  return {
+    tools() {
+      return [TRIGGER_LIST, TRIGGER_CONFIGURE] as CreatedTool[];
+    },
+
+    notify(connectionId, type, data) {
+      // Try in-memory first, fall back to storage load
+      const credentials = state.getCredentials(connectionId);
+      if (credentials) {
+        deliverCallback(credentials, type, data);
+        return;
+      }
+
+      // Attempt async load from storage (fire-and-forget)
+      state
+        .loadFromStorage(connectionId)
+        .then(() => {
+          const loaded = state.getCredentials(connectionId);
+          if (loaded) {
+            deliverCallback(loaded, type, data);
+          } else {
+            console.log(
+              `[Triggers] No callback credentials for connection=${connectionId}, skipping notify`,
+            );
+          }
+        })
+        .catch((err) => {
+          console.error(
+            `[Triggers] Failed to load credentials for ${connectionId}:`,
+            err,
+          );
+        });
+    },
+  };
+}
+
+function deliverCallback(
+  credentials: CallbackCredentials,
+  type: string,
+  data: Record<string, unknown>,
+): void {
+  fetch(credentials.callbackUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${credentials.callbackToken}`,
+    },
+    body: JSON.stringify({ type, data }),
+  })
+    .then((res) => {
+      if (!res.ok) {
+        console.error(
+          `[Triggers] Callback delivery failed for ${type}: ${res.status} ${res.statusText}`,
+        );
+      }
+    })
+    .catch((err) => {
+      console.error(`[Triggers] Failed to deliver callback for ${type}:`, err);
+    });
+}