@softr/sdk 0.0.24 → 0.0.26-alpha-0

package/dist/routes/visibility.d.ts

@@ -139,4 +139,4 @@ type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
  */
 declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
 //#endregion
-export { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };
+export { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { auth } from "./auth/server.js";
-import { ds } from "./core/datasource.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/dist/server.js

@@ -1,5 +1,5 @@
 import { auth } from "./auth/server.js";
-import { ds } from "./core/datasource.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/package.json

@@ -1,15 +1,36 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.24",
+  "version": "0.0.26-alpha-0",
   "type": "module",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
-    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
-    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "bin": {
+    "softr-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
-  "files": ["dist", "skills", "!skills/_artifacts"],
-  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -41,7 +62,9 @@
       "optional": true
     }
   },
-  "keywords": ["tanstack-intent"],
+  "keywords": [
+    "tanstack-intent"
+  ],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -5,13 +5,13 @@ description: >-
   four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
-  visibility, the current user, reading records, writing records, or auth. Load
-  this when unsure which sub-skill applies, or when touching the wiring; each
-  sub-skill stands alone for its own task.
+  visibility, the current user, reading records, charts and metrics, writing
+  records, or auth. Load this when unsure which sub-skill applies, or when
+  touching the wiring; each sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 # Softr SDK core
@@ -21,7 +21,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
-> **CRITICAL**: `workflow.trigger` is exploratory. It exists on the entrypoints below and typechecks, but its endpoint is not final. Do not build a feature on it. Tell the user the capability is not ready and ask how they want to proceed.
+> **CRITICAL**: `workflow.trigger` and `integration.fetch` are exploratory. They exist on the entrypoints below and they typecheck, but their endpoints are not final. Do not build a feature on either of them. Tell the user the capability is not ready and ask how they want to proceed.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `reading-records` plus `routes-and-visibility`.
 
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineAction`, `defineVisibility`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -41,6 +41,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Add a route, or change who can see one | [routes-and-visibility/SKILL.md](./routes-and-visibility/SKILL.md) |
 | Read the signed-in visitor or what they may do | [current-user/SKILL.md](./current-user/SKILL.md) |
 | Fetch records from a datasource | [reading-records/SKILL.md](./reading-records/SKILL.md) |
+| Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [data-mutations/SKILL.md](./data-mutations/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 
@@ -56,6 +57,9 @@ Showing the visitor's name, or hiding UI they cannot use?
 Putting records on a page, in a table, a list or a detail view?
   load softr-sdk/reading-records
 
+Drawing a chart, a stat tile, or any aggregated number?
+  load softr-sdk/charts-and-metrics
+
 Submitting a form, editing a record, or deleting one?
   load softr-sdk/data-mutations
 
@@ -124,4 +128,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.24.
+Targets `@softr/sdk` v0.0.25.

package/skills/softr-sdk/auth/SKILL.md

@@ -1,30 +1,69 @@
 ---
 name: auth
 description: >-
-  Sign a Softr visitor in, out, or up from a server function: auth.signIn,
-  auth.signOut, auth.signUp and auth.confirmSignUp from @softr/sdk/server, the
-  Result shape they answer with ({ success, data } | { success, error }) and its
-  codes invalidCredentials, tooManyAttempts, emailTaken, invalidDetails and
-  invalidCode, the two-step sign-up, and redirecting after a successful sign-in.
-  The blank template already ships working login and signup pages.
+  Sign a Softr visitor in, out or up from a server function: auth.signIn,
+  signInWithCode, signInWithGoogle, signInWithMagicLink, signUp, confirmSignUp
+  and signOut from @softr/sdk/server, the authenticator-app calls that finish a
+  sign-in (verifyAuthenticator, startAuthenticatorSetup,
+  confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
+  authenticator from a settings page (sendAuthenticatorResetCode,
+  resetAuthenticator, removeAuthenticator). Covers the Result shape they answer
+  with ({ success, data } | { success, error }) and its codes
+  invalidCredentials, tooManyAttempts, emailTaken, invalidDetails, invalidCode
+  and notAuthenticated, the two-step sign-up, and why a successful sign-in does
+  not always mean the visitor is signed in. The blank template already ships
+  working login and signup pages.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.24
+  library_version: 0.0.25
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
 
 # Auth
 
-`auth` is what changes who the visitor is. It exposes four calls and nothing else:
+`auth` is what changes who the visitor is.
+
+Signing in:
+
+| Call | Does |
+| --- | --- |
+| `auth.signIn({ email, password })` | Signs a visitor in with an email and password |
+| `auth.sendSignInCode({ email })` | Emails a one-time sign-in code |
+| `auth.signInWithCode({ email, code })` | Signs a visitor in with that code |
+| `auth.signInWithGoogle({ email, token, fullName? })` | Signs a visitor in with a Google id token the browser obtained, creating the account the first time |
+| `auth.signInWithMagicLink({ token })` | Signs a visitor in with the token from a magic link they followed |
+
+Signing up:
 
 | Call | Does |
 | --- | --- |
-| `auth.signIn({ email, password })` | Signs a visitor in |
-| `auth.signOut()` | Signs the visitor out |
 | `auth.signUp({ email, name? })` | Emails a verification code, creates no account |
-| `auth.confirmSignUp({ email, password, code, name? })` | Creates the account and signs in |
+| `auth.confirmSignUp({ email, code, name?, password? })` | Creates the account and signs the visitor in |
+
+Signing out:
+
+| Call | Does |
+| --- | --- |
+| `auth.signOut()` | Ends every session that visitor has in this app, on every device |
+
+Finishing a sign-in that wants an authenticator app:
+
+| Call | Does |
+| --- | --- |
+| `auth.verifyAuthenticator({ code })` or `({ backupCode })` | Answers the challenge with the code their app shows |
+| `auth.startAuthenticatorSetup()` | Hands back a QR code for enrolling an app |
+| `auth.confirmAuthenticatorSetup({ code })` | Enrols it on its first code, and returns the backup codes once |
+| `auth.skipAuthenticatorSetup()` | Skips enrolment, where the app allows skipping |
+
+Changing an authenticator from a settings page:
+
+| Call | Does |
+| --- | --- |
+| `auth.sendAuthenticatorResetCode()` | Emails the code the next two ask for |
+| `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
+| `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
 **The blank template already ships a working login page and signup page.** Read `src/routes/_auth/login.tsx` before writing anything new. Most tasks are an edit to those, not a new flow.
 
@@ -57,7 +96,7 @@ A form that posts `FormData` instead validates with a function, since a zod obje
 .validator((fields: FormData) => Credentials.parse(Object.fromEntries(fields)))
 ```
 
-`signIn`, `signUp` and `confirmSignUp` answer with a `Result` rather than throwing on something the visitor can fix. `signOut` returns nothing.
+Every call except `signOut` answers with a `Result` rather than throwing on something the visitor can fix. `signOut` returns nothing.
 
 ```ts
 type Result<T> =
@@ -65,14 +104,42 @@ type Result<T> =
   | { success: false; error: { code: AuthErrorCode; message: string } }
 
 type AuthErrorCode =
-  | 'invalidCredentials'   // signIn: wrong email or password
-  | 'tooManyAttempts'      // signIn: rate limited
-  | 'emailTaken'           // signUp or confirmSignUp: that email already has an account
-  | 'invalidDetails'       // signUp: details Softr rejected
-  | 'invalidCode'          // confirmSignUp: wrong or expired verification code
+  | 'invalidCredentials'   // signIn, signInWithGoogle, signInWithMagicLink: wrong password, or a token Softr would not take
+  | 'tooManyAttempts'      // any call: rate limited
+  | 'emailTaken'           // signUp, confirmSignUp: that email already has an account
+  | 'invalidDetails'       // signUp, sendSignInCode: details Softr rejected
+  | 'invalidCode'          // any call that takes a code: wrong or expired
+  | 'notAuthenticated'     // a call that needs a signed-in visitor, made by one who is not
 ```
 
-Each code comes from the call named beside it. Email and password is the sign-in method these calls cover.
+Branch on `error.code` with a `switch` and write your own wording. Never put `error.message` in front of the visitor.
+
+`code` is typed as every code the SDK produces, not the ones a given call can answer, so a `switch` needs a `default` even when the cases above it are complete. Give it a message rather than leaving it out.
+
+## A successful sign-in is not always a session
+
+`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink` and `confirmSignUp` all answer the same two ways:
+
+```ts
+{ status: 'signedIn', user }
+{ status: 'authenticatorRequired', step: 'verify' | 'setup' | 'setupOptional' }
+```
+
+`signedIn` is a session. Redirect into the app.
+
+`authenticatorRequired` is not. The app asks for an authenticator app as well, and the visitor has no session until they produce one. Redirecting into the app here sends them to a page they cannot see, and a guarded page bounces them back to the login form with nothing on screen explaining why.
+
+Send them on by `step`:
+
+| `step` | Show them | Finish with |
+| --- | --- | --- |
+| `verify` | a code field | `auth.verifyAuthenticator({ code })`, or `({ backupCode })` |
+| `setup` | the QR from `auth.startAuthenticatorSetup()` | `auth.confirmAuthenticatorSetup({ code })` |
+| `setupOptional` | the same, plus a skip button | the same, or `auth.skipAuthenticatorSetup()` |
+
+Those calls take only what the visitor typed. The sign-in they finish is the one already in progress for this browser, so nothing has to be carried through the UI. It does not stay open indefinitely, and a visitor who abandons the page signs in again from the start.
+
+An app with no authenticator app configured never answers `authenticatorRequired`. The type still has both arms either way, so `result.data.user` does not exist until you have narrowed on `status`.
 
 ## Core Patterns
 
@@ -85,19 +152,25 @@ const signIn = createServerFn({ method: 'POST' })
     const result = await auth.signIn(data)
 
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'tooManyAttempts'
-            ? 'Too many attempts. Please try again in a few minutes.'
-            : 'Please ensure your email and password are correct.',
+      switch (result.error.code) {
+        case 'invalidCredentials':
+          return { message: 'Please ensure your email and password are correct.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not sign you in. Please try again.' }
       }
     }
 
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
     throw redirect({ to: '/' })
   })
 ```
 
-Two exits: return a message for the form to render, or `throw redirect` on success. Do not put `error.message` in front of the visitor. Write your own wording, as above.
+Three exits: a message for the form to render, a redirect to the second factor, a redirect into the app.
 
 Call it from the component with `useServerFn`:
 
@@ -111,6 +184,43 @@ A server function that throws `redirect` needs the hook. Call the imported funct
 
 A login page is a `NON_LOGGED_IN_USERS` route, which is what keeps an already-signed-in visitor off it. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
 
+### Sign in with an emailed code
+
+For an app that signs people in with a code instead of a password.
+
+```ts
+// Step 1: emails the code.
+const sent = await auth.sendSignInCode({ email })
+
+// Step 2: same two-armed result as signIn.
+const result = await auth.signInWithCode({ email, code })
+```
+
+Step one succeeds whether or not that address has an account, so the form cannot be used to find out who is registered. Say "check your email" either way, and never branch the UI on it.
+
+### Sign in with Google
+
+```ts
+const result = await auth.signInWithGoogle({
+  email,
+  token,     // the id token Google Identity Services handed the page
+  fullName,  // names a first-time visitor, ignored for an existing one
+})
+```
+
+Only an id token works. An access token, a token minted for another app, and an email that does not match it all fail as `invalidCredentials`.
+
+### Sign in with a magic link
+
+For the route the link in the email points at.
+
+```ts
+// Same two-armed result as signIn.
+const result = await auth.signInWithMagicLink({ token })
+```
+
+The token keeps working after it is used, so anyone holding the link can sign in as that visitor. Never log it, and redirect away from the URL that carried it.
+
 ### Sign out
 
 ```ts
@@ -120,7 +230,7 @@ const signOut = createServerFn({ method: 'POST' }).handler(async () => {
 })
 ```
 
-It returns nothing and has no failure the visitor can act on, so send them somewhere and let the redirect re-resolve the context.
+It returns nothing and has no failure the visitor can act on, so send them somewhere and let the redirect re-resolve the context. It ends every session that visitor has in this app, on every device, so a "sign out of this device only" button is not something you can build on it.
 
 ### Sign up, in two steps
 
@@ -134,11 +244,15 @@ const startSignUp = createServerFn({ method: 'POST' })
   .handler(async ({ data }) => {
     const result = await auth.signUp(data)
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'emailTaken'
-            ? 'That email already has an account.'
-            : 'Please check the details and try again.',
+      switch (result.error.code) {
+        case 'emailTaken':
+          return { message: 'That email already has an account.' }
+        case 'invalidDetails':
+          return { message: 'Please check the details and try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not start the sign-up. Please try again.' }
       }
     }
     return { message: null }   // now show the code field
@@ -150,19 +264,91 @@ const finishSignUp = createServerFn({ method: 'POST' })
   .handler(async ({ data }) => {
     const result = await auth.confirmSignUp(data)
     if (!result.success) {
-      return {
-        message:
-          result.error.code === 'emailTaken'
-            ? 'That email already has an account. Please sign in instead.'
-            : 'That code is not valid. Please try again.',
+      switch (result.error.code) {
+        case 'emailTaken':
+          return { message: 'That email already has an account. Please sign in instead.' }
+        case 'invalidCode':
+          return { message: 'That code is not valid. Please try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not finish the sign-up. Please try again.' }
       }
     }
 
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
     throw redirect({ to: '/' })
   })
 ```
 
-The UI has to carry email and password into step two, plus the name if step one collected one. `name` is optional to `confirmSignUp`, the rest is not. It is the only call that creates the account.
+The UI has to carry email into step two, plus the name if step one collected one. `confirmSignUp` is the only call that creates the account.
+
+`password` is what the account is created with. Leave it out only for an app that signs people in with an emailed code. An app that expects a password rejects a sign-up without one, and an app that does not expect one rejects a sign-up that sends it.
+
+### Finishing a sign-in that needs an authenticator app
+
+On `step: 'verify'` the visitor already has an app, and owes a code from it:
+
+```ts
+const verify = createServerFn({ method: 'POST' })
+  .validator(z.object({ code: z.string() }))
+  .handler(async ({ data }) => {
+    const result = await auth.verifyAuthenticator(data)
+    if (!result.success) {
+      switch (result.error.code) {
+        case 'invalidCode':
+          return { message: 'That code is not valid. Please try again.' }
+        case 'tooManyAttempts':
+          return { message: 'Too many attempts. Please try again in a few minutes.' }
+        default:
+          return { message: 'Could not check that code. Please try again.' }
+      }
+    }
+    throw redirect({ to: '/' })
+  })
+```
+
+A visitor without their phone sends `{ backupCode }` instead of `{ code }`. Each backup code works once.
+
+On `step: 'setup'` or `'setupOptional'` they have no app yet:
+
+```ts
+const start = await auth.startAuthenticatorSetup()
+if (!start.success) return { message: 'Could not start setup. Please try again.' }
+
+start.data.otpauthUri    // what an authenticator app reads
+start.data.qrPngBase64   // the same URI as a PNG, for
+                         // <img src={`data:image/png;base64,${qrPngBase64}`} />
+```
+
+Neither of those enrols anybody. `confirmAuthenticatorSetup` does, once it accepts a first code:
+
+```ts
+const done = await auth.confirmAuthenticatorSetup({ code })
+if (done.success) {
+  done.data.backupCodes  // returned once. Render them now, nothing fetches them again.
+  throw redirect({ to: '/' })
+}
+```
+
+Call `startAuthenticatorSetup` again to hand back a fresh QR code, for a visitor who lost the first one. Only the newest one enrols them.
+
+`skipAuthenticatorSetup` finishes the sign-in without enrolling, and only on `setupOptional`. Later sign-ins stop asking.
+
+### Changing an authenticator from a settings page
+
+```ts
+await auth.sendAuthenticatorResetCode()   // emails the code the next two ask for
+await auth.resetAuthenticator({ code })   // unpairs the app, so a new one can be enrolled
+await auth.removeAuthenticator({ code })  // turns the authenticator off
+```
+
+All three need a signed-in visitor and answer `notAuthenticated` when there is not one. Both changes ask for a code from the visitor's inbox as well, because both change how that visitor signs in.
+
+After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuthenticatorSetup`, which is also where the new backup codes come from. After a removal, an app that requires an authenticator asks the visitor to set one up again on their next sign-in.
 
 ## References
 

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: charts-and-metrics
+description: >-
+  Aggregate Softr datasource records inside a server function: ds.chart with
+  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
+  headline number, date bucket intervals, which aggregations each kind of field
+  offers, the two-group-column ceiling, and distinct values for filter
+  controls. Aggregation only. Listing and fetching records is reading-records.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.22
+---
+
+This skill builds on softr-sdk, and on reading-records for declaring the action a chart aggregates over.
+
+# Charts and metrics
+
+`ds.chart` groups records and aggregates each group into one row: the data behind a bar chart, a line, a pie. `ds.metric` aggregates everything into one value: the number on a stat tile. Both live on `@softr/sdk/server` and run inside a `createServerFn` handler, and both take the same read action `ds.list` takes, with the same `where` filters.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineAction } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+
+const sales = defineAction({
+  id: 'sales',
+  datasource: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+  operation: 'read',
+  fields: {
+    amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
+    region: 'fZk3Qm9pLw2Xa1',   // SELECT
+    status: 'Ru7bVx2cNq0Ed9',   // SELECT, choice ids 'paid' | 'open' | 'void'
+    closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
+    rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+A chart only sees the action's declared fields, so a field to group, aggregate or filter by must be in `fields`.
+
+## Core Patterns
+
+### A bar chart
+
+```ts
+const ordersByRegion = createServerFn().handler(async () => {
+  const { data } = await ds
+    .chart(sales)
+    .groupBy((q) => ({ region: q.region }))
+    .metrics((q) => ({ orders: q.$count }))
+    .orderBy((q) => q.orders.desc)
+  return data
+})
+// data: Array<{ region: string | null; orders: number }>
+```
+
+One row per group, keyed by the names you chose in `groupBy` and `metrics`. `orders` is `number`, not `number | null`: a group that exists holds at least one record. The `null` region is the bucket of records with no value. The result also carries `executionTimestamp: Date`, when the numbers were computed.
+
+A SELECT or LINKED_RECORD group column comes back as the choice's display label, not its id. Labels are user-editable and a `where` on the same field compares ids, so a clicked bar's value cannot be fed straight back into a filter.
+
+### A time series
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .where((q) => q.status.is('paid'))
+  .orderBy((q) => q.month.asc)
+// data: Array<{ month: string | null; revenue: number | null }>
+```
+
+`q.closedAt` bare groups by the field's value. The bucket leaves hanging off it group a date field by the bucket: `byDay`, `byWeek`, `byMonth`, `byQuarter`, `byYear`, and the cyclic `byHourOfDay`, `byDayOfWeek`, `byMonthOfYear`, `byQuarterOfYear`. What each one holds is in [references/aggregations.md](./references/aggregations.md); `byMonth` reads as `"2025-06"`.
+
+**Sort the time axis ascending yourself.** Left unsorted, rows come back by the first bucket ascending when there is one, else by the first metric descending. A time axis that misses the fallback arrives in value order, which draws a scrambled line rather than failing.
+
+### Spread, not just totals
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ region: q.region }))
+  .metrics((q) => ({
+    smallest: q.amount.min,
+    typical: q.amount.avg,
+    biggest: q.amount.max,
+  }))
+  .orderBy((q) => q.typical.desc)
+```
+
+Any number of metrics in one request, several over the same field included. Each row carries all of them, so one request can feed two panels. A metric key may not reuse a group key, and two metrics may not ask for the same value. `avg` comes back rounded to two decimals.
+
+### Two group columns, which is the ceiling
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => [q.month.asc, q.revenue.desc])
+// data: Array<{ month: string | null; region: string | null; revenue: number | null }>
+```
+
+The result is long format, one row per month and region pair, so the app pivots into one array per series before charting. **A chart groups by at most two columns**, each a different field, and a field cannot be grouped and aggregated in the same chart. A third group column is a compile error.
+
+### Distinct values, for a filter control
+
+```ts
+const { data } = await ds.chart(sales).groupBy((q) => ({ region: q.region }))
+// data: Array<{ region: string | null }>
+```
+
+Skip `metrics` entirely and the rows hold the distinct group values, one each. This is the cheapest way to fill a dropdown from a real column.
+
+### A headline number
+
+```ts
+const { value } = await ds
+  .metric(sales, (q) => q.amount.sum)
+  .where((q) => q.status.is('paid'))
+// value: number | null
+```
+
+One aggregation, no grouping, one value. Whenever the answer is a single number, a stat tile or a count, reach for `ds.metric` rather than a one-row chart: there is nothing to group by and nothing to unpack out of `data`. The same measure handles apply, `q.$count` included:
+
+```ts
+const { value: open } = await ds.metric(sales, (q) => q.$count).where((q) => q.status.is('open'))
+// open: number
+```
+
+### Top N
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ rep: q.rep }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => q.revenue.desc)
+
+const top5 = data.slice(0, 5)
+```
+
+A chart has no row limit to set, so a top-N is a client-side slice of the fully sorted rows.
+
+### A dashboard load
+
+```ts
+const loadDashboard = createServerFn().handler(async () => {
+  const [mtd, series] = await Promise.all([
+    ds
+      .metric(sales, (q) => q.amount.sum)
+      .where((q) => q.$and(q.status.is('paid'), q.closedAt.gte('2026-09-01'))),
+    ds
+      .chart(sales)
+      .groupBy((q) => ({ month: q.closedAt.byMonth }))
+      .metrics((q) => ({ revenue: q.amount.sum }))
+      .where((q) => q.status.is('paid'))
+      .orderBy((q) => q.month.asc),
+  ])
+  return { mtd: mtd.value, series: series.data }
+})
+```
+
+Each tile and panel is its own request, fired in parallel from one handler.
+
+## Order of calls
+
+`groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.
+
+## References
+
+- [references/aggregations.md](./references/aggregations.md): every bucket interval and its value type, which aggregations each kind of field offers, and the chart rules
+- [reading-records/SKILL.md](../reading-records/SKILL.md): declaring the action, and the filter operators `where` accepts
+- [reading-records/references/query-builder.md](../reading-records/references/query-builder.md): the full filter matrix