@voltro/cli 0.1.0

package/templates/apps/api-rest/app.config.ts

@@ -0,0 +1,70 @@
+// Api app config — a PUBLIC REST API. Read by `voltro dev`.
+//
+// What's wired here:
+//   • restRoutes  — the four `defineRestRoute` descriptors, registered
+//     EXPLICITLY (REST routes are the one primitive that is NOT auto-
+//     discovered — they're opt-in public HTTP surface).
+//   • openapiPlugin — generates an OpenAPI 3.1 spec from those same
+//     descriptors and serves it at GET /openapi.json + a Swagger UI at /docs.
+//     Zero hand-maintained API docs: the descriptors ARE the spec.
+//   • auth.strategies — an apiKeyStrategy so `Authorization: Bearer <key>`
+//     resolves to a scoped Subject. The guarded routes gate on those scopes.
+//   • idempotency — POST/PUT/PATCH/DELETE carrying `Idempotency-Key` are
+//     deduplicated (replay the first response; 409 while in-flight).
+//
+// `store: 'memory'` keeps first-run zero-infra (no docker). Data resets on
+// every restart — switch to `store: 'postgres'` (+ a local postgres) for
+// anything real.
+
+import { apiKeyStrategy } from '@voltro/protocol/apikey'
+import { openapiPlugin } from '@voltro/plugin-openapi'
+import listProducts   from './routes/v1/products.list.route'
+import getProduct     from './routes/v1/products.get.route'
+import createProduct  from './routes/v1/products.create.route'
+import deleteProduct  from './routes/v1/products.delete.route'
+
+// The descriptors, in one array — handed to BOTH `restRoutes` (to mount them)
+// and `openapiPlugin` (to document them).
+const routes = [listProducts, getProduct, createProduct, deleteProduct]
+
+// ─── DEV ONLY ────────────────────────────────────────────────────────────
+// A single hardcoded API key so the guarded routes work the moment you boot:
+//
+//   curl -H 'Authorization: Bearer restdemo_devkey' ...
+//
+// The strategy SHA-256-hashes the full bearer token and hands the hash to
+// `resolveKey`; we match it to a fixed scoped Subject. In PRODUCTION, delete
+// the constant below and look the hash up against your own key store (apps
+// store key HASHES, never raw tokens) — or flip on the framework's first-
+// class `apiKeys: true` for admin-gated issue/list/revoke against
+// `_voltro_api_keys`. This demo key is the moral equivalent of a sample
+// password in a README: fine for a starter, never for a real deployment.
+const DEMO_KEY_SHA256 = 'c8917896a6fbdd429ca2410e6e1958953d7421393f649d44fe8fc88c267441cd' // sha256('restdemo_devkey')
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  auth: {
+    strategies: [
+      apiKeyStrategy({
+        prefix: 'restdemo_',
+        resolveKey: (hash) =>
+          hash === DEMO_KEY_SHA256
+            ? { id: 'svc_demo', tenantId: 'acme', scopes: ['products:read', 'products:write'] }
+            : null,
+      }),
+    ],
+  },
+  plugins: [
+    openapiPlugin({
+      routes,
+      info: { title: '{{capProjectName}} API', version: '1.0.0' },
+      // specPath: '/openapi.json' (default) · docsPath: '/docs' (default)
+    }),
+  ],
+  // Public REST endpoints — registered explicitly, NOT auto-discovered.
+  restRoutes: routes,
+  // Idempotency-Key dedup for the mutating routes (records in _voltro_idempotency).
+  idempotency: true,
+}

package/templates/apps/api-rest/database/schema.ts

@@ -0,0 +1,52 @@
+// Schema for the {{projectName}} public-REST backend.
+//
+// `products` is a plain catalog table the REST routes read + write. It
+// intentionally carries NO mixins — a public REST surface is usually a
+// separate, explicitly-scoped API (the routes own their auth + filtering),
+// so we keep the row shape flat and write `id` / `createdAt` by hand in the
+// handler. (For the tenant()-scoped, reactive-over-WebSocket shape, see the
+// `api-backend` template.)
+//
+// `actors` + `tenants` are the framework's core tables — declared for
+// convention parity even though no mixin references them here.
+
+import {
+  databaseHandle,
+  id,
+  integer,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+
+// ---------- Core tables ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application table ----------
+
+export const products = table('products', {
+  id:         id({ prefix: 'prod' }),
+  name:       text(),
+  priceCents: integer(),
+  createdAt:  timestamp().default('now'),
+})
+  // Opt into the matcher engine so a future reactive WS query over the
+  // same table stays live. The REST routes don't need it, but it's free.
+  .reactive()
+
+export type Product = InferRow<typeof products>
+
+export const database = databaseHandle({ actors, tenants, products })

package/templates/apps/api-rest/lib/product.ts

@@ -0,0 +1,30 @@
+// Shared wire-shape for a product + a row→wire mapper.
+//
+// Imported by every `*.route.tsx` AND by `openapiPlugin({ routes })` (both
+// server-side — REST route files are NOT pulled into the browser rpcGroup,
+// so they're free to import server modules). One source of truth means the
+// generated OpenAPI schema and the runtime encode can never disagree.
+
+import { Schema } from 'effect'
+
+export const Product = Schema.Struct({
+  id:         Schema.String,
+  name:       Schema.String,
+  priceCents: Schema.Number,
+  // ISO-8601 string on the wire (we stringify the Date in the mapper below).
+  createdAt:  Schema.String,
+})
+export type Product = Schema.Schema.Type<typeof Product>
+
+/**
+ * Coerce a raw store row into the wire shape. Two store-path quirks this
+ * absorbs: a `timestamp` column can come back as a `Date` OR an ISO string,
+ * and an `integer` column can come back as a STRING on some dialects — so we
+ * normalise both before the strict output Schema encodes them.
+ */
+export const toProduct = (r: Record<string, unknown>): Product => ({
+  id:         r['id'] as string,
+  name:       r['name'] as string,
+  priceCents: Number(r['priceCents']),
+  createdAt:  r['createdAt'] instanceof Date ? r['createdAt'].toISOString() : String(r['createdAt']),
+})

package/templates/apps/api-rest/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/plugin-openapi": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-rest/routes/v1/products.create.route.tsx

@@ -0,0 +1,45 @@
+// POST /v1/products  — create a product. GUARDED + IDEMPOTENT.
+//
+// - `guards: [requireScope('products:write')]` → 403 unless the resolved
+//   Subject carries that scope. The app's `apiKeyStrategy` (see app.config)
+//   maps the demo bearer token to a subject WITH the scope; an anonymous
+//   caller is rejected.
+// - `idempotency: true` in app.config makes a POST carrying an
+//   `Idempotency-Key` header replay-safe: a retry with the same key replays
+//   the first response instead of inserting twice.
+//
+// The `body` is parsed from the JSON request body and decoded against the
+// `body` sub-schema (a bad shape → 400 before the handler runs).
+
+import { defineRestRoute, requireScope } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+import { randomUUID } from 'node:crypto'
+import type { DataStore } from '@voltro/runtime'
+import { Product, toProduct } from '../../lib/product'
+
+export default defineRestRoute({
+  method: 'POST',
+  path:   '/v1/products',
+  input: Schema.Struct({
+    body: Schema.Struct({
+      name:       Schema.NonEmptyString,
+      priceCents: Schema.Number.pipe(Schema.int(), Schema.greaterThanOrEqualTo(0)),
+    }),
+  }),
+  output:  Product,
+  summary: 'Create a product',
+  guards:  [requireScope('products:write')],
+  handler: async ({ body }, ctx) => {
+    const store = ctx.store as DataStore
+    // Explicit id + createdAt — the REST store path doesn't run the mutation
+    // middleware that auto-injects them, so we own them here.
+    const row = {
+      id:         `prod_${randomUUID().replace(/-/g, '')}`,
+      name:       body.name,
+      priceCents: body.priceCents,
+      createdAt:  new Date(),
+    }
+    await store.insert('products', row as never)
+    return toProduct(row)
+  },
+})

package/templates/apps/api-rest/routes/v1/products.delete.route.tsx

@@ -0,0 +1,25 @@
+// DELETE /v1/products/:id  — GUARDED. Deletes one product or 404.
+//
+// Same scope guard as create. `DELETE` is one of the idempotent methods the
+// `Idempotency-Key` dedup covers (app.config `idempotency: true`).
+
+import { defineRestRoute, requireScope } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+import type { DataStore } from '@voltro/runtime'
+
+export default defineRestRoute({
+  method: 'DELETE',
+  path:   '/v1/products/:id',
+  input: Schema.Struct({
+    params: Schema.Struct({ id: Schema.NonEmptyString }),
+  }),
+  output:  Schema.Struct({ id: Schema.String, deleted: Schema.Boolean }),
+  summary: 'Delete a product by id',
+  guards:  [requireScope('products:write')],
+  handler: async ({ params }, ctx) => {
+    const store = ctx.store as DataStore
+    const ok = await store.delete('products', params.id)
+    if (!ok) throw { status: 404, message: `product '${params.id}' not found` }
+    return { id: params.id, deleted: true }
+  },
+})

package/templates/apps/api-rest/routes/v1/products.get.route.tsx

@@ -0,0 +1,29 @@
+// GET /v1/products/:id  — public, one product or 404.
+//
+// `:id` is a PATH param — the desugar re-derives it from the matched pattern
+// into `params`. A handler `throw { status, message }` maps to that HTTP code;
+// anything else → 500.
+
+import { defineRestRoute } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+import { eq } from '@voltro/database'
+import type { DataStore } from '@voltro/runtime'
+import { database } from '../../database/schema'
+import { Product, toProduct } from '../../lib/product'
+
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/products/:id',
+  input: Schema.Struct({
+    params: Schema.Struct({ id: Schema.NonEmptyString }),
+  }),
+  output:  Product,
+  summary: 'Get a product by id',
+  handler: async ({ params }, ctx) => {
+    const store = ctx.store as DataStore
+    const rows = await store.query(database.products.where(eq('id', params.id)).limit(1).descriptor)
+    const row = rows[0]
+    if (row === undefined) throw { status: 404, message: `product '${params.id}' not found` }
+    return toProduct(row as Record<string, unknown>)
+  },
+})

package/templates/apps/api-rest/routes/v1/products.list.route.tsx

@@ -0,0 +1,43 @@
+// GET /v1/products?limit=&cursor=  — public, cursor-paginated list.
+//
+// The desugar parses the query string into the `query` shape and decodes it.
+// `Schema.NumberFromString` turns the string query param "20" into a number;
+// we clamp it in the handler. Cursor pagination keys off the sortable `prod_…`
+// TypeID (no OFFSET scan): pass the last row's id back as `cursor`.
+
+import { defineRestRoute } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+import { gt } from '@voltro/database'
+import type { DataStore } from '@voltro/runtime'
+import { database } from '../../database/schema'
+import { Product, toProduct } from '../../lib/product'
+
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/products',
+  input: Schema.Struct({
+    query: Schema.Struct({
+      limit:  Schema.optional(Schema.NumberFromString),
+      cursor: Schema.optional(Schema.String),
+    }),
+  }),
+  output: Schema.Struct({
+    data:       Schema.Array(Product),
+    nextCursor: Schema.NullOr(Schema.String),
+  }),
+  summary:     'List products',
+  description: 'Cursor-paginated. Pass the response `nextCursor` back as `cursor` for the next page.',
+  handler: async ({ query }, ctx) => {
+    const store = ctx.store as DataStore
+    const limit = Math.min(Math.max(query.limit ?? 20, 1), 100)
+
+    const base = query.cursor
+      ? database.products.where(gt('id', query.cursor))
+      : database.products
+    const rows = await store.query(base.orderBy('id', 'asc').limit(limit).descriptor)
+
+    const data = rows.map((r) => toProduct(r as Record<string, unknown>))
+    const nextCursor = data.length === limit ? data[data.length - 1]!.id : null
+    return { data, nextCursor }
+  },
+})

package/templates/apps/api-rest/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-rest",
+  "kind": "api",
+  "summary": "Public REST API: defineRestRoute endpoints (GET/POST/DELETE, query+path+body) + scope guards + Idempotency-Key + @voltro/plugin-openapi (Swagger UI at /docs).",
+  "tags": ["api", "rest", "openapi", "swagger", "public-api"]
+}

package/templates/apps/api-rest/tests/products.create.test.ts

@@ -0,0 +1,53 @@
+// Unit test with `@voltro/testing` — no database, no running HTTP server. A
+// `defineRestRoute` carries its logic in a plain `handler(input, ctx)`, so the
+// test calls that handler with a `RestRouteContext` built over the SAME
+// mixin-wrapped `ctx.store` a route gets at runtime, and asserts the wire shape
+// it returns. The REST routing + guard + idempotency layers are dispatch-time
+// concerns (integration), not exercised here. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { anonymousSubject } from '@voltro/protocol'
+import type { RestRouteContext } from '@voltro/protocol/rest'
+import { database } from '../database/schema'   // registers products / actors / tenants
+import createProduct from '../routes/v1/products.create.route'
+
+// A REST handler receives `{ subject, headers, store }` (not the full rpc
+// AppContext). Build that shape over the real test store so `store.insert`
+// runs the same mixin/validation path it does in production. `products` carries
+// no tenant() mixin, so the subject identity is irrelevant to the insert.
+const restCtx = (store: unknown): RestRouteContext => ({
+  subject: anonymousSubject(null),
+  headers: {},
+  store,
+})
+
+describe('POST /v1/products', () => {
+  it('inserts a product and returns the wire shape', async () => {
+    const ctx = makeTestContext({ store: mockStore({ products: [] }) })
+    const product = await createProduct.handler(
+      { body: { name: 'Widget', priceCents: 1999 } },
+      restCtx(ctx.store),
+    )
+
+    expect(product.name).toBe('Widget')
+    expect(product.priceCents).toBe(1999)
+    expect(product.id).toMatch(/^prod_/)          // handler-minted id
+    // `createdAt` is normalised to an ISO-8601 string by the row→wire mapper.
+    expect(typeof product.createdAt).toBe('string')
+    expect(Number.isNaN(Date.parse(product.createdAt))).toBe(false)
+  })
+
+  it('persists the row to the store (readable back through the descriptor)', async () => {
+    const ctx = makeTestContext({ store: mockStore({ products: [] }) })
+    const product = await createProduct.handler(
+      { body: { name: 'Gadget', priceCents: 500 } },
+      restCtx(ctx.store),
+    )
+
+    const rows = await ctx.store.query(database.products.descriptor)
+    expect(rows).toHaveLength(1)
+    expect(rows[0]!['id']).toBe(product.id)
+    expect(rows[0]!['name']).toBe('Gadget')
+  })
+})

package/templates/apps/api-rest/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-saas/README.md

@@ -0,0 +1,106 @@
+# {{capProjectName}} {{capAppName}} — the SaaS plugin bundle
+
+Four cross-cutting **SaaS plugins** wired turnkey, in one cohesive domain — the
+billing / notifications / analytics / presence slice of the framework end to
+end. A single `projects.create` mutation pulls three of them together.
+
+## What it demonstrates
+
+- **Billing** ([`@voltro/plugin-billing`](https://voltro.cloud/docs/plugins/overview)) —
+  subscriptions + entitlements over the in-memory `mock` provider. The `free`
+  plan caps `projects` at 3; `requireEntitlement(ctx, 'projects', 1)` gates the
+  create and fails typed **`EntitlementExceeded`** on the 4th.
+- **Notifications** ([`@voltro/plugin-notifications`](https://voltro.cloud/docs/plugins/overview)) —
+  one `NotificationService.send(...)` across channels + a durable in-app inbox.
+- **Analytics** ([`@voltro/plugin-analytics-postgres`](https://voltro.cloud/docs/plugins/overview)) —
+  `useAnalytics().track('project_created', …)`. Noop-safe out of the box; one
+  config line + a SQL store makes it durable (see below).
+- **Presence** ([`@voltro/plugin-presence`](https://voltro.cloud/docs/plugins/overview)) —
+  ephemeral "who's online": `presence.heartbeat` / `list` / `leave` + the
+  `usePresence(channel)` hook.
+
+Each plugin contributes its OWN routes + tables automatically — you wire them in
+`app.config.ts` and consume their services in handlers. Boots **zero-infra**
+(`store: 'memory'`).
+
+## The bundle, in one handler
+
+```ts
+// mutations/projects.create.mutation.server.ts (Effect-mode)
+yield* requireEntitlement(ctx, 'projects', 1)          // billing quota gate
+const row = yield* (yield* EffectStore).insert('projects', { name: input.name })
+yield* (yield* useAnalytics()).track({ name: 'project_created', subjectId: ctx.request.subject.id })
+yield* Effect.promise(() => (yield* NotificationService).send({
+  to: ctx.request.subject.id ?? 'system', category: 'project', title: 'Project created', body: `"${input.name}" is live.`,
+}))
+```
+
+## Run it
+
+```bash
+voltro dev .
+```
+
+`projects.create` / `projects.list` and the plugin routes (`billing.*`,
+`presence.*`, `notifications.*`) are rpc procedures — call them from a web app
+with `useMutation` / `useSubscription`, or over HTTP via the dev inspect endpoint:
+
+```bash
+# Create projects — the free plan allows 3
+for i in 1 2 3; do
+  curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+    -H 'content-type: application/json' \
+    -d "{\"tag\":\"projects.create\",\"input\":{\"name\":\"Project $i\"}}"
+done
+# → { "ok": true, "result": { "id": "proj_…", … } }
+
+# The 4th trips the billing entitlement
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"projects.create","input":{"name":"Project 4"}}'
+# → { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, … } }
+
+# Presence — announce yourself, then read the roster
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"presence.heartbeat","input":{"channel":"lobby"}}'
+```
+
+## Enable durable analytics
+
+`useAnalytics().track(...)` is noop-safe without a sink. To STORE + query events
+(`aggregate` / `timeseries` / `topN`), add a sink AND a SQL store — the
+postgres-lite sink needs a `SqlClient`:
+
+```ts
+// app.config.ts
+import { postgresAnalytics } from '@voltro/plugin-analytics-postgres'
+
+export default {
+  type: 'api' as const, name: 'AcmeApi',
+  store: 'postgres' as const,          // or 'sqlite' (file:./.voltro/db.sqlite)
+  analytics: postgresAnalytics(),       // events → _voltro_events
+  plugins: [ /* … */ ],
+}
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Real subscriptions / checkout | `billingPlugin({ provider: 'stripe', apiKey, webhookSecret, plans })` with real `priceId`s |
+| Email / Slack / SMS notifications | add `emailChannel()` / `webhookChannel()` / `smsChannel()` to `channels` |
+| Durable analytics + warehouse | `postgresAnalytics()` on postgres, or swap to `@voltro/plugin-clickhouse` / `@voltro/plugin-duckdb` at scale |
+| Live presence roster in the UI | subscribe a reactive query over `_voltro_presence`, or use `usePresence(channel)` |
+
+## Anti-patterns
+
+- **Authoring your own `notifications.*` / `billing.*` / `presence.*` procedures.**
+  The plugins own those tag namespaces — boot fails on a collision. Use the
+  plugin routes + services, don't hand-roll them.
+- **Expecting analytics to persist on `memory`.** The postgres-lite sink needs
+  a SqlClient. `track()` is reachable + safe on memory, but events only land in
+  `_voltro_events` once you wire a sink + a SQL store.
+- **Skipping the entitlement gate on a paid action.** A scope says "may you call
+  this"; an entitlement says "do you have quota left". A create-project action
+  needs the quota check — `requireEntitlement` is one line.

package/templates/apps/api-saas/app.config.ts

@@ -0,0 +1,51 @@
+// Api app config — the SaaS plugin bundle. Read by `voltro dev`.
+//
+// Four cross-cutting SaaS plugins, wired turnkey. Each contributes its own
+// routes + tables; the `projects.create` mutation pulls three of them together
+// (billing entitlement gate → analytics event → notification).
+//
+// `store: 'memory'` keeps first-run zero-infra. NOTE the analytics caveat below.
+
+import { billingPlugin } from '@voltro/plugin-billing'
+import { presencePlugin } from '@voltro/plugin-presence'
+import { notificationsPlugin, consoleChannel } from '@voltro/plugin-notifications'
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    // ── Billing ──────────────────────────────────────────────────────────
+    // Subscriptions + entitlements over a pluggable provider. 'mock' is the
+    // in-memory provider (no Stripe key) — great for dev. `plans` is the single
+    // source of tier→quota truth; the `free` default caps `projects` at 3, so
+    // the 4th `projects.create` fails typed `EntitlementExceeded`. Swap
+    // provider:'stripe' (+ STRIPE_SECRET_KEY) + real priceIds for production.
+    billingPlugin({
+      provider: 'mock',
+      plans: {
+        free: { entitlements: { projects: 3 } },
+        pro:  { priceId: 'price_demo_pro', entitlements: { projects: 'unlimited' } },
+      },
+    }),
+    // ── Notifications ────────────────────────────────────────────────────
+    // One `send` across channels + a durable in-app inbox (added automatically).
+    // consoleChannel() prints to stdout for dev; add email/webhook/sms/push for
+    // real delivery. Reach the inbox from the browser with useInbox()/useUnreadCount().
+    notificationsPlugin({ channels: [consoleChannel()] }),
+    // ── Presence ─────────────────────────────────────────────────────────
+    // Ephemeral "who's online" — presence.heartbeat / list / leave routes +
+    // the usePresence(channel) hook. Swept `_voltro_presence` table; cross-instance.
+    presencePlugin(),
+  ],
+
+  // ── Analytics ──────────────────────────────────────────────────────────
+  // `useAnalytics().track(...)` is called in projects.create and is NOOP-SAFE
+  // with no sink configured (it never crashes) — so the event API is reachable
+  // on the zero-infra memory store. To actually STORE + query events, add a
+  // sink AND a SQL store (the postgres-lite sink needs a SqlClient):
+  //
+  //   import { postgresAnalytics } from '@voltro/plugin-analytics-postgres'
+  //   store: 'postgres' as const,   // or 'sqlite' (file:./.voltro/db.sqlite)
+  //   analytics: postgresAnalytics(),   // events → _voltro_events; aggregate/timeseries/topN
+}

package/templates/apps/api-saas/database/schema.ts

@@ -0,0 +1,50 @@
+// Schema for the {{projectName}} SaaS backend.
+//
+// One tenant-scoped `projects` table — the SaaS plugins (billing entitlements,
+// notifications, analytics, presence) layer on top via `app.config.ts`; they
+// contribute their OWN tables (`_voltro_billing_*`, `notification_*`,
+// `_voltro_events`, `_voltro_presence`) automatically, so you don't declare them.
+//
+// `actors` + `tenants` are the framework's core tables (the audit / tenant
+// mixins reference them).
+
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application table ----------
+
+export const projects = table('projects', {
+  id:   id({ prefix: 'proj' }),
+  name: text(),
+})
+  // tenant() pulls audit() transitively → tenantId + createdAt / updatedAt /
+  // createdBy / updatedBy (auto-stamped). Creating a project is gated by the
+  // billing `projects` entitlement (see mutations/projects.create).
+  .with(tenant())
+  .reactive()
+
+export type Project = InferRow<typeof projects>
+
+export const database = databaseHandle({ actors, tenants, projects })

package/templates/apps/api-saas/mutations/projects.create.mutation.server.ts

@@ -0,0 +1,52 @@
+// One mutation, three plugins. Effect-mode so it can `yield*` the plugin
+// services the framework provides in the per-request stack:
+//
+//   1. BILLING       — requireEntitlement check-and-decrements the tenant's
+//                      `projects` quota (free = 3). Over quota → typed
+//                      EntitlementExceeded, the row is never written.
+//   2. ANALYTICS      — useAnalytics().track(...) records a `project_created`
+//                      event. Noop-safe with no sink configured (see app.config).
+//   3. NOTIFICATIONS  — NotificationService.send(...) drops a note in the
+//                      owner's in-app inbox + the console channel.
+
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore, useAnalytics } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+import { NotificationService } from '@voltro/plugin-notifications'
+
+const execute = (input: { name: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    // 1. Billing gate — fails closed (typed EntitlementExceeded) when the
+    //    tenant has no `projects` quota left. Runs BEFORE the write.
+    yield* requireEntitlement(ctx, 'projects', 1)
+
+    // 2. Write the row. `tenant()` auto-stamps tenantId + audit columns.
+    const store = yield* EffectStore
+    const row = yield* store.insert('projects', { name: input.name })
+
+    // 3. Analytics — fire-and-forget event.
+    const analytics = yield* useAnalytics()
+    yield* analytics.track({
+      name:      'project_created',
+      subjectId: ctx.request.subject.id,
+      properties: { name: input.name },
+    })
+
+    // 4. Notify the owner (in-app inbox + console).
+    const notify = yield* NotificationService
+    yield* Effect.promise(() => notify.send({
+      to:       ctx.request.subject.id ?? 'system',
+      category: 'project',
+      title:    'Project created',
+      body:     `"${input.name}" is live.`,
+    }))
+
+    return {
+      id:       row['id'] as string,
+      name:     row['name'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute