@checkstack/automation-backend 0.2.0

package/src/automation-store.ts

@@ -0,0 +1,227 @@
+/**
+ * Drizzle-backed CRUD for the `automations` table plus the lookups the
+ * dispatch engine needs (find by referenced trigger event, etc.).
+ *
+ * Returns are typed against the public `Automation` shape from
+ * `@checkstack/automation-common`, with parsed `definition`.
+ */
+import { and, eq, sql } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import {
+  AutomationDefinitionSchema,
+  type Automation,
+  type AutomationDefinition,
+  type AutomationStatus,
+  type CreateAutomationInput,
+  type UpdateAutomationInput,
+} from "@checkstack/automation-common";
+
+import { automations } from "./schema";
+import type { LoadedAutomation } from "./dispatch/types";
+
+type Schema = { automations: typeof automations };
+
+export interface AutomationStore {
+  create(input: CreateAutomationInput): Promise<Automation>;
+  update(input: UpdateAutomationInput): Promise<Automation>;
+  delete(id: string): Promise<void>;
+  toggle(id: string, enabled: boolean): Promise<Automation>;
+  getById(id: string): Promise<Automation | undefined>;
+  list(filter?: {
+    status?: AutomationStatus;
+    limit?: number;
+    offset?: number;
+  }): Promise<{ items: Automation[]; total: number }>;
+
+  /**
+   * Enabled automations that reference the given trigger event id in one
+   * of their trigger declarations. Used by the trigger fan-in to fan an
+   * incoming event out to the right automations.
+   */
+  findEnabledByTriggerEvent(eventId: string): Promise<LoadedAutomation[]>;
+
+  /**
+   * All enabled automations — used at boot to set up setup-backed
+   * triggers (cron, interval, …).
+   */
+  listEnabled(): Promise<LoadedAutomation[]>;
+}
+
+function mapToAutomation(
+  row: typeof automations.$inferSelect,
+): Automation {
+  const definition = AutomationDefinitionSchema.parse(row.definition);
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description ?? undefined,
+    status: row.status === "disabled" ? "disabled" : "enabled",
+    definition,
+    managedBy: row.managedBy ?? undefined,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function mapToLoaded(
+  row: typeof automations.$inferSelect,
+): LoadedAutomation {
+  return {
+    id: row.id,
+    name: row.name,
+    status: row.status === "disabled" ? "disabled" : "enabled",
+    definition: AutomationDefinitionSchema.parse(row.definition),
+  };
+}
+
+export function createAutomationStore(
+  db: SafeDatabase<Schema>,
+): AutomationStore {
+  return {
+    async create(input) {
+      const parsedDefinition = AutomationDefinitionSchema.parse(
+        input.definition,
+      );
+      const [row] = await db
+        .insert(automations)
+        .values({
+          name: input.name,
+          description: input.description ?? null,
+          status: input.status,
+          definition: parsedDefinition as unknown as Record<string, unknown>,
+        })
+        .returning();
+      if (!row) throw new Error("create: insert returned no rows");
+      return mapToAutomation(row);
+    },
+
+    async update(input) {
+      const existing = await this.getById(input.id);
+      if (!existing) throw new Error(`Automation ${input.id} not found`);
+
+      const set: Record<string, unknown> = { updatedAt: new Date() };
+      if (input.name !== undefined) set.name = input.name;
+      if (input.description !== undefined)
+        set.description = input.description ?? null;
+      if (input.status !== undefined) set.status = input.status;
+      if (input.definition !== undefined) {
+        const parsed = AutomationDefinitionSchema.parse(input.definition);
+        set.definition = parsed as unknown as Record<string, unknown>;
+      }
+
+      const [row] = await db
+        .update(automations)
+        .set(set)
+        .where(eq(automations.id, input.id))
+        .returning();
+      if (!row) throw new Error(`update: row ${input.id} not found after update`);
+      return mapToAutomation(row);
+    },
+
+    async delete(id) {
+      await db.delete(automations).where(eq(automations.id, id));
+    },
+
+    async toggle(id, enabled) {
+      const status: AutomationStatus = enabled ? "enabled" : "disabled";
+      const [row] = await db
+        .update(automations)
+        .set({ status, updatedAt: new Date() })
+        .where(eq(automations.id, id))
+        .returning();
+      if (!row) throw new Error(`Automation ${id} not found`);
+      return mapToAutomation(row);
+    },
+
+    async getById(id) {
+      const rows = await db
+        .select()
+        .from(automations)
+        .where(eq(automations.id, id))
+        .limit(1);
+      const row = rows[0];
+      return row ? mapToAutomation(row) : undefined;
+    },
+
+    async list(filter = {}) {
+      const limit = filter.limit ?? 50;
+      const offset = filter.offset ?? 0;
+      const whereExpr = filter.status
+        ? eq(automations.status, filter.status)
+        : undefined;
+
+      const rows = whereExpr
+        ? await db
+            .select()
+            .from(automations)
+            .where(whereExpr)
+            .limit(limit)
+            .offset(offset)
+        : await db
+            .select()
+            .from(automations)
+            .limit(limit)
+            .offset(offset);
+
+      const countRows = whereExpr
+        ? await db
+            .select({ c: sql<number>`count(*)::int` })
+            .from(automations)
+            .where(whereExpr)
+        : await db
+            .select({ c: sql<number>`count(*)::int` })
+            .from(automations);
+
+      return {
+        items: rows.map((r) => mapToAutomation(r)),
+        total: countRows[0]?.c ?? 0,
+      };
+    },
+
+    async findEnabledByTriggerEvent(eventId) {
+      // The `definition.triggers` array is queried via JSONB containment.
+      // We can't index the inner JSON cheaply without a generated column;
+      // for v1 we filter in-memory across all enabled rows. Volume is
+      // expected to be in the dozens or low hundreds.
+      const rows = await db
+        .select()
+        .from(automations)
+        .where(eq(automations.status, "enabled"));
+
+      const matching: LoadedAutomation[] = [];
+      for (const row of rows) {
+        const parsed = AutomationDefinitionSchema.safeParse(row.definition);
+        if (!parsed.success) continue;
+        const defn: AutomationDefinition = parsed.data;
+        if (defn.triggers.some((t) => t.event === eventId)) {
+          matching.push({
+            id: row.id,
+            name: row.name,
+            status: "enabled",
+            definition: defn,
+          });
+        }
+      }
+      return matching;
+    },
+
+    async listEnabled() {
+      const rows = await db
+        .select()
+        .from(automations)
+        .where(eq(automations.status, "enabled"));
+      const result: LoadedAutomation[] = [];
+      for (const row of rows) {
+        const parsed = AutomationDefinitionSchema.safeParse(row.definition);
+        if (parsed.success) {
+          result.push(mapToLoaded({ ...row, definition: parsed.data as unknown as Record<string, unknown> }));
+        }
+      }
+      return result;
+    },
+  };
+}
+
+// Silence unused-imports for the second `and` symbol (kept around for the
+// inevitable future "filter by enabled AND something" query).
+void and;

package/src/builtin-actions.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Behaviour tests for the built-in `log` and `notify_user` actions.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import type { Logger, RpcClient } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  createNotifyUserAction,
+  logAction,
+  notifyUserArtifactType,
+  type NotifyUserArtifact,
+} from "./builtin-actions";
+
+const baseLogger = createMockLogger();
+const logger = baseLogger as Logger;
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+describe("automation.log", () => {
+  it("forwards the message to the run logger at the requested level", async () => {
+    const localLogger = createMockLogger();
+    const result = await logAction.execute({
+      ...ctxBase,
+      logger: localLogger as Logger,
+      consumedArtifacts: {},
+      config: { message: "hello", level: "warn" } as never,
+    });
+    expect(result.success).toBe(true);
+    expect(localLogger.warn).toHaveBeenCalledTimes(1);
+    const call = (localLogger.warn as unknown as {
+      mock: { calls: unknown[][] };
+    }).mock.calls[0];
+    expect(call?.[0]).toContain("hello");
+  });
+
+  it("defaults to level=info when not provided (after zod parsing)", async () => {
+    const localLogger = createMockLogger();
+    // The dispatch engine validates config before calling execute,
+    // so the schema's default has already kicked in by the time the
+    // action runs. Simulate that by passing `level: "info"`.
+    const result = await logAction.execute({
+      ...ctxBase,
+      logger: localLogger as Logger,
+      consumedArtifacts: {},
+      config: { message: "hi", level: "info" } as never,
+    });
+    expect(result.success).toBe(true);
+    expect(localLogger.info).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns success without an artifact", async () => {
+    const result = await logAction.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { message: "x", level: "info" } as never,
+    });
+    expect(result.success).toBe(true);
+    expect(result.artifact).toBeUndefined();
+  });
+});
+
+interface SendResult {
+  deliveredCount: number;
+  results: Array<{ strategyId: string; success: boolean; error?: string }>;
+}
+
+function makeRpcClient(
+  behaviour:
+    | { ok: true; result: SendResult }
+    | { ok: false; error: Error },
+): RpcClient & { sendMock: ReturnType<typeof mock> } {
+  const sendMock = mock(async (_input: unknown) => {
+    if (!behaviour.ok) throw behaviour.error;
+    return behaviour.result;
+  });
+  return {
+    forPlugin: () => ({ sendTransactional: sendMock }),
+    sendMock,
+  } as unknown as RpcClient & { sendMock: ReturnType<typeof mock> };
+}
+
+describe("automation.notify_user", () => {
+  it("delegates to sendTransactional and emits a per-strategy artifact", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: {
+        deliveredCount: 1,
+        results: [{ strategyId: "email.smtp", success: true }],
+      },
+    });
+    const action = createNotifyUserAction({ rpcClient });
+    const result = await action.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hello",
+        body: "World",
+      } as never,
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBe("user-1");
+    const artifact = result.artifact as NotifyUserArtifact;
+    expect(artifact.userId).toBe("user-1");
+    expect(artifact.deliveredCount).toBe(1);
+    expect(artifact.results).toHaveLength(1);
+
+    const call = rpcClient.sendMock.mock.calls[0]![0] as {
+      userId: string;
+      notification: { title: string; body: string };
+    };
+    expect(call.userId).toBe("user-1");
+    expect(call.notification.title).toBe("Hello");
+    expect(call.notification.body).toBe("World");
+  });
+
+  it("returns success=false when no strategy delivers but still emits the artifact for audit", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: { deliveredCount: 0, results: [] },
+    });
+    const action = createNotifyUserAction({ rpcClient });
+    const result = await action.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+      } as never,
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.artifact).toBeDefined();
+  });
+
+  it("returns failure when sendTransactional throws", async () => {
+    const rpcClient = makeRpcClient({
+      ok: false,
+      error: new Error("rpc down"),
+    });
+    const action = createNotifyUserAction({ rpcClient });
+    const result = await action.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+      } as never,
+    });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/rpc down/);
+  });
+});
+
+describe("notifyUserArtifactType", () => {
+  it("validates the canonical artifact shape", () => {
+    const ok = notifyUserArtifactType.schema.safeParse({
+      userId: "user-1",
+      deliveredCount: 2,
+      results: [{ strategyId: "email.smtp", success: true }],
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  it("rejects when deliveredCount is missing", () => {
+    const bad = notifyUserArtifactType.schema.safeParse({
+      userId: "user-1",
+      results: [],
+    });
+    expect(bad.success).toBe(false);
+  });
+});

package/src/builtin-actions.ts

@@ -0,0 +1,132 @@
+/**
+ * Built-in actions shipped by automation-backend itself.
+ *
+ * Two actions, intentionally minimal:
+ *
+ *   - `log` — write a single line to the run logger. No artifact, no
+ *     external delivery. The cheapest "I want to see something happened
+ *     here" primitive, useful inside `choose`/`parallel` branches as a
+ *     no-op placeholder until the operator wires the real action.
+ *
+ *   - `notify_user` — send a transactional notification to a specific
+ *     user via the existing service-mode `NotificationApi.sendTransactional`
+ *     RPC. Same delivery path as the integration plugin's
+ *     `notification.send`; this one ships in the core automation
+ *     catalog so an operator gets a built-in "notify a user" action
+ *     even on a minimal install where the notification integration
+ *     plugin hasn't been added.
+ */
+import { z } from "zod";
+import { Versioned, type RpcClient } from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import { NotificationApi } from "@checkstack/notification-common";
+
+import type { ActionDefinition } from "./action-types";
+
+// ─── log ───────────────────────────────────────────────────────────────
+
+const logConfigSchema = z.object({
+  message: z.string().min(1).describe("Message to write to the run log"),
+  level: z
+    .enum(["debug", "info", "warn", "error"])
+    .default("info")
+    .describe("Log level — surfaces with the same severity in the run-detail UI"),
+});
+
+export type LogConfig = z.infer<typeof logConfigSchema>;
+
+export const logAction: ActionDefinition<LogConfig, undefined> = {
+  id: "log",
+  displayName: "Log Message",
+  description: "Write a single line to the automation run's log",
+  category: "Built-in",
+  icon: "FileText",
+  config: new Versioned({ version: 1, schema: logConfigSchema }),
+  execute: async ({ config, logger }) => {
+    logger[config.level](`[automation.log] ${config.message}`);
+    return { success: true };
+  },
+};
+
+// ─── notify_user ───────────────────────────────────────────────────────
+
+const notifyUserConfigSchema = z.object({
+  userId: z.string().min(1).describe("Target user to notify"),
+  title: z.string().min(1).describe("Notification title"),
+  body: z.string().min(1).describe("Notification body (supports markdown)"),
+  importance: z
+    .enum(["info", "warning", "critical"])
+    .optional()
+    .describe("Severity; defaults to 'info'"),
+});
+
+export type NotifyUserConfig = z.infer<typeof notifyUserConfigSchema>;
+
+const notifyUserArtifactSchema = z.object({
+  userId: z.string(),
+  deliveredCount: z.number(),
+  results: z.array(
+    z.object({
+      strategyId: z.string(),
+      success: z.boolean(),
+      error: z.string().optional(),
+    }),
+  ),
+});
+
+export type NotifyUserArtifact = z.infer<typeof notifyUserArtifactSchema>;
+
+export const notifyUserArtifactType = {
+  id: "notify_user_result",
+  displayName: "Notify User Result",
+  description:
+    "Per-strategy outcome from a built-in `notify_user` automation action",
+  schema: notifyUserArtifactSchema,
+} as const;
+
+export interface BuiltinActionDeps {
+  rpcClient: RpcClient;
+}
+
+export function createNotifyUserAction(
+  deps: BuiltinActionDeps,
+): ActionDefinition<NotifyUserConfig, NotifyUserArtifact> {
+  return {
+    id: "notify_user",
+    displayName: "Notify User",
+    description: "Send a transactional notification to a specific user",
+    category: "Built-in",
+    icon: "BellRing",
+    config: new Versioned({ version: 1, schema: notifyUserConfigSchema }),
+    produces: "automation.notify_user_result",
+    execute: async ({ config, logger }) => {
+      const notificationClient = deps.rpcClient.forPlugin(NotificationApi);
+      try {
+        const result = await notificationClient.sendTransactional({
+          userId: config.userId,
+          notification: {
+            title: config.title,
+            body: config.body,
+            importance: config.importance,
+          },
+        });
+        logger.info(
+          `notify_user → ${config.userId} (${result.deliveredCount} delivered)`,
+        );
+        return {
+          success: result.deliveredCount > 0,
+          externalId: config.userId,
+          artifact: {
+            userId: config.userId,
+            deliveredCount: result.deliveredCount,
+            results: result.results,
+          },
+        };
+      } catch (error) {
+        const message = extractErrorMessage(error);
+        logger.error(`notify_user failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+  };
+}