@checkstack/integration-webhook-backend 0.0.35 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @checkstack/integration-webhook-backend
 
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/automation-backend@0.3.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 41c77f4: feat(automation): one-time migration of webhook subscriptions + remove legacy integration backend
+
+  **BREAKING CHANGES** (platform is in BETA — no major bump):
+
+  - `IntegrationProvider` no longer carries `config` (subscription
+    config) or `deliver`. The interface now models a connection provider
+    only: connection schema + `getConnectionOptions` + `testConnection`.
+  - The legacy subscription / delivery-log / event endpoints
+    (`listSubscriptions`, `createSubscription`, `getDeliveryLogs`,
+    `listEventTypes`, …) are removed from `integrationContract`.
+  - `delivery-coordinator`, `hook-subscriber`, `event-registry`, and the
+    `integrationEventExtensionPoint` are deleted. Plugins that
+    previously called `integrationEvents.registerEvent(...)` now
+    register their hooks as automation triggers via
+    `automationTriggerExtensionPoint.registerTrigger(...)`.
+  - Frontend pages `IntegrationsPage` and `DeliveryLogsPage` are gone;
+    the integration plugin's only remaining UI is connection
+    management. Subscription management lives under `/automation/...`.
+  - `webhook_subscriptions` and `delivery_logs` tables stay in the
+    database for one release as a safety net (no code reads or writes
+    them), and will be dropped in a follow-up migration.
+
+  **New**:
+
+  - `jira.create_issue`, `teams.post_message`, `webex.post_message`,
+    `webhook.send`, `integration-script.run_shell`, and
+    `integration-script.run_script` actions registered against the
+    Automation Platform with matching `*.message`, `*.delivery`,
+    `shell.result`, and `script.result` artifact types. The script
+    plugin exposes **two** actions — `run_shell` runs bash via the
+    shared `ShellScriptRunner` (Monaco `shell` editor), `run_script`
+    runs an ESM module in a Bun subprocess via `EsmScriptRunner`
+    (Monaco `typescript` editor + `defineIntegration` helper) — to
+    preserve the legacy provider split. `jira.create_issue` keeps the
+    dynamic field-mapping dropdown (driven by
+    `JIRA_RESOLVERS.FIELD_OPTIONS`).
+  - One-time data migration runs on boot in
+    `automation-backend.afterPluginsReady`. It reads
+    `webhook_subscriptions` via a new service RPC
+    `IntegrationApi.listLegacySubscriptions`, translates each row into
+    a single-trigger / single-action automation (marked with
+    `managed_by = "migrated-subscription:<id>"`), and is idempotent
+    across restarts.
+  - Failed translations are recorded in a new
+    `automation_migration_failures` table and surfaced via
+    `AutomationApi.listMigrationFailures` /
+    `acknowledgeMigrationFailure` so admins can review and re-create
+    failed entries by hand.
+
+- 41c77f4: fix(automation): qualify action `produces` / `consumes` with the owning plugin id
+
+  `context.artifacts` showed up untyped (no fields) in the script editor
+  because action `produces` / `consumes` were hand-written full strings
+  (`"jira.issue"`) that did not match the artifact-type registry's
+  qualified id. The registry derives `${pluginId}.${id}`, and the plugin's
+  id is the package name `integration-jira`, so the artifact type actually
+  registers as `integration-jira.issue` — the editor's schema lookup
+  (`produces` vs registered `qualifiedId`) missed, leaving the artifact's
+  fields unknown. (Runtime store/consume happened to agree with each other
+  on the short string, so it "worked" but typed nothing.)
+
+  The action registry now qualifies `produces` with the owning plugin id,
+  exactly as it already qualifies the action's own `id` and as the
+  artifact-type registry qualifies the artifact type id — so the three can
+  never drift. Actions declare the **local** artifact id:
+
+  - `produces: "issue"` → registered as `integration-jira.issue`,
+  - `consumes: ["issue"]` → resolved against the owning plugin's namespace
+    at run time; `consumedArtifacts` is keyed by the local id, so an
+    action's `execute` reads `consumedArtifacts["issue"]`.
+
+  All five artifact-producing integration plugins (jira / teams / webex /
+  webhook / script) now declare local ids. With `produces` matching the
+  registered artifact type, the editor types `context.artifacts[...]` with
+  the real schema (e.g. `issueKey`, `projectKey`, `issueUrl`).
+
+  **BREAKING (beta):** the fully-qualified artifact type ids change from
+  the short form to the plugin-prefixed form, e.g. `jira.issue` →
+  `integration-jira.issue`. This affects how artifacts are referenced in
+  templates (`{{ artifact.integration-jira.issue.issueKey }}`), the TS
+  script `context.artifacts["integration-jira.issue"]`, and shell env names
+  (`$CHECKSTACK_ARTIFACT_INTEGRATION_JIRA_ISSUE_ISSUEKEY`). Artifacts are
+  per-run and ephemeral, so no stored-data migration is needed.
+
+  Note: this keeps the same-plugin produce→consume handoff (the current
+  pattern). Cross-plugin artifact consumption would need a follow-up to
+  allow a fully-qualified `consumes` ref.
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+
 ## 0.0.35
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/integration-webhook-backend",
-  "version": "0.0.35",
+  "version": "0.1.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -11,20 +11,21 @@
     "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test",
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.17.0",
-    "@checkstack/integration-backend": "0.1.29",
-    "@checkstack/integration-common": "0.5.0",
-    "@checkstack/common": "0.11.0",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/automation-backend": "0.2.0",
+    "@checkstack/common": "0.12.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/test-utils-backend": "0.1.31"
   },
   "description": "Checkstack integration-webhook-backend plugin",
   "author": {

package/src/automations.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Behaviour tests for the webhook automation action.
+ *
+ * fetch is stubbed in-process so we can exercise the full
+ * `webhookSendAction.execute` flow including the retry/error mapping.
+ * Template expansion happens at the dispatch-engine level — by the
+ * time this action runs, `config.body` is already a rendered string,
+ * so we don't need to set up a template runtime here.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import { webhookSendAction, webhookDeliveryArtifactType } from "./automations";
+
+const logger = createMockLogger() as Logger;
+
+interface CapturedFetchCall {
+  url: string;
+  init: RequestInit;
+}
+
+interface StagedResponse {
+  body?: unknown;
+  status?: number;
+  headers?: Record<string, string>;
+  raw?: string;
+  /** Throw this error instead of returning a response. */
+  throws?: Error;
+}
+
+function setupFetchSequence(responses: StagedResponse[]) {
+  const calls: CapturedFetchCall[] = [];
+  const originalFetch = globalThis.fetch;
+  let i = 0;
+  globalThis.fetch = (async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ) => {
+    calls.push({ url: String(input), init: init ?? {} });
+    const next = responses[i++] ?? { body: {}, status: 200 };
+    if (next.throws) throw next.throws;
+    const headers = new Headers({ "Content-Type": "application/json", ...next.headers });
+    const payload =
+      next.raw !== undefined ? next.raw : JSON.stringify(next.body ?? {});
+    return new Response(payload, {
+      status: next.status ?? 200,
+      headers,
+    });
+  }) as typeof fetch;
+  return {
+    calls,
+    restore: () => {
+      globalThis.fetch = originalFetch;
+    },
+  };
+}
+
+let fetchFixture: ReturnType<typeof setupFetchSequence> | undefined;
+
+beforeEach(() => {
+  fetchFixture?.restore();
+  fetchFixture = undefined;
+});
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+const baseConfig = {
+  url: "https://example.com/hook",
+  method: "POST" as const,
+  contentType: "application/json" as const,
+  authType: "none" as const,
+  timeout: 10_000,
+};
+
+describe("webhookDeliveryArtifactType", () => {
+  it("validates the canonical artifact shape", () => {
+    const ok = webhookDeliveryArtifactType.schema.safeParse({
+      url: "https://example.com/hook",
+      status: 200,
+      responseBody: "{}",
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  it("rejects when status is missing", () => {
+    const bad = webhookDeliveryArtifactType.schema.safeParse({
+      url: "https://example.com/hook",
+      responseBody: "{}",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+describe("webhook.send", () => {
+  it("delivers a payload and emits a webhook.delivery artifact", async () => {
+    fetchFixture = setupFetchSequence([
+      { body: { id: "msg-42" }, status: 201 },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig, body: '{"x":1}' },
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as {
+      url: string;
+      status: number;
+      externalId?: string;
+      responseBody: string;
+    };
+    expect(artifact.url).toBe("https://example.com/hook");
+    expect(artifact.status).toBe(201);
+    expect(artifact.externalId).toBe("msg-42");
+    expect(result.externalId).toBe("msg-42");
+    const call = fetchFixture.calls[0]!;
+    expect(call.init.method).toBe("POST");
+    expect(call.init.body).toBe('{"x":1}');
+    const headers = call.init.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+  });
+
+  it("attaches a bearer token to the Authorization header", async () => {
+    fetchFixture = setupFetchSequence([{ body: {} }]);
+    await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        ...baseConfig,
+        authType: "bearer",
+        bearerToken: "secret-token",
+      },
+    });
+    const headers = fetchFixture.calls[0]!.init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer secret-token");
+  });
+
+  it("attaches Basic auth when username and password are set", async () => {
+    fetchFixture = setupFetchSequence([{ body: {} }]);
+    await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        ...baseConfig,
+        authType: "basic",
+        basicUsername: "alice",
+        basicPassword: "wonderland",
+      },
+    });
+    const headers = fetchFixture.calls[0]!.init.headers as Record<string, string>;
+    const expected = `Basic ${Buffer.from("alice:wonderland").toString("base64")}`;
+    expect(headers.Authorization).toBe(expected);
+  });
+
+  it("attaches a custom header when authType is header", async () => {
+    fetchFixture = setupFetchSequence([{ body: {} }]);
+    await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        ...baseConfig,
+        authType: "header",
+        authHeaderName: "X-API-Key",
+        authHeaderValue: "k123",
+      },
+    });
+    const headers = fetchFixture.calls[0]!.init.headers as Record<string, string>;
+    expect(headers["X-API-Key"]).toBe("k123");
+  });
+
+  it("appends extra custom headers", async () => {
+    fetchFixture = setupFetchSequence([{ body: {} }]);
+    await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        ...baseConfig,
+        customHeaders: [
+          { name: "X-Source", value: "checkstack" },
+          { name: "X-Trace", value: "abc" },
+        ],
+      },
+    });
+    const headers = fetchFixture.calls[0]!.init.headers as Record<string, string>;
+    expect(headers["X-Source"]).toBe("checkstack");
+    expect(headers["X-Trace"]).toBe("abc");
+  });
+
+  it("returns a retryable failure when the status matches retryOnStatus", async () => {
+    fetchFixture = setupFetchSequence([
+      { status: 429, raw: "rate limited", headers: { "Retry-After": "5" } },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig, retryOnStatus: [429, 503] },
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.retryAfterMs).toBe(5_000);
+    expect(result.error).toMatch(/429/);
+  });
+
+  it("defaults retryAfterMs to 30s when Retry-After is missing", async () => {
+    fetchFixture = setupFetchSequence([
+      { status: 503, raw: "unavailable" },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig, retryOnStatus: [503] },
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.retryAfterMs).toBe(30_000);
+  });
+
+  it("returns a non-retryable failure for an unmatched 4xx/5xx", async () => {
+    fetchFixture = setupFetchSequence([
+      { status: 500, raw: "boom" },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig },
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/HTTP 500/);
+    expect(result.retryAfterMs).toBeUndefined();
+  });
+
+  it("classifies network errors as retryable", async () => {
+    fetchFixture = setupFetchSequence([
+      { throws: new Error("ECONNREFUSED 127.0.0.1") },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig },
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.retryAfterMs).toBe(30_000);
+  });
+
+  it("does not retry generic non-network errors", async () => {
+    fetchFixture = setupFetchSequence([
+      { throws: new Error("something else broke") },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig },
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.retryAfterMs).toBeUndefined();
+  });
+
+  it("returns success without externalId when the response body is not JSON", async () => {
+    fetchFixture = setupFetchSequence([
+      { status: 200, raw: "ok" },
+    ]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig },
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBeUndefined();
+    const artifact = result.artifact as { responseBody: string };
+    expect(artifact.responseBody).toBe("ok");
+  });
+
+  it("truncates the captured response body to 1000 chars", async () => {
+    const big = "x".repeat(5_000);
+    fetchFixture = setupFetchSequence([{ status: 200, raw: big }]);
+    const result = await webhookSendAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { ...baseConfig },
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as { responseBody: string };
+    expect(artifact.responseBody.length).toBe(1_000);
+  });
+});

package/src/automations.ts

@@ -0,0 +1,193 @@
+/**
+ * Webhook action — generic HTTP POST/PUT/PATCH to an external endpoint.
+ *
+ * Replaces the legacy `webhookProvider.deliver` path. All template
+ * expansion now happens in the dispatch engine before `execute` is
+ * called, so this action just builds the request and fires it.
+ */
+import { z } from "zod";
+import {
+  configNumber,
+  configString,
+  requestTimeoutMs,
+  Versioned,
+} from "@checkstack/backend-api";
+import type { ActionDefinition } from "@checkstack/automation-backend";
+import { extractErrorMessage } from "@checkstack/common";
+
+const webhookHeaderSchema = z.object({
+  name: z.string().min(1).describe("Header name"),
+  value: z.string().describe("Header value"),
+});
+
+export const webhookSendConfigSchema = z.object({
+  url: configString({}).url().describe("Endpoint URL"),
+  method: z
+    .enum(["POST", "PUT", "PATCH"])
+    .default("POST")
+    .describe("HTTP method"),
+  contentType: z
+    .enum(["application/json", "application/x-www-form-urlencoded"])
+    .default("application/json"),
+  authType: z
+    .enum(["none", "bearer", "basic", "header"])
+    .default("none")
+    .describe("Authentication method"),
+  bearerToken: configString({ "x-secret": true })
+    .optional()
+    .describe("Bearer token"),
+  basicUsername: configString({}).optional(),
+  basicPassword: configString({ "x-secret": true }).optional(),
+  authHeaderName: configString({}).optional(),
+  authHeaderValue: configString({ "x-secret": true }).optional(),
+  customHeaders: z.array(webhookHeaderSchema).optional(),
+  body: configString({
+    "x-editor-types": ["raw", "json", "yaml", "xml", "formdata"],
+  })
+    .optional()
+    .describe("Request body — already rendered when this action runs"),
+  timeout: requestTimeoutMs().describe("Request timeout in milliseconds"),
+  retryOnStatus: z
+    .array(configNumber({}))
+    .optional()
+    .describe("Retryable HTTP status codes (e.g., 429, 503)"),
+});
+
+export type WebhookSendConfig = z.infer<typeof webhookSendConfigSchema>;
+
+interface WebhookDeliveryArtifact {
+  url: string;
+  status: number;
+  externalId?: string;
+  responseBody: string;
+}
+
+export const webhookSendAction: ActionDefinition<
+  WebhookSendConfig,
+  WebhookDeliveryArtifact
+> = {
+  id: "send",
+  displayName: "Send Webhook",
+  description: "Deliver a payload to an HTTP endpoint",
+  category: "Webhook",
+  icon: "Webhook",
+  config: new Versioned({
+    version: 1,
+    schema: webhookSendConfigSchema,
+  }),
+  produces: "delivery",
+  execute: async ({ config, logger }) => {
+    const headers: Record<string, string> = {
+      "Content-Type": config.contentType,
+      "User-Agent": "Checkstack-Automation/1.0",
+    };
+
+    switch (config.authType) {
+      case "bearer": {
+        if (config.bearerToken) {
+          headers.Authorization = `Bearer ${config.bearerToken}`;
+        }
+        break;
+      }
+      case "basic": {
+        if (config.basicUsername && config.basicPassword) {
+          const credentials = Buffer.from(
+            `${config.basicUsername}:${config.basicPassword}`,
+          ).toString("base64");
+          headers.Authorization = `Basic ${credentials}`;
+        }
+        break;
+      }
+      case "header": {
+        if (config.authHeaderName && config.authHeaderValue) {
+          headers[config.authHeaderName] = config.authHeaderValue;
+        }
+        break;
+      }
+    }
+
+    if (config.customHeaders) {
+      for (const header of config.customHeaders) {
+        headers[header.name] = header.value;
+      }
+    }
+
+    const body = config.body ?? "";
+
+    try {
+      const response = await fetch(config.url, {
+        method: config.method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(config.timeout),
+      });
+
+      const responseText = await response.text();
+
+      if (config.retryOnStatus?.includes(response.status)) {
+        const retryAfter = response.headers.get("Retry-After");
+        const retryAfterMs = retryAfter
+          ? Number.parseInt(retryAfter, 10) * 1000
+          : 30_000;
+        return {
+          success: false,
+          error: `Received status ${response.status} (retryable)`,
+          retryAfterMs,
+        };
+      }
+
+      if (!response.ok) {
+        return {
+          success: false,
+          error: `HTTP ${response.status}: ${responseText.slice(0, 200)}`,
+        };
+      }
+
+      let externalId: string | undefined;
+      try {
+        const json = JSON.parse(responseText) as Record<string, unknown>;
+        const candidate = json.id ?? json.externalId ?? json.messageId;
+        if (typeof candidate === "string") externalId = candidate;
+      } catch {
+        // Not JSON — that's fine, no externalId.
+      }
+
+      logger.debug(
+        `Webhook delivered to ${config.url}: ${response.status}`,
+      );
+      return {
+        success: true,
+        externalId,
+        artifact: {
+          url: config.url,
+          status: response.status,
+          externalId,
+          responseBody: responseText.slice(0, 1000),
+        },
+      };
+    } catch (error) {
+      const message = extractErrorMessage(error);
+      logger.error(`Webhook delivery failed: ${message}`);
+      if (
+        message.includes("timeout") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ENOTFOUND")
+      ) {
+        return { success: false, error: message, retryAfterMs: 30_000 };
+      }
+      return { success: false, error: message };
+    }
+  },
+};
+
+export const webhookDeliveryArtifactType = {
+  id: "delivery",
+  displayName: "Webhook Delivery",
+  description: "Result of an HTTP delivery attempt",
+  schema: z.object({
+    url: z.string(),
+    status: z.number(),
+    externalId: z.string().optional(),
+    responseBody: z.string(),
+  }),
+} as const;