@softr/sdk 0.0.24 → 0.0.26-alpha-0

package/dist/action.d.ts

@@ -0,0 +1,195 @@
+import { SoftrUserGroupId } from "./auth/user.js";
+
+//#region src/action.d.ts
+type ActionOperation = "read" | "create" | "update" | "delete";
+type ActionPermission = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+/**
+ * Describes the datasources available in the app and their read, create and update types.
+ *
+ * This lets datasource IDs and fields in actions be type-checked.
+ *
+ * @example
+ * declare module "@softr/sdk" {
+ *   interface SoftrDatasources {
+ *     FrkQIVpeTtfJDT: {
+ *       name: "Cafes"
+ *       primaryField: "9QrOA"
+ *       read: CafesRead
+ *       create: CafesCreate
+ *       update: CafesUpdate
+ *       fieldTypes: { "9QrOA": "SINGLE_LINE_TEXT"; "1G3aA": "DATETIME" }
+ *     }
+ *   }
+ * }
+ */
+interface SoftrDatasources {}
+type SoftrDatasourceId = keyof SoftrDatasources extends never ? string : keyof SoftrDatasources & string;
+/** The read type one datasource returns. */
+type ReadOf<TDatasource$1> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
+  read: infer TRecord;
+} ? TRecord : never : never;
+/**
+ * The DSv2 type name one field declares, as codegen emitted it: `"NUMBER"`, `"SELECT[]"`.
+ * `never` for a field no augmentation describes.
+ */
+type FieldTypeOf<TDatasource$1, TFieldId> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
+  fieldTypes: infer TTypes;
+} ? TFieldId extends keyof TTypes ? TTypes[TFieldId] : never : never : never;
+/** The write type one datasource accepts for one operation. */
+type WriteOf<TDatasource$1, TOperation$1> = TDatasource$1 extends keyof SoftrDatasources ? TOperation$1 extends keyof SoftrDatasources[TDatasource$1] ? SoftrDatasources[TDatasource$1][TOperation$1] : never : never;
+/** The field ids a write may name. Any string, until {@link SoftrDatasources} is declared. */
+type FieldIdOf<TDatasource$1, TOperation$1> = keyof SoftrDatasources extends never ? string : keyof WriteOf<TDatasource$1, TOperation$1> & string;
+/**
+ * The field ids a read may name. Any string, until {@link SoftrDatasources} is declared.
+ *
+ * A read constrains against the record type rather than a write type, because a read may
+ * name a field no write can: a formula or a lookup is on the record and on neither.
+ */
+type ReadFieldIdOf<TDatasource$1> = keyof SoftrDatasources extends never ? string : keyof ReadOf<TDatasource$1> & string;
+/**
+ * What an action declares, as the type layer reads it. `permission` is absent because no
+ * call site depends on it, and the build reads it off the value.
+ */
+type ActionShape = {
+  id: string;
+  datasource: SoftrDatasourceId;
+  operation: ActionOperation;
+  fields?: Record<string, string>;
+};
+/** What a read declares. A read is the whole field list, so `fields` is not optional. */
+type ReadShape = ActionShape & {
+  operation: "read";
+  fields: Record<string, string>;
+};
+/**
+ * What one action writes: its own aliases, each resolved to the value that field accepts.
+ *
+ * An alias renames the field, and a mapped type keeps a property's docstring only while it
+ * keeps the key, so the prose that sits on the field in `softr-env.d.ts` does not reach the
+ * call site. The type does.
+ */
+type ActionData<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
+  datasource: infer TDatasource;
+  operation: infer TOperation;
+  fields: infer TFields;
+} ? { [Alias in keyof TFields]?: WriteOf<TDatasource, TOperation>[TFields[Alias] & keyof WriteOf<TDatasource, TOperation>] } : Record<string, unknown>;
+/**
+ * What a mutation reads back: the same aliases, resolved against the table's read type.
+ *
+ * A write returns the record it wrote, and the SDK aliases its fields on the way out, so a
+ * field the action never declared is absent from the result as well as from the payload.
+ *
+ * Every alias the action does declare is present. An empty field reads as `null`, so nothing
+ * here is optional.
+ */
+type ActionRecord<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
+  datasource: infer TDatasource;
+  fields: infer TFields;
+} ? { [Alias in keyof TFields]: ReadOf<TDatasource>[TFields[Alias] & keyof ReadOf<TDatasource>] } : Record<string, unknown>;
+declare const brand: unique symbol;
+/**
+ * A handle to a declared action, and the only thing a mutation accepts. The brand keeps it
+ * nominal, so an object literal of the same shape will not do and no mutation can be reached
+ * without passing through a declaration the build reads.
+ *
+ * The brand carries the declaration itself, which is what lets a call site resolve what the
+ * action writes without codegen having said anything about this action.
+ */
+type Action<TShape extends ActionShape = ActionShape> = {
+  type: "action";
+  id: TShape["id"];
+} & {
+  readonly [brand]: TShape;
+};
+/** What a write action declares. */
+type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1> = {
+  id: TId;
+  datasource: TDatasource$1;
+  operation: TOperation$1;
+  fields: TFields$1;
+  permission: ActionPermission;
+};
+/** What a read action declares. */
+type ReadDeclaration<TId extends string, TDatasource$1, TFields$1> = {
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "read";
+  fields: TFields$1;
+  permission: ActionPermission;
+};
+/** What a delete action declares. `fields?: never` so a stray one is rejected rather than ignored. */
+type DeleteDeclaration<TId extends string, TDatasource$1> = {
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "delete";
+  fields?: never;
+  permission: ActionPermission;
+};
+/** The whole declaration, which is what an action is at runtime and in the manifest. */
+
+/**
+ * Declares a data operation: which datasource, which of the four operations, which fields
+ * participate, and who may run it.
+ *
+ * One call per action, at module scope, with a literal: the build reads these declarations
+ * to publish what the app may read and write.
+ *
+ * The keys of `fields` are aliases the app chooses and the values are field ids of the
+ * datasource the action names. The result, `data`, `where` and `orderBy` at the call site
+ * are all keyed by those aliases, so nothing there restates what the action already says.
+ *
+ * A read fixes the table and the columns. It does not fix which rows: `where`, `orderBy` and
+ * the paging arguments stay at the call site, because a list screen changes them as the user
+ * types and a declaration cannot follow that.
+ *
+ * @example
+ * const publishedPosts = defineAction({
+ *   id: "publishedPosts",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "read",
+ *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
+ *   permission: { userGroup: "ALL_USERS" },
+ * })
+ *
+ * const { records } = await ds
+ *   .list(publishedPosts)
+ *   .where((q) => q.publishedAt.lte(today))
+ *   .orderBy((q) => q.publishedAt.desc)
+ *
+ * @example
+ * const closeOrderAction = defineAction({
+ *   id: "closeOrder",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "update",
+ *   fields: { status: "V1StGXR8", closedAt: "Z7pQm4Kd" },
+ *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ * })
+ *
+ * await ds.update(closeOrderAction, { id, data: { status: "closed" } })
+ */
+declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "read";
+  fields: TFields$1;
+}>;
+declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: TOperation$1;
+  fields: TFields$1;
+}>;
+declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "delete";
+}>;
+//#endregion
+export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineAction };

package/dist/action.js

@@ -0,0 +1,21 @@
+//#region src/action.ts
+function defineAction(definition) {
+	return {
+		type: "action",
+		...definition
+	};
+}
+/**
+* True for anything {@link defineAction} produced, whatever its operation.
+*
+* Matched on `type` rather than with `instanceof`, so two copies of the SDK in one
+* dependency tree still recognise each other's actions.
+*/
+function isAction(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return candidate.type === "action" && typeof candidate.id === "string" && typeof candidate.datasource === "string";
+}
+
+//#endregion
+export { defineAction, isAction };

package/dist/assertions.js

@@ -18,9 +18,6 @@ function assert(condition, message) {
 function panic(message) {
 	throwAtCaller(panic, new AssertionError(unwrapErrorMessage(message)));
 }
-function todo(message) {
-	throwAtCaller(todo, new UnimplementedError(unwrapErrorMessage(message)));
-}
 /**
 * A soft assertion that throws an error in non prod environments, including
 * staging, but logs an error in production mode.
@@ -47,9 +44,6 @@ var AssertionError = class extends Error {
 var SoftAssertionError = class extends Error {
 	name = "SoftAssertionError";
 };
-var UnimplementedError = class extends Error {
-	name = "UnimplementedError";
-};
 function unwrapErrorMessage(message) {
 	return typeof message === "function" ? message() : message ?? "";
 }
@@ -65,4 +59,4 @@ function throwAtCaller(f, ex) {
 }
 
 //#endregion
-export { assert, panic, requireDefined, softAssert, todo };
+export { assert, panic, requireDefined, softAssert };

package/dist/auth/isomorphic.d.ts

@@ -1,6 +1,5 @@
 import { User } from "./user.js";
-import { DatasourcePermissions } from "../types.js";
-import { Permissions } from "./permissions.js";
+import { DatasourcePermissions, Permissions } from "./permissions.js";
 import { Session, SoftrContext } from "./context.js";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 

package/dist/auth/methods/authenticator.d.ts

@@ -0,0 +1,80 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/authenticator.d.ts
+
+/**
+ * Starts enrolling an authenticator app, for a sign-in that asked to set one up
+ * or for a signed-in visitor adding one.
+ *
+ * `otpauthUri` is what an authenticator app reads. `qrPngBase64` is that same
+ * URI as a PNG for `<img src="data:image/png;base64,…">`, so a page can show
+ * the QR code without a QR library. Neither one enrols anybody.
+ * {@link confirmAuthenticatorSetup} does that, once it accepts a first code.
+ *
+ * Call it again to hand back a fresh QR code, for a visitor who lost the first
+ * one. Only the newest one enrols them.
+ */
+declare function startAuthenticatorSetup(): Promise<Result<{
+  otpauthUri: string;
+  qrPngBase64: string;
+}, AuthError>>;
+/**
+ * Enrols the authenticator app on its first code and signs the visitor in.
+ *
+ * This is the only call that returns the backup codes, and it returns them
+ * once. Nothing fetches them again, so render them before leaving the page.
+ */
+declare function confirmAuthenticatorSetup(details: {
+  code: string;
+}): Promise<Result<{
+  user: User;
+  backupCodes: Array<string>;
+}, AuthError>>;
+/**
+ * Skips enrolment and finishes the sign-in, for a visitor whose app offers an
+ * authenticator without requiring one. Only the `setupOptional` step.
+ *
+ * Later sign-ins stop asking.
+ */
+declare function skipAuthenticatorSetup(): Promise<Result<User, AuthError>>;
+/**
+ * Finishes a sign-in that stopped at the `verify` step, with the code the
+ * visitor's authenticator app shows or one of their backup codes.
+ *
+ * Each backup code works once.
+ */
+declare function verifyAuthenticator(credentials: {
+  code: string;
+} | {
+  backupCode: string;
+}): Promise<Result<User, AuthError>>;
+/**
+ * Emails the signed-in visitor the code that {@link resetAuthenticator} and
+ * {@link removeAuthenticator} ask for.
+ *
+ * Both change how the visitor signs in, so both want a code from their inbox
+ * on top of being signed in.
+ */
+declare function sendAuthenticatorResetCode(): Promise<Result<null, AuthError>>;
+/**
+ * Unpairs the visitor's authenticator app so they can enrol a new one with
+ * {@link startAuthenticatorSetup}, after a lost or replaced phone.
+ *
+ * `code` is the one {@link sendAuthenticatorResetCode} emailed.
+ */
+declare function resetAuthenticator(details: {
+  code: string;
+}): Promise<Result<null, AuthError>>;
+/**
+ * Turns the visitor's authenticator app off entirely.
+ *
+ * `code` is the one {@link sendAuthenticatorResetCode} emailed. An app that
+ * requires an authenticator will ask them to set one up again on their next
+ * sign-in.
+ */
+declare function removeAuthenticator(details: {
+  code: string;
+}): Promise<Result<null, AuthError>>;
+//#endregion
+export { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator };

package/dist/auth/methods/authenticator.js

@@ -0,0 +1,175 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { clearPendingAuth, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionToken } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/authenticator.ts
+/**
+* Starts enrolling an authenticator app, for a sign-in that asked to set one up
+* or for a signed-in visitor adding one.
+*
+* `otpauthUri` is what an authenticator app reads. `qrPngBase64` is that same
+* URI as a PNG for `<img src="data:image/png;base64,…">`, so a page can show
+* the QR code without a QR library. Neither one enrols anybody.
+* {@link confirmAuthenticatorSetup} does that, once it accepts a first code.
+*
+* Call it again to hand back a fresh QR code, for a visitor who lost the first
+* one. Only the newest one enrols them.
+*/
+async function startAuthenticatorSetup() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupInit(readPendingAuthToken() ?? readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected authenticator setup to start, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: result.data
+	};
+}
+/**
+* Enrols the authenticator app on its first code and signs the visitor in.
+*
+* This is the only call that returns the backup codes, and it returns them
+* once. Nothing fetches them again, so render them before leaving the page.
+*/
+async function confirmAuthenticatorSetup(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupComplete(readPendingAuthToken() ?? readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected authenticator setup to finish, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session, backupCodes } = result.data;
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: {
+			user: session.user,
+			backupCodes
+		}
+	};
+}
+/**
+* Skips enrolment and finishes the sign-in, for a visitor whose app offers an
+* authenticator without requiring one. Only the `setupOptional` step.
+*
+* Later sign-ins stop asking.
+*/
+async function skipAuthenticatorSetup() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSetupDismiss(readPendingAuthToken() ?? readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected to skip authenticator setup, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from skipping setup, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* Finishes a sign-in that stopped at the `verify` step, with the code the
+* visitor's authenticator app shows or one of their backup codes.
+*
+* Each backup code works once.
+*/
+async function verifyAuthenticator(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorVerify(readPendingAuthToken() ?? readSessionToken(), "code" in credentials ? { totpCode: credentials.code } : { backupCode: credentials.backupCode });
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected to verify the authenticator, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from verification, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* Emails the signed-in visitor the code that {@link resetAuthenticator} and
+* {@link removeAuthenticator} ask for.
+*
+* Both change how the visitor signs in, so both want a code from their inbox
+* on top of being signed in.
+*/
+async function sendAuthenticatorResetCode() {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorSendResetCode(readSessionToken());
+	if (!result.ok) {
+		if (result.status === 401) return authError("notAuthenticated", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the reset code to be emailed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Unpairs the visitor's authenticator app so they can enrol a new one with
+* {@link startAuthenticatorSetup}, after a lost or replaced phone.
+*
+* `code` is the one {@link sendAuthenticatorResetCode} emailed.
+*/
+async function resetAuthenticator(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorReset(readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the authenticator to be reset, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Turns the visitor's authenticator app off entirely.
+*
+* `code` is the one {@link sendAuthenticatorResetCode} emailed. An app that
+* requires an authenticator will ask them to set one up again on their next
+* sign-in.
+*/
+async function removeAuthenticator(details) {
+	const result = await makePlatform(sessionConfig().applicationId).authenticatorRemove(readSessionToken(), details.code);
+	if (!result.ok) {
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status >= 500) panic(`Expected the authenticator to be removed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+
+//#endregion
+export { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator };

package/dist/auth/methods/code.d.ts

@@ -0,0 +1,40 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/code.d.ts
+
+/**
+ * Emails a one-time sign-in code, for an app that signs people in with a code
+ * rather than a password.
+ *
+ * It succeeds whether or not the address has an account, so nobody can use the
+ * form it backs to find out who is registered. Say "check your email" either
+ * way.
+ */
+declare function sendSignInCode(details: {
+  email: string;
+}): Promise<Result<null, AuthError>>;
+/**
+ * Signs a visitor in with the code {@link sendSignInCode} emailed them.
+ *
+ * A `signedIn` result means the visitor is signed in. An app that also asks for
+ * an authenticator app answers `authenticatorRequired` instead, naming the step
+ * to send them to next.
+ */
+declare function signInWithCode(credentials: {
+  email: string;
+  code: string;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  /**
+   * `verify`: they have an authenticator app and owe a code.
+   * `setup`: the app requires one and they have none yet.
+   * `setupOptional`: same, except they may skip it instead.
+   */
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
+//#endregion
+export { sendSignInCode, signInWithCode };

package/dist/auth/methods/code.js

@@ -0,0 +1,74 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/code.ts
+/**
+* Emails a one-time sign-in code, for an app that signs people in with a code
+* rather than a password.
+*
+* It succeeds whether or not the address has an account, so nobody can use the
+* form it backs to find out who is registered. Say "check your email" either
+* way.
+*/
+async function sendSignInCode(details) {
+	const result = await makePlatform(sessionConfig().applicationId).sendSignInCode(details.email);
+	if (!result.ok) {
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status === 400) return authError("invalidDetails", result.message);
+		if (result.status >= 500) panic(`Expected the sign-in code to be emailed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app signs people in with an emailed code.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Signs a visitor in with the code {@link sendSignInCode} emailed them.
+*
+* A `signedIn` result means the visitor is signed in. An app that also asks for
+* an authenticator app answers `authenticatorRequired` instead, naming the step
+* to send them to next.
+*/
+async function signInWithCode(credentials) {
+	const result = await makePlatform(sessionConfig().applicationId).signInWithCode(credentials);
+	if (!result.ok) {
+		if (result.status === 429) return authError("tooManyAttempts", result.message);
+		if (result.status === 400 || result.status === 401) return authError("invalidCode", result.message);
+		if (result.status >= 500) panic(`Expected sign-in to succeed, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app signs people in with an emailed code.`);
+	}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from sign-in, but got none");
+		writeCookies([makePendingAuthCookie(mfa.challengeToken)]);
+		return {
+			success: true,
+			data: {
+				status: "authenticatorRequired",
+				step: mfa.action === "VERIFICATION_REQUIRED" ? "verify" : mfa.action === "SETUP_REQUIRED" ? "setup" : "setupOptional"
+			}
+		};
+	}
+	const { session } = result.data;
+	assert(session, "Expected a session from sign-in, but got none");
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+		user: session.user,
+		permissions: session.permissions
+	}, session.jwt)]);
+	clearPendingAuth();
+	return {
+		success: true,
+		data: {
+			status: "signedIn",
+			user: session.user
+		}
+	};
+}
+
+//#endregion
+export { sendSignInCode, signInWithCode };

package/dist/auth/methods/magicLink.d.ts

@@ -0,0 +1,24 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/magicLink.d.ts
+
+/**
+ * Signs a visitor in with the token from a magic link they followed.
+ *
+ * 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.
+ *
+ */
+declare function signInWithMagicLink(credentials: {
+  token: string;
+}): Promise<Result<{
+  status: "signedIn";
+  user: User;
+} | {
+  status: "authenticatorRequired";
+  step: "verify" | "setup" | "setupOptional";
+}, AuthError>>;
+//#endregion
+export { signInWithMagicLink };