@tatara/cli 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",

package/templates/features/base/files/AGENTS.md

@@ -55,6 +55,12 @@ __PM_EXEC__ tatara upgrade               # after bumping @tatara/cli: run its co
   `{ success: false, error, code, details }`.
 - Route files are `routes/<name>.routes.ts` and default-export `defineRoutes({ app, basePath, router })`.
   They are found automatically; there is no central list to edit.
+- Long or live lists page by cursor: `cursorQuerySchema` for the query, fetch `limit + 1` rows after
+  `decodeCursor(positionSchema, cursor)`, answer `cursorPage(rows, limit, (row) => ({ createdAt, id }))`
+  (schema: `cursorPageSchema(item)`).
+- Requests time out after `REQUEST_TIMEOUT_MS` (504); give slow paths their own limit in
+  `src/apps/http.ts` (`timeouts.paths`). Behind proxies, set `TRUSTED_PROXY_HOPS` and read the caller
+  with `clientIp(c, { trustedHops })`.
 
 ## Configuration and logging
 
@@ -62,6 +68,17 @@ __PM_EXEC__ tatara upgrade               # after bumping @tatara/cli: run its co
   `.env.example`. Never read `process.env` elsewhere.
 - Log with `c.get("logger")` in requests and `logger` from `#core/logging/logger` elsewhere.
   No `console.*` outside commands and tests.
+- Secrets and codes come from `@tatara/core`: `createEncryption(keys)` for secrets at rest (AES-GCM,
+  rotatable keys), `randomToken()`, `numericCode()`, `randomCode()`, `hashToken()`, `safeEqual()`.
+  Never `Math.random()` for anything a user could guess.
+- User text: `text({ max })` and `url()` from `@tatara/core` in validators clean and check it (control,
+  invisible and bidi characters, whitespace; only http(s) links). Escape when you render HTML.
+
+## Deploying
+
+- Every deploy runs `node dist/apps/cli/index.mjs deploy`: commands with `phase: "deploy"` (migrations
+  first, then the rest by `order`), and each `phase: "once"` command the first time a database sees
+  it (recorded in a ledger). Commands without a phase only run when asked for.
 
 ## Tests
 

package/templates/features/base/files/biome.template.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://biomejs.dev/schemas/__BIOME_VERSION__/schema.json",
 	"files": {
-		"includes": ["**", "!**/node_modules", "!**/dist", "!**/coverage", "!src/generated", "!drizzle", "!prisma/migrations"]
+		"includes": ["**", "!**/node_modules", "!**/dist", "!**/coverage", "!src/generated", "!drizzle", "!prisma/migrations", "!contracts"]
 	},
 	"formatter": { "indentStyle": "tab", "lineWidth": 100 },
 	"javascript": { "formatter": { "quoteStyle": "double" } },

package/templates/features/base/files/src/apps/api/server.ts

@@ -2,5 +2,11 @@ import { startServer } from "@tatara/http";
 import { app } from "#apps/api/app";
 import { env } from "#core/config/env";
 import { logger } from "#core/logging/logger";
+// tatara:slot imports
 
-startServer(app, { port: env.PORT, name: "api", logger });
+startServer(app, {
+	port: env.PORT,
+	name: "api",
+	logger,
+	// tatara:slot server-options
+});

package/templates/features/base/files/src/apps/cli/index.ts

@@ -1,6 +1,9 @@
 import { runCommand, shutdown } from "@tatara/core";
 import { logger } from "#core/logging/logger";
 import { commands } from "#generated/commands";
+// tatara:slot imports
 
-const code = await runCommand(commands, process.argv.slice(2), logger);
+const code = await runCommand(commands, process.argv.slice(2), logger, {
+	// tatara:slot options
+});
 await shutdown(code, logger);

package/templates/features/base/files/src/apps/http.ts

@@ -20,6 +20,12 @@ export function createHttpApp(name: AppName, options: { title: string }) {
 			],
 		},
 		bodyLimitBytes: env.BODY_LIMIT_BYTES,
+		timeouts: {
+			defaultMs: env.REQUEST_TIMEOUT_MS,
+			paths: {
+				// tatara:slot timeout-paths
+			},
+		},
 		defaults: { principal: null, language: "en" },
 	});
 	// tatara:slot middleware

package/templates/features/base/files/src/core/logging/logger.ts

@@ -1,9 +1,11 @@
 import { loggerOptions } from "@tatara/core";
 import { pino } from "pino";
 import { env } from "#core/config/env";
+// tatara:slot imports
 
-export const logger = pino(
-	loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "__APP_NAME__" }),
-);
+export const logger = pino({
+	...loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "__APP_NAME__" }),
+	// tatara:slot logger-options
+});
 
 export type Logger = typeof logger;

package/templates/features/cache/files/src/core/cache/index.ts

@@ -0,0 +1,23 @@
+import { onShutdown } from "@tatara/core";
+import { type Cache, createCache, type CacheStore, memoryStore } from "@tatara/cache";
+import { redisStore } from "@tatara/cache/redis";
+import { Redis } from "ioredis";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export type { Cache } from "@tatara/cache";
+
+function redis(): CacheStore {
+	// connects on first command, so importing this file opens nothing
+	const client = new Redis(env.REDIS_URL, { lazyConnect: true, maxRetriesPerRequest: 3 });
+	onShutdown("cache", async () => {
+		await client.quit();
+	});
+	return redisStore(client);
+}
+
+/** The app's cache; pick the store with CACHE_DRIVER. */
+export const cache: Cache = createCache(env.CACHE_DRIVER === "redis" ? redis() : memoryStore(), {
+	prefix: "__APP_NAME__",
+	onError: (error, key) => logger.warn({ err: error, key }, "cache unavailable, computing instead"),
+});

package/templates/features/cache/files/src/core/http/rate-limit.ts

@@ -0,0 +1,15 @@
+import { clientIp, type RateLimitOptions, rateLimit } from "@tatara/http";
+import { cache } from "#core/cache/index";
+import { env } from "#core/config/env";
+
+/**
+ * `middleware: [limitRequests({ name: "contact", windowMs: 60_000, max: 5 })]` on a route: per
+ * caller IP, or per whatever `key` returns (e.g. the signed-in user).
+ */
+export function limitRequests(options: Omit<RateLimitOptions, "counter" | "key"> & Partial<Pick<RateLimitOptions, "key">>) {
+	return rateLimit({
+		counter: cache,
+		key: (c) => clientIp(c, { trustedHops: env.TRUSTED_PROXY_HOPS }),
+		...options,
+	});
+}

package/templates/features/cache/files/tests/tatara/cache.test.ts

@@ -0,0 +1,22 @@
+import { orgKey } from "@tatara/cache";
+import { describe, expect, it, vi } from "vitest";
+import { cache } from "#core/cache/index";
+
+describe("cache", () => {
+	it("wraps a computation and drops an org's keys together", async () => {
+		const orgId = crypto.randomUUID();
+		const load = vi.fn(async () => ({ total: 3 }));
+		expect(await cache.wrap(orgKey(orgId, "dashboard"), 60_000, load)).toEqual({ total: 3 });
+		expect(await cache.wrap(orgKey(orgId, "dashboard"), 60_000, load)).toEqual({ total: 3 });
+		expect(load).toHaveBeenCalledTimes(1);
+		expect(await cache.delPrefix(orgKey(orgId))).toBe(1);
+		expect(await cache.get(orgKey(orgId, "dashboard"))).toBeNull();
+	});
+
+	it("lets one holder run under a lock", async () => {
+		const key = crypto.randomUUID();
+		const first = cache.lock(key, 10_000, () => new Promise((r) => setTimeout(() => r("ran"), 50)));
+		expect(await cache.lock(key, 10_000, async () => "second")).toEqual({ acquired: false });
+		expect(await first).toEqual({ acquired: true, value: "ran" });
+	});
+});

package/templates/features/cache/files/tests/tatara/rate-limit.test.ts

@@ -0,0 +1,27 @@
+import { createRoute } from "@hono/zod-openapi";
+import { createRouter, handleErrors } from "@tatara/http";
+import { describe, expect, it } from "vitest";
+import { limitRequests } from "#core/http/rate-limit";
+
+describe("limitRequests", () => {
+	it("answers 429 once a caller passes the limit", async () => {
+		const name = crypto.randomUUID();
+		const app = createRouter();
+		app.openapi(
+			createRoute({
+				method: "post",
+				path: "/contact",
+				middleware: [limitRequests({ name, windowMs: 60_000, max: 2, key: (c) => c.req.header("x-who") })],
+				responses: { 204: { description: "Sent" } },
+			}),
+			(c) => c.body(null, 204),
+		);
+		handleErrors(app);
+		const send = () => app.request("/contact", { method: "POST", headers: { "x-who": "a" } });
+		expect((await send()).status).toBe(204);
+		expect((await send()).status).toBe(204);
+		const limited = await send();
+		expect(limited.status).toBe(429);
+		expect(limited.headers.get("retry-after")).toBe("60");
+	});
+});

package/templates/features/cache/files+postgres/src/core/cache/index.ts

@@ -0,0 +1,36 @@
+import { onShutdown } from "@tatara/core";
+import { type Cache, createCache, type CacheStore, memoryStore } from "@tatara/cache";
+import { postgresStore } from "@tatara/cache/postgres";
+import { redisStore } from "@tatara/cache/redis";
+import { Redis } from "ioredis";
+import pg from "pg";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export type { Cache } from "@tatara/cache";
+
+function redis(): CacheStore {
+	// connects on first command, so importing this file opens nothing
+	const client = new Redis(env.REDIS_URL, { lazyConnect: true, maxRetriesPerRequest: 3 });
+	onShutdown("cache", async () => {
+		await client.quit();
+	});
+	return redisStore(client);
+}
+
+function postgres(): CacheStore {
+	// an unlogged table in the "tatara" schema, created on first use
+	const pool = new pg.Pool({ connectionString: env.DATABASE_URL, max: 5 });
+	onShutdown("cache", async () => {
+		await pool.end();
+	});
+	return postgresStore(pool);
+}
+
+const stores = { redis, postgres, memory: memoryStore };
+
+/** The app's cache; pick the store with CACHE_DRIVER. */
+export const cache: Cache = createCache(stores[env.CACHE_DRIVER](), {
+	prefix: "__APP_NAME__",
+	onError: (error, key) => logger.warn({ err: error, key }, "cache unavailable, computing instead"),
+});

package/templates/features/db/files+mysql+drizzle/src/core/commands/db/command-runs.schema.ts

@@ -0,0 +1,10 @@
+import { sql } from "drizzle-orm";
+import { datetime, int, mysqlTable, varchar } from "drizzle-orm/mysql-core";
+
+/** Which "once" commands this database has run (written by `deploy`). */
+export const tataraCommandRuns = mysqlTable("tatara_command_runs", {
+	name: varchar({ length: 255 }).primaryKey(),
+	phase: varchar({ length: 16 }).notNull(),
+	ranAt: datetime({ fsp: 3 }).notNull().default(sql`current_timestamp(3)`),
+	durationMs: int().notNull(),
+});

package/templates/features/db/files+mysql+drizzle/src/core/db/admin.ts

@@ -1,2 +1,7 @@
 // This app uses MySQL through mysql2.
-export { dropAllTables, ensureDatabase, truncateAllTables } from "@tatara/db/mysql2";
+export {
+	commandLedger,
+	dropAllTables,
+	ensureDatabase,
+	truncateAllTables,
+} from "@tatara/db/mysql2";

package/templates/features/db/files+mysql+prisma/prisma/models/command-runs.prisma

@@ -0,0 +1,9 @@
+// Which "once" commands this database has run (written by `deploy`).
+model TataraCommandRun {
+  name       String   @id @db.VarChar(255)
+  phase      String   @db.VarChar(16)
+  ranAt      DateTime @default(now()) @map("ran_at") @db.DateTime(3)
+  durationMs Int      @map("duration_ms")
+
+  @@map("tatara_command_runs")
+}

package/templates/features/db/files+mysql+prisma/src/core/db/admin.ts

@@ -1,5 +1,6 @@
 // This app uses MySQL through the mariadb driver (Prisma adapter).
 export {
+	commandLedger,
 	connectionConfig,
 	dropAllTables,
 	ensureDatabase,

package/templates/features/db/files+postgres/src/core/db/admin.ts

@@ -1,2 +1,7 @@
 // This app uses PostgreSQL through node-postgres.
-export { dropAllTables, ensureDatabase, truncateAllTables } from "@tatara/db/postgres";
+export {
+	commandLedger,
+	dropAllTables,
+	ensureDatabase,
+	truncateAllTables,
+} from "@tatara/db/postgres";

package/templates/features/email/files/src/core/email/send.ts

@@ -1,13 +1,33 @@
-import { createMailer } from "@tatara/email";
+import { createMailer, renderEmail } from "@tatara/email";
 import { env } from "#core/config/env";
 import { logger } from "#core/logging/logger";
+import type { emails } from "#generated/emails";
 
 export type { EmailMessage } from "@tatara/email";
 
-/** Sends through SMTP (Mailpit locally) or logs it when EMAIL_DRIVER=console. */
+/** Sends through SMTP (Mailpit locally) or Mailgun, or logs it when EMAIL_DRIVER=console. */
 export const { send: sendEmail } = createMailer({
 	driver: env.EMAIL_DRIVER,
 	smtpUrl: env.SMTP_URL,
+	...(env.MAILGUN_API_KEY && env.MAILGUN_DOMAIN
+		? { mailgun: { apiKey: env.MAILGUN_API_KEY, domain: env.MAILGUN_DOMAIN, apiUrl: env.MAILGUN_API_URL } }
+		: {}),
 	from: env.EMAIL_FROM,
 	logger,
 });
+
+type Templates = { [E in (typeof emails)[number] as E["name"]]: Parameters<E["render"]>[0] };
+
+/** Renders an `emails/*.ts` template in `language` and sends it. */
+export async function sendTemplate<N extends keyof Templates & string>(
+	name: N,
+	to: string,
+	data: Templates[N],
+	language = "en",
+): Promise<void> {
+	// loaded on first use: core doesn't import module code until it's needed
+	const { emails: all } = await import("#generated/emails");
+	const template = all.find((e) => e.name === name);
+	if (!template) throw new Error(`No email template named "${name}"`);
+	await sendEmail({ to, ...renderEmail(template, data, language) });
+}

package/templates/features/email/files/src/modules/example/emails/welcome.ts

@@ -0,0 +1,11 @@
+import { defineEmail } from "@tatara/email";
+import { z } from "zod";
+
+export default defineEmail({
+	name: "example.welcome",
+	schema: z.object({ name: z.string().min(1) }),
+	render: ({ name }, language) =>
+		language === "ar"
+			? { subject: "أهلاً بك", text: `أهلاً ${name}` }
+			: { subject: "Welcome", text: `Hello ${name}, welcome aboard.` },
+});

package/templates/features/jobs/files/src/apps/cron/index.ts

@@ -1,8 +1,7 @@
 import { handleSignals } from "@tatara/core";
 import { startCron } from "@tatara/jobs";
-import { redis } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
-import { schedules } from "#generated/schedules";
+import { scheduleRunner } from "#apps/cron/runner";
 
-startCron({ schedules, redis, logger });
+startCron({ ...scheduleRunner, logger });
 handleSignals(logger);

package/templates/features/jobs/files/src/apps/cron/runner.ts

@@ -0,0 +1,11 @@
+import { cache } from "#core/cache/index";
+import { schedules } from "#generated/schedules";
+// tatara:slot imports
+
+/** What runs a schedule, wherever it's triggered from: the cron app, `schedule:run`, or HTTP. */
+export const scheduleRunner = {
+	schedules,
+	// one run per tick across every process and trigger
+	lock: cache,
+	// tatara:slot options
+};

package/templates/features/jobs/files/src/apps/worker/index.ts

@@ -1,16 +1,9 @@
 import { handleSignals } from "@tatara/core";
 import { startWorker } from "@tatara/jobs";
 import { env } from "#core/config/env";
-import { QUEUE_NAME, redis } from "#core/jobs/index";
+import { jobs } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 
-startWorker({
-	queue: QUEUE_NAME,
-	prefix: env.JOBS_PREFIX,
-	redis: redis(),
-	concurrency: env.WORKER_CONCURRENCY,
-	consumers,
-	logger,
-});
+await startWorker({ driver: jobs.driver, consumers, concurrency: env.WORKER_CONCURRENCY, logger });
 handleSignals(logger);

package/templates/features/jobs/files/src/core/jobs/index.ts

@@ -1,10 +1,41 @@
-import { createQueue, lazyRedis } from "@tatara/jobs";
+import { createJobs, inlineDriver, type JobDriver, lazyRedis, type TopicsOf } from "@tatara/jobs";
+import { bullmqDriver } from "@tatara/jobs/bullmq";
+import { kafkaDriver } from "@tatara/jobs/kafka";
+import { Kafka } from "kafkajs";
 import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+import type { consumers } from "#generated/consumers";
 
-export const QUEUE_NAME = "__APP_NAME__-jobs";
-
-/** The shared Redis connection, opened on first use. */
+/** The shared Redis connection for BullMQ, opened on first use. */
 export const redis = lazyRedis(env.REDIS_URL);
 
-/** `enqueue(topic, data)`: the consumer with that topic validates the payload. */
-export const { enqueue } = createQueue({ name: QUEUE_NAME, prefix: env.JOBS_PREFIX, redis });
+function kafka(): JobDriver {
+	if (!env.KAFKA_BROKERS) throw new Error("JOBS_DRIVER=kafka needs KAFKA_BROKERS");
+	const client = new Kafka({
+		clientId: env.KAFKA_CLIENT_ID,
+		brokers: env.KAFKA_BROKERS.split(","),
+		ssl: env.KAFKA_SSL,
+		...(env.KAFKA_SASL_USERNAME && env.KAFKA_SASL_PASSWORD
+			? {
+					sasl: {
+						mechanism: "scram-sha-512",
+						username: env.KAFKA_SASL_USERNAME,
+						password: env.KAFKA_SASL_PASSWORD,
+					},
+				}
+			: {}),
+	});
+	return kafkaDriver({ kafka: client, topic: "__APP_NAME__.jobs", groupId: env.KAFKA_CLIENT_ID });
+}
+
+const drivers: Record<typeof env.JOBS_DRIVER, () => JobDriver> = {
+	bullmq: () => bullmqDriver({ name: "__APP_NAME__-jobs", prefix: env.JOBS_PREFIX, redis }),
+	kafka,
+	// jobs run where they're sent, with no worker: tests and quick local work
+	inline: () =>
+		inlineDriver({ consumers: async () => (await import("#generated/consumers")).consumers, logger }),
+};
+
+/** `jobs.enqueue(topic, data, { orgId })`, typed by the app's consumers; pick the driver with JOBS_DRIVER. */
+export const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: drivers[env.JOBS_DRIVER]() });
+export const { enqueue } = jobs;

package/templates/features/jobs/files/src/modules/example/tests/jobs.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { processJob, withLock } from "@tatara/jobs";
-import { redis } from "#core/jobs/index";
+import { type InlineDriver, processJob } from "@tatara/jobs";
+import { enqueue, jobs } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 
@@ -17,13 +17,10 @@ describe("jobs", () => {
 		);
 	});
 
-	it("lets only one holder run a locked section", async () => {
-		const key = `test-${Date.now()}-${Math.random()}`;
-		let inner: boolean | undefined;
-		const outer = await withLock(redis(), key, 5000, async () => {
-			inner = await withLock(redis(), key, 5000, async () => {});
-		});
-		expect(outer).toBe(true);
-		expect(inner).toBe(false);
+	it("runs an enqueued job in tests (JOBS_DRIVER=inline)", async () => {
+		await enqueue("example.send-welcome", { name: "Ada" });
+		const driver = jobs.driver as InlineDriver;
+		await driver.drain();
+		expect(driver.dead).toEqual([]);
 	});
 });

package/templates/features/jobs/files+drizzle+postgres/src/core/jobs/outbox.ts

@@ -0,0 +1,23 @@
+import { type SQL, sql } from "drizzle-orm";
+import type { Queryable } from "@tatara/jobs/postgres";
+import { type Executor, pool } from "#core/db/client";
+
+/** The app's own pool: the Postgres driver needs no connection of its own. */
+export const outboxPool: Queryable = pool;
+
+/**
+ * `enqueue(topic, data, { executor: inTransaction(tx) })`: with JOBS_DRIVER=postgres the job is
+ * written in `tx`, so it exists exactly when the transaction commits.
+ */
+export function inTransaction(executor: Executor): Queryable {
+	return {
+		query(text, values = []) {
+			// $1, $2… become drizzle parameters
+			const parts = text.split(/\$(\d+)/);
+			let query: SQL = sql.raw(parts[0] ?? "");
+			for (let i = 1; i < parts.length; i += 2)
+				query = sql`${query}${values[Number(parts[i]) - 1]}${sql.raw(parts[i + 1] ?? "")}`;
+			return executor.execute(query);
+		},
+	};
+}

package/templates/features/jobs/files+drizzle+postgres/tests/tatara/jobs-outbox.test.ts

@@ -0,0 +1,34 @@
+import { createJobs, type TopicsOf } from "@tatara/jobs";
+import { postgresDriver } from "@tatara/jobs/postgres";
+import { describe, expect, it } from "vitest";
+import { db } from "#core/db/client";
+import { inTransaction, outboxPool } from "#core/jobs/outbox";
+import type { consumers } from "#generated/consumers";
+
+const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: postgresDriver({ db: outboxPool }) });
+
+async function stored(id: string): Promise<number> {
+	const result = (await outboxPool.query("select count(*)::int as n from tatara.jobs where id = $1", [id])) as {
+		rows: { n: number }[];
+	};
+	return result.rows[0]?.n ?? 0;
+}
+
+describe("the Postgres job outbox", () => {
+	it("stores a job with the caller's transaction, and drops it on rollback", async () => {
+		let rolledBack = "";
+		await expect(
+			db.transaction(async (tx) => {
+				rolledBack = await jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) });
+				throw new Error("rollback");
+			}),
+		).rejects.toThrow("rollback");
+		expect(await stored(rolledBack)).toBe(0);
+
+		const committed = await db.transaction(async (tx) =>
+			jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) }),
+		);
+		expect(await stored(committed)).toBe(1);
+		await outboxPool.query("delete from tatara.jobs where id = $1", [committed]);
+	});
+});

package/templates/features/jobs/files+postgres/src/core/jobs/index.ts

@@ -0,0 +1,47 @@
+import { createJobs, inlineDriver, type JobDriver, lazyRedis, type TopicsOf } from "@tatara/jobs";
+import { bullmqDriver } from "@tatara/jobs/bullmq";
+import { kafkaDriver } from "@tatara/jobs/kafka";
+import { postgresDriver } from "@tatara/jobs/postgres";
+import { Kafka } from "kafkajs";
+import { env } from "#core/config/env";
+import { outboxPool } from "#core/jobs/outbox";
+import { logger } from "#core/logging/logger";
+import type { consumers } from "#generated/consumers";
+
+export { inTransaction } from "#core/jobs/outbox";
+
+/** The shared Redis connection for BullMQ, opened on first use. */
+export const redis = lazyRedis(env.REDIS_URL);
+
+function kafka(): JobDriver {
+	if (!env.KAFKA_BROKERS) throw new Error("JOBS_DRIVER=kafka needs KAFKA_BROKERS");
+	const client = new Kafka({
+		clientId: env.KAFKA_CLIENT_ID,
+		brokers: env.KAFKA_BROKERS.split(","),
+		ssl: env.KAFKA_SSL,
+		...(env.KAFKA_SASL_USERNAME && env.KAFKA_SASL_PASSWORD
+			? {
+					sasl: {
+						mechanism: "scram-sha-512",
+						username: env.KAFKA_SASL_USERNAME,
+						password: env.KAFKA_SASL_PASSWORD,
+					},
+				}
+			: {}),
+	});
+	return kafkaDriver({ kafka: client, topic: "__APP_NAME__.jobs", groupId: env.KAFKA_CLIENT_ID });
+}
+
+const drivers: Record<typeof env.JOBS_DRIVER, () => JobDriver> = {
+	bullmq: () => bullmqDriver({ name: "__APP_NAME__-jobs", prefix: env.JOBS_PREFIX, redis }),
+	// a "tatara.jobs" table, claimed with SKIP LOCKED; enqueue with { executor: inTransaction(tx) }
+	postgres: () => postgresDriver({ db: outboxPool }),
+	kafka,
+	// jobs run where they're sent, with no worker: tests and quick local work
+	inline: () =>
+		inlineDriver({ consumers: async () => (await import("#generated/consumers")).consumers, logger }),
+};
+
+/** `jobs.enqueue(topic, data, { orgId })`, typed by the app's consumers; pick the driver with JOBS_DRIVER. */
+export const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: drivers[env.JOBS_DRIVER]() });
+export const { enqueue } = jobs;

package/templates/features/jobs/files+prisma+postgres/src/core/jobs/outbox.ts

@@ -0,0 +1,17 @@
+import { onShutdown } from "@tatara/core";
+import type { Queryable } from "@tatara/jobs/postgres";
+import pg from "pg";
+import { env } from "#core/config/env";
+import type { Executor } from "#core/db/client";
+
+/** A small pool for the Postgres job driver (Prisma keeps its own connections to itself). */
+export const outboxPool: Queryable = new pg.Pool({ connectionString: env.DATABASE_URL, max: 5 });
+onShutdown("jobs-pool", () => (outboxPool as pg.Pool).end());
+
+/**
+ * `enqueue(topic, data, { executor: inTransaction(tx) })`: with JOBS_DRIVER=postgres the job is
+ * written in `tx`, so it exists exactly when the transaction commits.
+ */
+export function inTransaction(executor: Executor): Queryable {
+	return { query: (text, values = []) => executor.$executeRawUnsafe(text, ...values) };
+}

package/templates/features/jobs/files+prisma+postgres/tests/tatara/jobs-outbox.test.ts

@@ -0,0 +1,34 @@
+import { createJobs, type TopicsOf } from "@tatara/jobs";
+import { postgresDriver } from "@tatara/jobs/postgres";
+import { describe, expect, it } from "vitest";
+import { db } from "#core/db/client";
+import { inTransaction, outboxPool } from "#core/jobs/outbox";
+import type { consumers } from "#generated/consumers";
+
+const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: postgresDriver({ db: outboxPool }) });
+
+async function stored(id: string): Promise<number> {
+	const result = (await outboxPool.query("select count(*)::int as n from tatara.jobs where id = $1", [id])) as {
+		rows: { n: number }[];
+	};
+	return result.rows[0]?.n ?? 0;
+}
+
+describe("the Postgres job outbox", () => {
+	it("stores a job with the caller's transaction, and drops it on rollback", async () => {
+		let rolledBack = "";
+		await expect(
+			db.$transaction(async (tx) => {
+				rolledBack = await jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) });
+				throw new Error("rollback");
+			}),
+		).rejects.toThrow("rollback");
+		expect(await stored(rolledBack)).toBe(0);
+
+		const committed = await db.$transaction(async (tx) =>
+			jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) }),
+		);
+		expect(await stored(committed)).toBe(1);
+		await outboxPool.query("delete from tatara.jobs where id = $1", [committed]);
+	});
+});

package/templates/features/notifications/files/src/modules/example/notifications/welcome.ts

@@ -0,0 +1,14 @@
+import { defineNotification } from "@tatara/notifications";
+import { z } from "zod";
+
+export default defineNotification({
+	name: "example.welcome",
+	description: "Example notification: greets a new user",
+	schema: z.object({ name: z.string().min(1) }),
+	channels: ["in-app", "push"],
+	inApp: ({ name }, language) => ({
+		title: language === "ar" ? `أهلاً ${name}` : `Welcome, ${name}`,
+		url: "/",
+	}),
+	push: ({ name }) => ({ title: `Welcome, ${name}` }),
+});

package/templates/features/notifications/files/src/modules/notifications/consumers/deliver.ts

@@ -0,0 +1,6 @@
+import type { DeliverConsumer } from "@tatara/notifications";
+import { consumers } from "#modules/notifications/services/notifier";
+
+/** Stores one user's notification and sends it on each channel, once each. */
+const deliver: DeliverConsumer = consumers[1];
+export default deliver;