create-questpie 2.0.3 → 2.0.4

package/skills/questpie/references/business-logic.md

@@ -1,6 +1,7 @@
 ---
 name: questpie-core-business-logic
-description: QUESTPIE routes jobs services emails route job service email background queue scheduling Zod input validation server-side logic reusable services email templates
+description:
+  QUESTPIE routes jobs services emails route job service email background queue scheduling Zod input validation server-side logic reusable services email templates
   - questpie-core
 ---
 
@@ -16,7 +17,7 @@ JSON routes are typed server-side endpoints. Define an input schema with Zod, wr
 
 ```ts
 // routes/get-active-barbers.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -37,7 +38,7 @@ JSON routes validate input with Zod automatically:
 
 ```ts
 // routes/create-booking.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -77,15 +78,18 @@ export default route()
 
 Route handlers receive the full `AppContext`:
 
-| Property      | Description                            |
-| ------------- | -------------------------------------- |
-| `input`       | Validated data matching the Zod schema |
-| `collections` | Typed collection API                   |
-| `queue`       | Publish background jobs                |
-| `email`       | Send emails                            |
-| `db`          | Raw database access                    |
-| `session`     | Current auth session                   |
-| `services`    | Custom services from `services/`       |
+| Property      | Description                                                |
+| ------------- | ---------------------------------------------------------- |
+| `input`       | Validated data matching the Zod schema                     |
+| `collections` | Typed collection API                                       |
+| `queue`       | Publish background jobs                                    |
+| `email`       | Send emails                                                |
+| `db`          | Raw database access                                        |
+| `session`     | Current auth session                                       |
+| `services`    | Custom services from `services/`                           |
+| _extensions_  | `appConfig({ context })` result, flat (e.g. `workspaceId`) |
+
+Derived request context (from `appConfig({ context })`) reaches route access rules and handlers alike — destructure the keys directly. Inside any nested code, `getContext<App>()` exposes the same keys (see `references/multi-tenancy.md`).
 
 ### Calling Routes
 
@@ -125,7 +129,7 @@ Jobs are background tasks that run outside the request lifecycle. Ideal for send
 
 ```ts
 // jobs/send-appointment-confirmation.ts
-import { job } from "questpie";
+import { job } from "questpie/services";
 import z from "zod";
 
 export default job({
@@ -182,6 +186,31 @@ Publish from hooks, routes, or other jobs via the typed `queue` context:
 
 The `queue` object provides full autocompletion for all jobs and their payloads.
 
+### Recurring Jobs (Cron)
+
+Jobs accept a job-level cron expression in `options.cron`. Schedules are registered automatically when the queue worker starts (`app.queue.listen()` calls `registerSchedules()`):
+
+```ts
+// jobs/cleanup-expired.ts
+import { job } from "questpie/services";
+import z from "zod";
+
+export default job({
+	name: "cleanupExpired",
+	schema: z.object({}),
+	options: { cron: "0 3 * * *" }, // every day at 03:00
+	handler: async ({ collections }) => {
+		await collections.sessions.deleteMany({
+			where: { expiresAt: { lt: new Date() } },
+		});
+	},
+});
+```
+
+Programmatic scheduling from any handler: `queue.cleanupExpired.schedule({}, "0 3 * * *")` and `queue.cleanupExpired.unschedule()`.
+
+Use job-level cron for simple recurring tasks (cleanup, digests, syncs). Reach for **workflow-level cron** (`references/workflows.md`) only when the recurring process needs steps, durable waits, or replay — a workflow is the heavier primitive.
+
 ### Job Handler Context
 
 | Property      | Description                            |
@@ -198,7 +227,8 @@ Configure the queue adapter in your runtime config:
 
 ```ts
 // questpie.config.ts
-import { pgBossAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgBossAdapter } from "questpie/adapters/pg-boss";
 
 export default runtimeConfig({
 	queue: {
@@ -209,26 +239,28 @@ export default runtimeConfig({
 });
 ```
 
-## Routes
+## Raw Routes
 
-Routes give raw HTTP request/response handling for webhooks, OAuth callbacks, health checks, file downloads, and streaming.
+Raw routes (`route().raw()`) give raw HTTP request/response handling for webhooks, OAuth callbacks, health checks, file downloads, and streaming. The handler receives the standard `Request` and must return a `Response`.
 
-### Defining a Route
+### Defining a Raw Route
 
 ```ts
 // routes/health.ts
-import { route } from "questpie";
+import { sql } from "questpie/drizzle";
+import { route } from "questpie/services";
 
-export default route({
-	method: "GET",
-	handler: async ({ db }) => {
+export default route()
+	.get()
+	.raw()
+	.access(true)
+	.handler(async ({ db }) => {
 		const healthy = await db
 			.execute(sql`SELECT 1`)
 			.then(() => true)
 			.catch(() => false);
 		return Response.json({ status: healthy ? "ok" : "degraded" });
-	},
-});
+	});
 ```
 
 Place files in `routes/`. The file path maps to a flat URL under your `basePath` (`/api` by default):
@@ -243,27 +275,29 @@ routes/
 
 ### Route Methods
 
+Chain HTTP method calls on the builder (multiple methods = multiple calls):
+
 ```ts
-route({ method: "POST", handler: ... })           // Single method
-route({ method: ["GET", "POST"], handler: ... })   // Multiple methods
-route({ handler: ... })                            // All methods (default)
+route().post().raw().handler(...)          // POST only
+route().get().post().raw().handler(...)    // GET + POST
 ```
 
-Supported: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
+Supported: `.get()`, `.post()`, `.put()`, `.delete()`, `.patch()`. The built-in `/auth/*` catch-all is itself a raw route (`route().get().post().raw()` delegating to Better Auth) — raw handlers run inside `runWithContext`, so the full request context is live in any code they call.
 
 ### Route Handler Context
 
-| Property      | Type                     | Description              |
-| ------------- | ------------------------ | ------------------------ |
-| `request`     | `Request`                | Standard Web API Request |
-| `params`      | `Record<string, string>` | URL path parameters      |
-| `locale`      | `string`                 | Current locale           |
-| `db`          | `Database`               | Database instance        |
-| `session`     | `Session \| null`        | Current auth session     |
-| `collections` | `CollectionsAPI`         | Typed collection API     |
-| `queue`       | `QueueClient`            | Queue client             |
-| `email`       | `MailerService`          | Email service            |
-| `services`    |                          | User-defined services    |
+| Property      | Type                     | Description                                  |
+| ------------- | ------------------------ | -------------------------------------------- |
+| `request`     | `Request`                | Standard Web API Request                     |
+| `params`      | `Record<string, string>` | URL path parameters                          |
+| `locale`      | `string`                 | Current locale                               |
+| `db`          | `Database`               | Database instance                            |
+| `session`     | `Session \| null`        | Current auth session                         |
+| `collections` | `CollectionsAPI`         | Typed collection API                         |
+| `queue`       | `QueueClient`            | Queue client                                 |
+| `email`       | `MailerService`          | Email service                                |
+| `services`    |                          | User-defined services                        |
+| _extensions_  |                          | `appConfig({ context })` result, flat        |
 
 Route handlers must return a `Response` object.
 
@@ -279,27 +313,66 @@ Route handlers must return a `Response` object.
 
 **Rule of thumb**: Use JSON routes for typed input/output with automatic validation. Use raw routes for HTTP-level control (custom headers, binary data, streams, signature verification).
 
-### Webhook Example
+### Webhook Example (Signature Verification)
+
+Webhooks need the raw body for signature verification — exactly what `.raw()` is for:
 
 ```ts
 // routes/webhooks/stripe.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 
-export default route({
-	method: "POST",
-	handler: async ({ request, db }) => {
+export default route()
+	.post()
+	.raw()
+	.access(true) // signature IS the auth — verify it yourself below
+	.handler(async ({ request, collections, queue }) => {
 		const body = await request.text();
 		const signature = request.headers.get("stripe-signature");
-		const event = verifyStripeWebhook(body, signature);
+		const event = verifyStripeWebhook(body, signature); // throws on bad signature
+		if (!event) return new Response("Invalid signature", { status: 401 });
 
-		await db.insert(webhookEvents).values({
+		await collections.webhook_events.create({
 			type: event.type,
 			payload: body,
 		});
+		await queue.processStripeEvent.publish({ eventId: event.id });
 
 		return new Response("OK", { status: 200 });
-	},
-});
+	});
+```
+
+### Streamed Response Example
+
+Raw routes can return any `Response`, including streams — CSV exports, server-sent progress, large file proxies:
+
+```ts
+// routes/export.ts
+import { route } from "questpie/services";
+
+export default route()
+	.get()
+	.raw()
+	.access(({ session }) => !!session)
+	.handler(async ({ collections }) => {
+		const { docs } = await collections.orders.find({ limit: 10_000 });
+
+		const stream = new ReadableStream({
+			start(controller) {
+				controller.enqueue("id,total,createdAt\n");
+				for (const order of docs) {
+					controller.enqueue(`${order.id},${order.total},${order.createdAt.toISOString()}\n`);
+				}
+				controller.close();
+			},
+		});
+
+		return new Response(stream, {
+			headers: {
+				"Content-Type": "text/csv; charset=utf-8",
+				"Content-Disposition": 'attachment; filename="orders.csv"',
+			},
+		});
+	});
 ```
 
 ## Services
@@ -310,8 +383,7 @@ Services are reusable units of logic injected into `AppContext` under the `servi
 
 ```ts
 // services/blog.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 const WORDS_PER_MINUTE = 200;
 
 function stripHtml(html: string): string {
@@ -372,7 +444,7 @@ Services are available via `services` destructuring in any handler:
 
 ```ts
 // services/stripe.ts
-import { service } from "questpie";
+import { service } from "questpie/services";
 import Stripe from "stripe";
 
 export default service({
@@ -385,8 +457,7 @@ export default service({
 
 ```ts
 // services/tenant-db.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export default service({
 	lifecycle: "request",
 	deps: ["db", "session"] as const,
@@ -403,8 +474,7 @@ Services can depend on other services and infrastructure via `deps`. Use `as con
 
 ```ts
 // services/analytics.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export default service({
 	deps: ["db", "logger"] as const,
 	create: ({ db, logger }) => {
@@ -449,7 +519,7 @@ Email templates are defined in `emails/` and discovered by codegen. Each templat
 
 ```ts
 // emails/appointment-confirmation.ts
-import { email } from "questpie";
+import { email } from "questpie/services";
 import { z } from "zod";
 
 export default email({
@@ -500,7 +570,7 @@ Email handlers receive the full `AppContext` for fetching data:
 
 ```ts
 // emails/weekly-digest.ts
-import { email } from "questpie";
+import { email } from "questpie/services";
 import { z } from "zod";
 
 export default email({

package/skills/questpie/references/crud-api.md

@@ -1,6 +1,6 @@
 ---
 name: questpie-core/crud-api
-description: QUESTPIE CRUD API find findOne create update delete count updateMany deleteMany query operators where filter sort orderBy pagination limit offset with select relations depth context accessMode collections globals client server typesafe
+description: QUESTPIE CRUD API find findOne create updateById updateMany updateBatch deleteById deleteMany restoreById count atomic conditional update claim optimistic locking query operators where filter sort orderBy pagination limit offset with select relations depth context accessMode collections globals client server typesafe
   - questpie-core
 ---
 
@@ -16,8 +16,7 @@ Inside any handler, `collections` and `globals` are injected via context. The cu
 
 ```ts
 // routes/get-published.ts
-import { route } from "questpie";
-
+import { route } from "questpie/services";
 export default route()
 	.get()
 	.handler(async ({ collections }) => {
@@ -47,6 +46,23 @@ const result = await app.collections.posts.find(
 
 ## Collection Operations
 
+One vocabulary on both surfaces (server CRUD and client SDK):
+
+| Concept | Method | Returns |
+| --- | --- | --- |
+| list (paginated) | `find(options)` | `{ docs: T[], totalDocs: number }` |
+| single by query | `findOne(options)` | `T \| null` |
+| count | `count(options)` | `number` |
+| create | `create(data)` | `T` |
+| update by id | `updateById({ id, data })` | `T` (throws notFound) |
+| bulk update by where | `updateMany({ where, data })` | `T[]` (winners) |
+| per-record batch | `updateBatch({ updates })` | `T[]` |
+| delete by id | `deleteById({ id })` | `{ success }` (throws notFound) |
+| bulk delete by where | `deleteMany({ where })` | `{ success, count }` |
+| restore by id | `restoreById({ id })` | `T` (softDelete only) |
+
+Deprecated aliases (removed in v4): server `update`/`delete` = bulk (`updateMany`/`deleteMany`); client `update`/`delete`/`restore` = by-id (`updateById`/`deleteById`/`restoreById`). Avoid them — the same names mean different things on each surface. Accessing a method that does not exist on server CRUD throws a `TypeError` listing valid methods (it does NOT return `undefined`).
+
 ### `find(options)`
 
 List documents with filtering, sorting, and pagination.
@@ -91,58 +107,111 @@ const post = await collections.posts.create({
 // post: T (created record with id)
 ```
 
-### `update(options)`
+### `updateById(options)`
 
-Update a document matching `where`. Pass changed fields in `data`.
+Update a single document by id. Returns the updated record; throws `notFound` if the record does not exist (or vanished concurrently).
 
 ```ts
-const updated = await collections.posts.update({
-	where: { id: "abc-123" },
+const updated = await collections.posts.updateById({
+	id: "abc-123",
 	data: { status: "published" },
 });
 // updated: T (updated record)
 ```
 
-### `delete(options)`
+### `updateMany(options)`
 
-Delete documents matching `where`.
+Bulk update all documents matching `where`. Returns an **array** of the updated records — never a single object.
 
 ```ts
-await collections.posts.delete({
-	where: { id: "abc-123" },
+const updated = await collections.posts.updateMany({
+	where: { status: "draft" },
+	data: { status: "archived" },
 });
+// updated: T[] — exactly the rows that were written
 ```
 
-### `count(options)`
+`updateMany` is claim-checked: inside the write transaction the matched rows are locked and `where` is re-evaluated, so rows changed by a concurrent writer are skipped instead of silently overwritten. The returned array reports exactly the winners.
 
-Count documents matching a filter.
+#### Atomic conditional updates (claims, optimistic locking)
+
+Use a conditional `where` + the array length as the win/lose signal:
 
 ```ts
-const total = await collections.posts.count({
-	where: { status: "published" },
-});
-// total: number
+// Claim: of two parallel claims, EXACTLY ONE wins
+const claimed = await collections.event_members.updateMany(
+	{
+		where: { id: memberId, user: { isNull: true } },
+		data: { user: newUserId },
+	},
+	{ accessMode: "system" },
+);
+if (claimed.length === 0) {
+	// Lost the race (or row vanished) — handle explicitly
+}
+
+// Optimistic concurrency: write only if the revision is unchanged
+const bumped = await collections.documents.updateMany(
+	{ where: { id, revision: doc.revision }, data: { body, revision: doc.revision + 1 } },
+	ctx,
+);
+if (bumped.length === 0) throw new Error("Conflict — reload and retry");
 ```
 
-### `updateMany(options)`
+Hook timing: `beforeValidate`/`beforeChange` run before the transaction on candidates (intent — may fire for losers); `afterChange`, versioning, and the return value are winners-only (fact).
 
-Bulk update all documents matching `where`.
+### `updateBatch(options)`
+
+Distinct data per record, one transaction.
 
 ```ts
-await collections.posts.updateMany({
-	where: { status: "draft" },
-	data: { status: "archived" },
+const updated = await collections.posts.updateBatch({
+	updates: [
+		{ id: "a", data: { order: 1 } },
+		{ id: "b", data: { order: 2 } },
+	],
 });
+// updated: T[]
+```
+
+### `deleteById(options)`
+
+Delete a single document by id (soft delete when enabled). Throws `notFound` if missing.
+
+```ts
+await collections.posts.deleteById({ id: "abc-123" });
+// { success: true }
 ```
 
 ### `deleteMany(options)`
 
-Bulk delete all documents matching `where`.
+Bulk delete all documents matching `where`. Claim-checked like `updateMany` — `count` is the number of rows that still matched at delete time.
 
 ```ts
-await collections.posts.deleteMany({
+const result = await collections.posts.deleteMany({
 	where: { status: "archived" },
 });
+// result: { success: true, count: number }
+```
+
+### `restoreById(options)`
+
+Restore a soft-deleted document (collections with `softDelete: true`).
+
+```ts
+const restored = await collections.posts.restoreById({ id: "abc-123" });
+// restored: T
+```
+
+### `count(options)`
+
+Count documents matching a filter.
+
+```ts
+const total = await collections.posts.count({
+	where: { status: "published" },
+});
+// total: number
 ```
 
 ## Global Operations
@@ -204,6 +273,20 @@ const result = await collections.posts.find({
 });
 ```
 
+Multi-field sorting: order determines priority (first = primary sort). All
+three syntaxes work, including inside relation `with` options:
+
+```ts
+// Array syntax (preferred for explicit priority)
+orderBy: [{ status: "desc" }, { createdAt: "desc" }]
+
+// Object syntax (key order = priority)
+orderBy: { status: "desc", createdAt: "desc" }
+
+// Function syntax
+orderBy: (table, { asc, desc }) => [desc(table.status), asc(table.title)]
+```
+
 ## Pagination
 
 Use `limit` and `offset`:
@@ -216,6 +299,38 @@ const page2 = await collections.posts.find({
 // page2.totalDocs = total count across all pages
 ```
 
+### Keyset (cursor) pagination
+
+For stable pagination over changing data, use a tuple cursor of
+`(createdAt, id)` with a matching multi-field `orderBy`. System timestamps
+are stored with millisecond precision (`timestamp(3)`), so a `Date` you read
+back equals the stored value exactly — cursor comparisons are exact:
+
+```ts
+const page = await collections.posts.find({
+	where: cursor
+		? {
+				OR: [
+					{ createdAt: { lt: cursor.createdAt } },
+					{
+						AND: [
+							{ createdAt: { eq: cursor.createdAt } },
+							{ id: { lt: cursor.id } },
+						],
+					},
+				],
+			}
+		: undefined,
+	orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+	limit: 20,
+});
+const last = page.docs.at(-1);
+const nextCursor = last ? { createdAt: last.createdAt, id: last.id } : null;
+```
+
+Always use the explicit `{ eq: ... }` operator for `Date` cursor values —
+do not pass a bare `Date` as an equality shorthand.
+
 ## Relations
 
 Relations are NOT populated by default. Use `with` to eager-load:
@@ -252,9 +367,46 @@ export default route()
 	});
 ```
 
+### Partial Overrides (Inside Request Scope)
+
+The optional second argument of every CRUD call merges with the ambient request scope. Priority: **explicit param → ALS scope (`runWithContext`) → defaults** (`accessMode: "system"`, `locale: "en"`). A bare `{ accessMode: "system" }` elevates only the mode — the request's `session`, `db`, and `locale` ride along automatically. The inverse holds too:
+
+```ts
+// Inside any handler / hook / Better Auth callback:
+await collections.posts.updateMany(
+	{ where: { author: oldId }, data: { author: newId } },
+	{ accessMode: "system" }, // mode elevated; session/db/locale inherited
+);
+
+await collections.posts.find({}, { accessMode: "user" }); // rules re-enabled against inherited session
+```
+
+Never re-thread `session`/`locale` by hand when you only want a different access mode.
+
+### Transactions
+
+`withTransaction(db, fn)` (from `questpie`) runs multiple CRUD calls atomically — calls inside the callback inherit the transaction connection through the ALS scope, and nested `withTransaction` calls reuse the open transaction. Queue side effects for after COMMIT with `onAfterCommit`:
+
+```ts
+import { onAfterCommit, withTransaction } from "questpie";
+
+await withTransaction(db, async () => {
+	const order = await collections.orders.create({ ... });
+	await collections.inventory.updateMany({
+		where: { sku: order.sku, status: "available" },
+		data: { status: "reserved" },
+	});
+	onAfterCommit(async () => {
+		await queue.notifyWarehouse.publish({ orderId: order.id });
+	});
+});
+```
+
+Do not run output-hook-heavy reads (blocks/upload `afterRead`) inside an open transaction unless necessary — they inherit the tx connection too.
+
 ### In Scripts / Seeds
 
-Create an explicit context with `app.createContext()`:
+Outside any request scope, create an explicit context with `app.createContext()`:
 
 ```ts
 // System mode -- bypasses all access control
@@ -266,22 +418,44 @@ const ctx = await app.createContext({ accessMode: "user" });
 
 ## Client API
 
-The client SDK mirrors server operations:
+The client SDK uses the same vocabulary:
 
 ```ts
 const posts = await client.collections.posts.find({ limit: 10 });
 const post = await client.collections.posts.findOne({ where: { id: "abc" } });
 const created = await client.collections.posts.create({ title: "New" });
-const updated = await client.collections.posts.update({
+const updated = await client.collections.posts.updateById({
 	id: "abc",
 	data: { title: "Updated" },
 });
-await client.collections.posts.delete({ id: "abc" });
+await client.collections.posts.deleteById({ id: "abc" });
+const many = await client.collections.posts.updateMany({
+	where: { status: "draft" },
+	data: { status: "review" },
+});
+await client.collections.posts.deleteMany({ where: { status: "archived" } });
 const count = await client.collections.posts.count({
 	where: { status: "draft" },
 });
 ```
 
+### Live Queries (Client Only)
+
+Every read has a live form — `live()` mirrors `find()` (same options, same snapshot type) and pushes access-controlled snapshots over SSE. Globals mirror `get()`: `client.globals.<name>.live(...)`. See AGENTS.md §19 Realtime:
+
+```ts
+const stop = client.collections.posts.live(
+	{ where: { status: "published" }, with: { author: true } },
+	(snap) => render(snap.docs), // typed find() result
+);
+stop(); // unsubscribe
+
+// AsyncGenerator form (workers, agents, tests)
+for await (const snap of client.collections.posts.liveIter({ limit: 10 })) {
+	render(snap.docs);
+}
+```
+
 ### Upload (Client Only)
 
 For upload collections:
@@ -363,6 +537,34 @@ export default route()
 	});
 ```
 
+### HIGH: Expecting updateMany() to return a single record
+
+Server bulk update returns an **array** of updated records:
+
+```ts
+// WRONG -- updateMany returns T[], not T
+const updated = await collections.posts.updateMany({
+	where: { id: "abc" },
+	data: { status: "published" },
+});
+console.log(updated.status); // undefined!
+
+// CORRECT
+const [updated] = await collections.posts.updateMany({
+	where: { id: "abc" },
+	data: { status: "published" },
+});
+// or, for a single record by id:
+const updated2 = await collections.posts.updateById({
+	id: "abc",
+	data: { status: "published" },
+});
+```
+
+### HIGH: `update`/`delete` mean different things on server vs client
+
+On server CRUD, `update`/`delete` are deprecated aliases of the BULK operations (`{ where, data }` → `T[]`). On the client SDK they are by-id operations (`{ id, data }` → `T`). Always use the unambiguous names: `updateById`/`deleteById`/`restoreById` for single records, `updateMany`/`deleteMany` for bulk. Calling a method that does not exist (e.g. a typo) on server CRUD throws a `TypeError` listing the valid methods.
+
 ### MEDIUM: Wrong create() signature
 
 `create()` takes a flat data object, NOT `{ data: {...} }`:
@@ -375,4 +577,4 @@ await collections.posts.create({ data: { title: "Hello" } });
 await collections.posts.create({ title: "Hello", body: "World" });
 ```
 
-Note: `update()` DOES use `{ where, data }` -- only `create()` is flat.
+Note: `updateById()`/`updateMany()` DO use `{ id/where, data }` -- only `create()` is flat.