@sapporta/server 0.0.1

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sapporta/server",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Jasim A Basheer <jasim@nuabase.com>",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src/", "package.json"],
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": "./src/index.ts",
+    "./table": "./src/schema/table.ts",
+    "./report": "./src/reports/report.ts",
+    "./action": "./src/actions/action.ts",
+    "./errors": "./src/db/errors.ts",
+    "./view": "./src/views/view.ts",
+    "./boot": "./src/boot.ts",
+    "./runtime": "./src/runtime.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.1",
+    "better-sqlite3": "^11.x",
+    "commander": "^14.0.3",
+    "drizzle-orm": "^0.38.4",
+    "hono": "^4.7.4",
+    "nuabase": "^2.3.0",
+    "winston": "^3.17.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.x",
+    "drizzle-kit": "^0.31.9",
+    "typescript": "^5.7.3"
+  }
+}

package/src/actions/action.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Hono } from "hono";
+import { z } from "zod";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { action } from "./action.js";
+import { actionApi } from "../api/actions.js";
+import { createTestDb } from "../testing/test-utils.js";
+import { table } from "../schema/table.js";
+
+const itemsTable = sqliteTable("items", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+});
+
+const items = table({ drizzle: itemsTable });
+
+describe("Actions system", () => {
+  let app: Hono;
+
+  beforeEach(async () => {
+    const { db, sqlite } = createTestDb();
+    sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL
+      )
+    `);
+
+    const createItem = action({
+      name: "create_item",
+      input: z.object({ name: z.string().min(1) }),
+      // SQLite transactions are synchronous — run() must NOT be async.
+      // Drizzle's better-sqlite3 operations return values directly.
+      run: ({ input, db: txDb }) => {
+        const result = txDb
+          .insert(items.drizzle)
+          .values({ name: input.name })
+          .returning()
+          .all();
+        return result[0];
+      },
+    });
+
+    app = new Hono();
+    app.route("/actions", actionApi([createItem], db as any));
+  });
+
+  it("POST /actions/:name executes the action", async () => {
+    const res = await app.request("/actions/create_item", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Widget" }),
+    });
+
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data.name).toBe("Widget");
+    expect(json.data.id).toBeDefined();
+  });
+
+  it("validates input", async () => {
+    const res = await app.request("/actions/create_item", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "" }),
+    });
+
+    expect(res.status).toBe(422);
+    const json = await res.json();
+    expect(json.error).toBe("Validation failed");
+  });
+
+  it("validates missing fields", async () => {
+    const res = await app.request("/actions/create_item", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+
+    expect(res.status).toBe(422);
+  });
+});
+
+describe("action() definition", () => {
+  it("creates an ActionInstance", () => {
+    const act = action({
+      name: "test_action",
+      input: z.object({ value: z.number() }),
+      run: ({ input }) => input.value * 2,
+    });
+
+    expect(act.name).toBe("test_action");
+    expect(typeof act.run).toBe("function");
+  });
+
+  it("supports afterCommit callbacks", () => {
+    const callbacks: string[] = [];
+
+    const act = action({
+      name: "with_callback",
+      input: z.object({}),
+      run: () => "done",
+      afterCommit: [(result) => { callbacks.push(result as string); }],
+    });
+
+    expect(act.afterCommit).toHaveLength(1);
+  });
+});

package/src/actions/action.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+
+export interface ActionConfig<TInput extends z.ZodTypeAny, TOutput> {
+  /** Action name — used as the URL path */
+  name: string;
+  /** Human-readable label (used in UI) */
+  label?: string;
+  /** Zod schema for input validation */
+  input: TInput;
+  /**
+   * The action handler — receives validated input and a db transaction.
+   *
+   * Runs inside a SQLite transaction (synchronous). The handler MUST be
+   * synchronous — better-sqlite3 transactions reject async callbacks.
+   * Drizzle's SQLite operations return values directly (no await needed).
+   */
+  run: (ctx: {
+    input: z.infer<TInput>;
+    db: BetterSQLite3Database;
+  }) => TOutput;
+  /** Callbacks to run after the transaction commits */
+  afterCommit?: ((result: TOutput) => void | Promise<void>)[];
+}
+
+export interface ActionInstance<TInput extends z.ZodTypeAny, TOutput> {
+  name: string;
+  label?: string;
+  input: TInput;
+  run: ActionConfig<TInput, TOutput>["run"];
+  afterCommit?: ActionConfig<TInput, TOutput>["afterCommit"];
+}
+
+/**
+ * Define an action. Actions are transactional operations exposed as API endpoints.
+ *
+ * Usage:
+ * ```ts
+ * export default action({
+ *   name: "create_account",
+ *   input: z.object({ name: z.string(), type: z.string() }),
+ *   run: ({ input, db }) => {
+ *     // Drizzle SQLite operations are synchronous — no await needed.
+ *     const result = db.insert(accounts).values(input).returning().all();
+ *     return result[0];
+ *   },
+ * });
+ * ```
+ */
+export function action<TInput extends z.ZodTypeAny, TOutput>(
+  config: ActionConfig<TInput, TOutput>,
+): ActionInstance<TInput, TOutput> {
+  return {
+    name: config.name,
+    label: config.label,
+    input: config.input,
+    run: config.run,
+    afterCommit: config.afterCommit,
+  };
+}

package/src/actions/loader.ts

@@ -0,0 +1,47 @@
+import { readdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import type { ActionInstance } from "./action.js";
+
+/**
+ * Check if a value looks like an ActionInstance (duck-typing).
+ */
+function isAction(val: unknown): val is ActionInstance<any, any> {
+  if (typeof val !== "object" || val === null) return false;
+  const obj = val as Record<string, unknown>;
+  return typeof obj.name === "string" && typeof obj.run === "function";
+}
+
+/**
+ * Load all actions from a directory.
+ * Each .ts file should default-export an action().
+ */
+export async function loadActions(
+  dir: string,
+): Promise<ActionInstance<any, any>[]> {
+  const absDir = resolve(dir);
+  const files = await readdir(absDir);
+  const actions: ActionInstance<any, any>[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".ts") && !file.endsWith(".js")) continue;
+    if (file.endsWith(".test.ts") || file.endsWith(".test.js")) continue;
+
+    const filePath = join(absDir, file);
+    const mod = await import(filePath);
+
+    // Check default export first
+    if (mod.default && isAction(mod.default)) {
+      actions.push(mod.default);
+      continue;
+    }
+
+    // Check named exports
+    for (const key of Object.keys(mod)) {
+      if (isAction(mod[key])) {
+        actions.push(mod[key]);
+      }
+    }
+  }
+
+  return actions;
+}

package/src/api/actions.ts

@@ -0,0 +1,124 @@
+import { Hono } from "hono";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import { z } from "zod";
+import type { ActionInstance } from "../actions/action.js";
+import { ActionError } from "../db/errors.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "actions" });
+
+/**
+ * Convert a Zod schema to JSON Schema using Zod v4's built-in converter.
+ * Returns undefined if conversion fails.
+ */
+function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> | undefined {
+  try {
+    return z.toJSONSchema(schema) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Create the /actions API sub-app. Mounted at `/p/{slug}/actions` by the runtime.
+ *
+ * - GET  /       → list all actions with input JSON Schema
+ * - POST /:name  → execute an action (validated, transactional)
+ *
+ * Uses a single parametric /:name route backed by a Map lookup.
+ *
+ * ## Transaction semantics
+ *
+ * Each action's `run` function executes inside a single Drizzle transaction.
+ * If `run` throws, the transaction is rolled back automatically. The `afterCommit`
+ * callbacks run AFTER the transaction has committed — they're for side effects
+ * only (sending emails, logging, webhooks). Failures in afterCommit do NOT
+ * roll back the transaction.
+ *
+ * ## Error handling
+ *
+ * - Zod validation failure → 422 with field-level error details
+ * - ActionError (thrown by business logic) → 400 with error message and code
+ * - Unhandled errors → bubble up to Hono's error handler (500)
+ *
+ * ActionError is the intentional "business rule violated" signal. Unhandled
+ * errors are bugs. This distinction is important: the frontend shows ActionError
+ * messages to the user but treats unhandled errors as unexpected failures.
+ */
+export function actionApi(
+  actions: ActionInstance<any, any>[],
+  db: BetterSQLite3Database,
+): Hono {
+  const actionMap = new Map(actions.map((a) => [a.name, a]));
+  const app = new Hono();
+
+  app.get("/", (c) => {
+    return c.json({
+      actions: actions.map((act) => ({
+        name: act.name,
+        label: act.label,
+        inputSchema: zodToJsonSchema(act.input),
+      })),
+    });
+  });
+
+  app.post("/:name", async (c) => {
+    const act = actionMap.get(c.req.param("name"));
+    if (!act) return c.notFound();
+
+    const body = await c.req.json();
+    log.debug("Action request", { action: act.name, body });
+
+    // Validate input
+    const parsed = act.input.safeParse(body);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map(
+        (i: { path: string[]; message: string }) => ({
+          field: i.path.join("."),
+          message: i.message,
+        }),
+      );
+      log.warn("Action validation failed", { action: act.name, issues });
+      return c.json(
+        {
+          error: "Validation failed",
+          details: issues,
+        },
+        422,
+      );
+    }
+
+    try {
+      // Run inside a Drizzle SQLite transaction. If run() throws, the
+      // transaction rolls back and no afterCommit callbacks execute.
+      //
+      // IMPORTANT: SQLite transactions are SYNCHRONOUS — the callback
+      // cannot be async or return a Promise. This means action run()
+      // functions must be synchronous when using Drizzle operations.
+      // The `tx` object is a transactional Drizzle client — all queries
+      // through it share a single SQLite transaction.
+      const result = db.transaction((tx) => {
+        return act.run({ input: parsed.data, db: tx as any });
+      });
+
+      // afterCommit runs AFTER the transaction has committed successfully.
+      // Use for side effects (email, audit log, webhooks) that should NOT
+      // roll back the transaction if they fail. Callbacks run sequentially.
+      if (act.afterCommit) {
+        for (const cb of act.afterCommit) {
+          await cb(result);
+        }
+      }
+
+      return c.json({ data: result });
+    } catch (err) {
+      if (err instanceof ActionError) {
+        log.warn("Action error", { action: act.name, code: err.code, message: err.message });
+        return c.json({ error: err.message, code: err.code }, 400);
+      }
+      throw err;
+    }
+  });
+
+  return app;
+}