@softr/sdk 0.0.23 → 0.0.25

package/dist/core/datasource.js

@@ -120,9 +120,10 @@ async function deleteRecord(datasourceId, id) {
 }
 async function getMetric(datasourceId, options) {
 	const { select, where, aggregation, field } = options;
+	if (aggregation !== "COUNT" && !field) throw new Error(`field is required for aggregation "${aggregation}"`);
 	const fieldId = field ? select?.[field] ?? field : void 0;
 	const filterCriteria = where ? dealiasFilterCriteria(buildFilterCriteria(where), select ?? {}) : {};
-	const res = await fetch(`${dsUrl(datasourceId)}/metric/data`, {
+	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -131,10 +132,11 @@ async function getMetric(datasourceId, options) {
 		},
 		body: JSON.stringify({
 			options: { userLocale: "en-US" },
-			calculationField: {
+			groupBy: [],
+			metrics: [{
 				field: fieldId,
 				aggregation
-			},
+			}],
 			filterCriteria
 		})
 	});
@@ -142,26 +144,24 @@ async function getMetric(datasourceId, options) {
 	const payload = await res.json();
 	const executionTimestamp = /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3);
 	let value;
-	if (aggregation === "COUNT") value = payload.data.find((item) => COUNT_CNT in item)?.[COUNT_CNT] ?? null;
-	else {
-		if (!fieldId) throw new Error(`field is required for aggregation "${aggregation}"`);
-		value = payload.data.find((item) => fieldId in item)?.[fieldId] ?? null;
-	}
+	const responseKey = aggregation === "COUNT" && !fieldId ? COUNT_CNT : fieldId;
+	value = payload.data.find((item) => responseKey in item)?.[responseKey] ?? null;
 	return {
 		value,
 		executionTimestamp
 	};
 }
-async function getChartData(datasourceId, options) {
+async function getChart(datasourceId, options) {
 	const { select, where, groupBy, metrics, orderBy } = options;
 	const filterCriteria = where ? dealiasFilterCriteria(buildFilterCriteria(where), select ?? {}) : {};
-	const sortingOption = orderBy ? dealiasOrderBy(buildOrderBy(orderBy), select ?? {})[0] : void 0;
+	const sortingOptions = orderBy ? dealiasOrderBy(buildOrderBy(orderBy), select ?? {}) : void 0;
 	const groupByFields = (Array.isArray(groupBy) ? groupBy : [groupBy]).map((field) => ({ field: select?.[field] ?? field }));
 	const yAxisFields = Object.values(metrics).map(({ field, aggregation }) => ({
 		field: field ? select?.[field] ?? field : void 0,
 		aggregation
 	}));
-	const res = await fetch(`${dsUrl(datasourceId)}/chart`, {
+	if (!yAxisFields.length) throw new Error("chart requires at least one metric");
+	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -171,12 +171,12 @@ async function getChartData(datasourceId, options) {
 		body: JSON.stringify({
 			options: { userLocale: "en-US" },
 			filterCriteria,
-			sortingOption,
-			xAxisFields: groupByFields,
-			yAxisFields
+			sortingOptions,
+			groupBy: groupByFields,
+			metrics: yAxisFields
 		})
 	});
-	await assertResponseOk(res, `Softr datasource chartData failed for "${datasourceId}"`);
+	await assertResponseOk(res, `Softr datasource chart failed for "${datasourceId}"`);
 	const payload = await res.json();
 	const executionTimestamp = /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3);
 	const aliases = {};
@@ -216,11 +216,11 @@ const ds = {
 	update: updateRecord,
 	delete: deleteRecord,
 	metric: getMetric,
-	chartData: getChartData
+	chart: getChart
 };
 function withoutTrailingSlash(url) {
 	return url.replace(/\/+$/, "");
 }
 
 //#endregion
-export { ds };
+export { ds, dsUrl };

package/dist/core/integration.js

@@ -1,7 +1,7 @@
 import { readSessionToken } from "../auth/session.js";
+import { dsUrl } from "./datasource.js";
 
 //#region src/core/integration.ts
-const BASE_URL = () => (import.meta.env.VITE_SOFTR_BASE_URL ?? "").replace(/\/$/, "");
 async function integrationFetch(integrationId, input, init) {
 	const req = new Request(input, init);
 	if (req.signal.aborted) throw req.signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
@@ -16,7 +16,7 @@ async function integrationFetch(integrationId, input, init) {
 	};
 	const method = req.method.toUpperCase();
 	if (method !== "GET" && method !== "HEAD" && req.body !== null) payload.body = await req.clone().text();
-	return fetch(`${BASE_URL()}/api/integrations/${integrationId}/proxy`, {
+	return fetch(`${dsUrl(integrationId)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { q } from "./core/query.js";
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
+import { AggregationFunction, ChartOptions, ChartResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
 import { Permissions } from "./auth/permissions.js";
 import { SoftrContext } from "./auth/context.js";
 import { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type DatasourceTypeMap, DefaultErrorOverlay, type GetOptions, type JsonValue, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RecordFieldsFor, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartOptions, type ChartResult, type CreateOptions, type DatasourcePermissions, type DatasourceTypeMap, DefaultErrorOverlay, type GetOptions, type JsonValue, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RecordFieldsFor, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/types.d.ts

@@ -90,7 +90,7 @@ interface MetricResult {
   value: number | null;
   executionTimestamp: Date;
 }
-interface ChartDataOptions {
+interface ChartOptions {
   select?: Record<string, string>;
   where?: AnyConstructable;
   /** Field alias (resolved via select) or raw field ID. */
@@ -103,7 +103,7 @@ interface ChartDataOptions {
   /** Override the timezone for this request. */
   timeZone?: string;
 }
-interface ChartDataResult {
+interface ChartResult {
   data: Record<string, JsonValue>[];
   executionTimestamp: Date;
 }
@@ -125,4 +125,4 @@ interface UpdateOptions {
   data: Record<string, JsonValue>;
 }
 //#endregion
-export { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };
+export { AggregationFunction, ChartOptions, ChartResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };

package/dist/vite.d.ts

@@ -1,14 +1,7 @@
-import { Manifest, ManifestNode } from "./routes/manifest.js";
 import { PluginOption } from "vite";
 
 //#region src/vite.d.ts
-declare const MANIFEST_RELATIVE_PATH: string;
-/** Writes `<root>/dist/routes.json` and returns its path. Throws on a rule it cannot read. */
-declare function generateManifest(root: string): Promise<string>;
-/**
- * Everything Softr adds to an app's Vite config: the build-time routes manifest, plus the studio
- * edit engine when the pod supplies one.
- */
+/** Everything Softr adds to an app's Vite config: the studio edit engine, when the pod supplies one. */
 declare function softr(): PluginOption[];
 //#endregion
-export { MANIFEST_RELATIVE_PATH, type Manifest, type ManifestNode, generateManifest, softr };
+export { softr };

package/dist/vite.js

@@ -1,75 +1,10 @@
-import { ManifestError, generateRoutesManifest } from "./routes/manifest.js";
-import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 //#region src/vite.ts
-const MANIFEST_RELATIVE_PATH = path.join("dist", "routes.json");
-async function renderManifest(root) {
-	try {
-		return await generateRoutesManifest(root);
-	} catch (error) {
-		if (error instanceof ManifestError) {
-			const { filePath, line, column, message } = error.detail;
-			throw new Error(`[softr] ${filePath}:${line}:${column} — ${message}`, { cause: error });
-		}
-		throw error;
-	}
-}
-async function writeManifest(root, contents) {
-	const target = path.resolve(root, MANIFEST_RELATIVE_PATH);
-	await mkdir(path.dirname(target), { recursive: true });
-	await writeFile(target, contents, "utf8");
-	return target;
-}
-/** Writes `<root>/dist/routes.json` and returns its path. Throws on a rule it cannot read. */
-async function generateManifest(root) {
-	return writeManifest(root, await renderManifest(root));
-}
-/**
-* Everything Softr adds to an app's Vite config: the build-time routes manifest, plus the studio
-* edit engine when the pod supplies one.
-*/
+/** Everything Softr adds to an app's Vite config: the studio edit engine, when the pod supplies one. */
 function softr() {
-	return [
-		routesManifest(),
-		previewIdentity(),
-		editEngine()
-	];
-}
-/**
-* Signing the preview in writes the cookie this app's own session code reads back, so it lives here
-* rather than in the edit engine — one implementation of the format, no version to keep in step.
-*
-* `SOFTR_APPLICATION_ID` gates it: the pod sets it, a developer's machine has none.
-*/
-async function previewIdentity() {
-	if (!process.env.SOFTR_APPLICATION_ID) return false;
-	const { PREVIEW_REDEMPTION_PATH, PREVIEW_SIGNED_IN_PATH, redeemGrant, reportSignedIn } = await import("./preview-identity/preview-identity.js");
-	return {
-		name: "softr-preview-identity",
-		apply: "serve",
-		configureServer(server) {
-			server.middlewares.use(PREVIEW_REDEMPTION_PATH, redeemGrant);
-			server.middlewares.use(PREVIEW_SIGNED_IN_PATH, reportSignedIn);
-		}
-	};
-}
-/** Plugin order does not matter: this puts nothing into the module graph. */
-function routesManifest() {
-	let root = process.cwd();
-	let rendered = null;
-	return {
-		name: "softr",
-		apply: "build",
-		configResolved(config) {
-			root = config.root;
-		},
-		async closeBundle() {
-			rendered ??= renderManifest(root);
-			await writeManifest(root, await rendered);
-		}
-	};
+	return [editEngine()];
 }
 /**
 * The edit engine is provided by the pod runtime rather than an app dependency: it is never in the
@@ -91,4 +26,4 @@ async function editEngine() {
 }
 
 //#endregion
-export { MANIFEST_RELATIVE_PATH, generateManifest, softr };
+export { softr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
@@ -16,17 +16,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@babel/parser": "^7.28.0",
-    "@babel/traverse": "^7.28.0",
-    "@babel/types": "^7.28.0",
-    "@tanstack/router-generator": "^1.167.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@tanstack/intent": "^0.3.6",
     "@tanstack/react-router": "^1.168.0",
     "@tanstack/react-start": "^1.168.0",
-    "@types/babel__traverse": "^7.28.0",
     "@types/node": "^24.3.0",
     "tsdown": "^0.15.0",
     "typescript": "^5.9.2",

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.23
+  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**: `ds.metric`, `ds.chartData`, `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 any of them. Tell the user the capability is not ready and ask how they want to proceed.
+> **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.
 
 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`.
 
@@ -124,4 +124,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.23.
+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.23
+  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/current-user/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.23
+  library_version: 0.0.25
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.