Merge pull request #256 from better-stack-ai/v3

Release Better Stack v3.0.0

Author: olliethedev

.agents/skills/btst-backend-plugin-dev/REFERENCE.md

@@ -3,85 +3,45 @@
 ## defineBackendPlugin shape (api/plugin.ts)
 
 ```typescript
-import type { DBAdapter as Adapter } from "@btst/db"
-import { defineBackendPlugin, createEndpoint } from "@btst/stack/plugins/api"
-import { z } from "zod"
-import { dbSchema } from "./db-schema"
-import { listItems, getItemById } from "./getters"
-import { createItem, updateItem, deleteItem } from "./mutations"
-
-const ItemQuerySchema = z.object({ limit: z.coerce.number().optional() })
-const CreateItemSchema = z.object({ name: z.string() })
-
-export const myBackendPlugin = defineBackendPlugin({
-  name: "my-plugin",
-  dbPlugin: dbSchema,
-
-  // api factory — bound to shared adapter, no HTTP context
-  api: (adapter: Adapter) => ({
-    listItems: () => listItems(adapter),
-    getItemById: (id: string) => getItemById(adapter, id),
-    createItem: (data: CreateItemInput) => createItem(adapter, data),
-  }),
-
-  // routes factory — HTTP endpoints built with createEndpoint
-  routes: (adapter: Adapter) => {
-    const listItemsEndpoint = createEndpoint(
-      "/items",
-      { method: "GET", query: ItemQuerySchema },
-      async (ctx) => {
-        return await listItems(adapter)
-      },
-    )
-
-    const createItemEndpoint = createEndpoint(
-      "/items",
-      { method: "POST", body: CreateItemSchema },
-      async (ctx) => {
-        return await createItem(adapter, ctx.body)
-      },
-    )
-
-    const getItemEndpoint = createEndpoint(
-      "/items/:id",
-      { method: "GET" },
-      async (ctx) => {
-        const item = await getItemById(adapter, ctx.params.id)
-        if (!item) throw ctx.error(404, { message: "Item not found" })
-        return item
-      },
-    )
-
-    return { listItems: listItemsEndpoint, createItem: createItemEndpoint, getItem: getItemEndpoint } as const
-  },
-})
-
-// Router type for client consumption
-export type MyApiRouter = ReturnType<ReturnType<typeof myBackendPlugin>["routes"]>
-```
-
-### ctx object inside createEndpoint handlers
+/** Configuration accepted by `myBackendPlugin`. */
+export interface MyBackendPluginOptions {
+  /** Lifecycle callbacks composed around plugin operations. */
+  hooks?: MyBackendHooks
+}
 
-| Property | Description |
-|---|---|
-| `ctx.query` | Validated query params (when `query:` schema provided) |
-| `ctx.body` | Validated request body (when `body:` schema provided) |
-| `ctx.params` | URL path params (e.g. `:id` → `ctx.params.id`) |
-| `ctx.headers` | Request `Headers` object |
-| `ctx.request` | Raw `Request` object |
-| `ctx.error(status, { message })` | Create an HTTP error — always `throw` the result |
+export const myBackendPlugin = (options: MyBackendPluginOptions = {}) =>
+  defineBackendPlugin({
+    id: "myPlugin",
+    dbPlugin: dbSchema,
+    operations: (adapter) => createMyOperations(adapter, options.hooks),
+    raw: (adapter) => ({
+      prefetchForRoute: createItemPrefetchForRoute(adapter),
+    }),
+    routes: (_adapter, _context, operations) => {
+      const createItem = createEndpoint(
+        "/items",
+        { method: "POST", body: CreateItemSchema, requireRequest: true },
+        operations.createItem.route((ctx) => ctx.body),
+      )
+      return { createItem } as const
+    },
+  })
 
----
+/** Inferred router contract imported by the client plugin. */
+export type MyApiRouter = ReturnType<
+  ReturnType<typeof myBackendPlugin>["routes"]
+>
+```
 
 ## getters.ts
 
-Pure DB functions — no HTTP context, no lifecycle hooks, always accept `adapter` as first arg:
+Lower-level DB functions — no HTTP context or lifecycle composition, always accept `adapter` as first arg:
 
 ```typescript
 import type { DBAdapter as Adapter } from "@btst/db"
 import type { Item } from "./types"
 
-// Authorization hooks are NOT called — callers are responsible for access control
+// Lower-level primitive: callers own validation and lifecycle composition.
 export async function listItems(adapter: Adapter): Promise<Item[]> {
   return adapter.findMany({ model: "item" })
 }
@@ -95,15 +55,15 @@ export async function getItemById(adapter: Adapter, id: string): Promise<Item |
 
 ## mutations.ts
 
-Write operations — no auth hooks, no HTTP context. JSDoc disclaimer required:
+Write operations — no HTTP context or lifecycle composition. JSDoc disclaimer required:
 
 ```typescript
 import type { DBAdapter as Adapter } from "@btst/db"
 import type { CreateItemInput, Item } from "./types"
 
 /**
  * Create a new item directly in the database.
- * Authorization hooks are NOT called — caller is responsible for access control.
+ * Lower-level primitive: caller owns validation and lifecycle composition.
  */
 export async function createItem(adapter: Adapter, data: CreateItemInput): Promise<Item> {
   return adapter.create({
@@ -114,7 +74,7 @@ export async function createItem(adapter: Adapter, data: CreateItemInput): Promi
 
 /**
  * Update an existing item.
- * Authorization hooks are NOT called — caller is responsible for access control.
+ * Lower-level primitive: caller owns validation and lifecycle composition.
  */
 export async function updateItem(
   adapter: Adapter,
@@ -126,7 +86,7 @@ export async function updateItem(
 
 /**
  * Delete an item.
- * Authorization hooks are NOT called — caller is responsible for access control.
+ * Lower-level primitive: caller owns validation and lifecycle composition.
  */
 export async function deleteItem(adapter: Adapter, id: string): Promise<void> {
   await adapter.delete({ model: "item", where: { id } })
@@ -140,10 +100,10 @@ export async function deleteItem(adapter: Adapter, id: string): Promise<void> {
 Re-export getters and mutations for direct server-side import (SSG, scripts, AI tools):
 
 ```typescript
-// Getters — read-only, no auth hooks
+// Getters — read-only lower-level primitives
 export { listItems, getItemById } from "./getters"
 
-// Mutations — write ops, no auth hooks
+// Mutations — write lower-level primitives
 export { createItem, updateItem, deleteItem } from "./mutations"
 
 // Types for consumers
@@ -154,52 +114,26 @@ export { serializeItem } from "./serializers"
 
 ---
 
-## Lifecycle hook implementation in routes
+## Lifecycle hooks in operations
 
-```typescript
-routes: (adapter: Adapter) => {
-  const createItemEndpoint = createEndpoint(
-    "/items",
-    { method: "POST", body: CreateItemSchema },
-    async (ctx) => {
-      const context = { body: ctx.body, headers: ctx.headers }
-
-      // before hook — throw to deny
-      await ctx.hooks?.onBeforeItemCreated?.(ctx.body, context)
-
-      const item = await createItem(adapter, ctx.body)
-
-      // after hook — fire and forget or await
-      await ctx.hooks?.onAfterItemCreated?.(item, context)
-
-      return item
-    },
-  )
-
-  return { createItem: createItemEndpoint } as const
-},
-```
-
-Hook naming always follows: `onBefore{Entity}{Action}`, `onAfter{Entity}{Action}`, `on{Entity}{Action}Error`.
-
----
+Invoke domain hooks from the operation lifecycle after authorization. Hooks can enforce domain invariants, publish side effects, and observe errors; they are not the authorization policy.
 
-## Plugin stack() wiring (in stack.ts)
+## Plugin `createBackendStack()` wiring (in stack.ts)
 
 ```typescript
-import { stack } from "@btst/stack"
+import { createBackendStack } from "@btst/stack/api"
 import { myBackendPlugin } from "./src/plugins/my-plugin/api/plugin"
 
-export const myStack = stack({
+export const myStack = createBackendStack({
   basePath: "/api/data",
   plugins: {
-    myPlugin: myBackendPlugin,
+    myPlugin: myBackendPlugin(),
   },
   adapter: (db) => createDrizzleAdapter(schema, db, {}),
 })
 
 export const { handler, dbSchema } = myStack
 
-// Direct server-side access (bypasses auth hooks):
-const items = await myStack.api.myPlugin.listItems()
+// Explicitly trusted business access keeps validation and lifecycle hooks:
+const item = await myStack.trusted.myPlugin.createItem({ name: "Scheduled item" })
 ```

.agents/skills/btst-backend-plugin-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: btst-backend-plugin-dev
-description: Patterns for writing BTST backend plugins inside the monorepo, including defineBackendPlugin structure, getters.ts/mutations.ts separation, the api factory, lifecycle hook naming conventions, and accessing the adapter in AI tool execute functions. Use when creating or modifying a backend plugin, adding DB getters or mutations, wiring the api factory, or implementing lifecycle hooks in src/plugins/{name}/api/.
+description: Patterns for writing BTST backend plugins inside the monorepo, including operation-first authorization, getters.ts/mutations.ts separation, lifecycle hooks, and narrow SSG raw factories. Use when creating or modifying a backend plugin, adding DB getters or mutations, operations, permission descriptors, or lifecycle hooks in src/plugins/{name}/api/.
 ---
 
 # BTST Backend Plugin Development
@@ -12,19 +12,21 @@ src/plugins/{name}/
   api/
     plugin.ts        ← defineBackendPlugin entry
     getters.ts       ← read-only DB functions (no HTTP context)
-    mutations.ts     ← write DB functions (no auth hooks)
+    mutations.ts     ← lower-level write DB functions
+    operations.ts    ← validated operations, permission facts, lifecycle
     index.ts         ← re-exports getters + mutations + types
   query-keys.ts      ← React Query key factory
 ```
 
 ## Rules
 
 - **`getters.ts`** — pure async DB functions only. No HTTP context, no lifecycle hooks. Always takes `adapter` as first arg.
-- **`mutations.ts`** — write operations (create/update/delete). No auth hooks, no HTTP context. Add JSDoc: "Authorization hooks are NOT called."
+- **`mutations.ts`** — lower-level write primitives. No HTTP context or lifecycle composition. Document that callers own validation and lifecycle.
 - **`api/index.ts`** — re-export everything from getters + mutations for direct server-side import.
-- The `api` factory and `routes` factory share the same adapter instance — bind getters inside the factory, don't pass adapter at call site.
-- If the plugin has a one-time init step (e.g. `syncContentTypes`), call it inside each getter/mutation wrapper — not only inside `routes`.
-- **Never** use `myStack.api.*` as a substitute for authenticated HTTP endpoints — auth hooks are not called.
+- **`operations.ts`** — define the one maintained business inventory with input validation, exact permission descriptors, authoritative facts, domain execution, and lifecycle hooks.
+- Bind HTTP routes to same-key operations. Use `operationRouteMap` only for real route-name mismatches.
+- The optional `raw` factory is narrow: first-party plugins expose only `prefetchForRoute` for SSG. Do not duplicate business getters or mutations on `createBackendStack().raw`.
+- Use `myStack.forRequest(request).operations.*` for request work and `myStack.trusted.*` for explicitly trusted jobs.
 
 ## Key patterns
 
@@ -38,30 +40,37 @@ src/plugins/{name}/
 
 ## Lifecycle hook naming
 
-Pattern: `onBefore{Entity}{Action}`, `onAfter{Entity}{Action}`, `on{Entity}{Action}Error`
+Pattern: `onBefore{Action}{Entity}`, `onAfter{Action}{Entity}`, `onError{Action}{Entity}`
 
 ```typescript
-// Examples from existing plugins:
-onBeforeListPosts, onPostsRead, onListPostsError
-onBeforeCreatePost, onPostCreated, onCreatePostError
-onBeforeUpdatePost, onPostUpdated, onUpdatePostError
-onBeforeDeletePost, onPostDeleted, onDeletePostError
-onBeforePost, onAfterPost          // comments plugin (create comment)
-onBeforeEdit, onAfterEdit          // comments plugin (edit comment)
-onBeforeDelete, onAfterDelete      // comments plugin (delete comment)
-onBeforeStatusChange, onAfterApprove
+onBeforeListPosts, onAfterListPosts, onErrorListPosts
+onBeforeCreatePost, onAfterCreatePost, onErrorCreatePost
+onBeforeUpdatePost, onAfterUpdatePost, onErrorUpdatePost
+onBeforeDeletePost, onAfterDeletePost, onErrorDeletePost
+
+// Preserve meaningful domain events instead of inventing CRUD phases.
+onBeforeChat, onAfterChat, onErrorChat
+onBeforeActivateTools
 ```
 
-## Adapter in AI tool execute functions
+Normalize names without adding lifecycle phases that the plugin does not
+already support.
+
+## Trusted operations in AI tool execute functions
 
 `myStack` is a module-level const. The `execute` closure runs lazily (only on HTTP request), so `myStack` is always initialised by then:
 
 ```typescript
-export const myStack = stack({ ... })
+import { createBackendStack } from "@btst/stack/api"
+
+export const myStack = createBackendStack({ ... })
 
 const myTool = tool({
   execute: async (params) => {
-    await createKanbanTask(myStack.adapter, { title: params.title, columnId: "col-id" })
+		await myStack.trusted.kanban.createTask({
+			title: params.title,
+			columnId: "col-id",
+		})
     return { success: true }
   }
 })
@@ -73,8 +82,8 @@ const myTool = tool({
 - **Wrong adapter type** — use `import type { DBAdapter as Adapter } from "@btst/db"` in getters/mutations/plugin files.
 - **`"GET /path"` string keys** — routes use `createEndpoint()`, not string-keyed method/path objects.
 - **`ctx.json()`** — does not exist; return data directly from route handlers.
-- **`stack().api` bypasses auth hooks** — never use for authenticated data access; enforce auth at the call site.
-- **Plugin init not called via `api`** — if `routes` factory runs a setup (e.g. `syncContentTypes`), also await it inside each `api` getter wrapper.
+- **Business methods on `createBackendStack().raw`** — do not add them. Keep the composed lifecycle explicit through `forRequest(request).operations` or `trusted`, and reserve `raw` for narrow lower-level/SSG helpers.
+- **Authorization in lifecycle hooks** — routine access control belongs in operation descriptors and the one shared rule. Hooks receive already-authorized context.
 - **Write ops in `getters.ts`** — write functions belong in `mutations.ts`, not `getters.ts`.
 
 ## Full code patterns