@softr/sdk 0.0.93 → 0.0.94

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

@@ -0,0 +1,34 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/emailCode2fa.d.ts
+
+/**
+ * Finishes a sign-in that answered `emailCodeRequired`, with the code emailed
+ * to the visitor.
+ *
+ * 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 verifyEmailCode(details: {
+  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>>;
+/**
+ * Emails the code for {@link verifyEmailCode} again. Asking again within a
+ * short wait sends nothing and still succeeds.
+ */
+declare function resendEmailCode(): Promise<Result<null, AuthError>>;
+//#endregion
+export { resendEmailCode, verifyEmailCode };

package/dist/auth/methods/emailCode2fa.js

@@ -0,0 +1,71 @@
+import { assert, panic } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken } from "../session.js";
+import { makePlatform } from "../platform.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/emailCode2fa.ts
+/**
+* Finishes a sign-in that answered `emailCodeRequired`, with the code emailed
+* to the visitor.
+*
+* 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 verifyEmailCode(details) {
+	const result = await makePlatform(sessionConfig().applicationId).emailCodeVerify(readPendingAuthToken(), 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 to verify the emailed code, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app asks for an emailed code at sign-in.`);
+	}
+	if (result.data.status === "MFA_REQUIRED") {
+		const { mfa } = result.data;
+		assert(mfa, "Expected a challenge from verification, 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 verification, 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
+		}
+	};
+}
+/**
+* Emails the code for {@link verifyEmailCode} again. Asking again within a
+* short wait sends nothing and still succeeds.
+*/
+async function resendEmailCode() {
+	const result = await makePlatform(sessionConfig().applicationId).emailCodeResend(readPendingAuthToken());
+	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 code to be emailed again, but got ${result.status}: ` + result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app asks for an emailed code at sign-in.`);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+
+//#endregion
+export { resendEmailCode, verifyEmailCode };

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

@@ -8,7 +8,8 @@ import { AuthError, Result } from "./utils.js";
  *
  * 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.
+ * to send them to next. An app that also asks for an emailed code answers
+ * `emailCodeRequired`; `verifyEmailCode` finishes it.
  */
 declare function signIn(credentials: {
   email: string;
@@ -24,6 +25,8 @@ declare function signIn(credentials: {
    * `setupOptional`: same, except they may skip it instead.
    */
   step: "verify" | "setup" | "setupOptional";
+} | {
+  status: "emailCodeRequired";
 }, AuthError>>;
 /**
  * Signs the visitor out.

package/dist/auth/methods/password.js

@@ -11,7 +11,8 @@ import { authError } from "./utils.js";
 *
 * 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.
+* to send them to next. An app that also asks for an emailed code answers
+* `emailCodeRequired`; `verifyEmailCode` finishes it.
 */
 async function signIn(credentials) {
 	const result = await makePlatform(sessionConfig().applicationId).tokens(credentials);
@@ -25,6 +26,10 @@ async function signIn(credentials) {
 		const { mfa } = result.data;
 		assert(mfa, "Expected a challenge from sign-in, but got none");
 		writeCookies([makePendingAuthCookie(mfa.challengeToken)]);
+		if (mfa.action === "EMAIL_CODE_REQUIRED") return {
+			success: true,
+			data: { status: "emailCodeRequired" }
+		};
 		return {
 			success: true,
 			data: {

package/dist/auth/platform.js

@@ -71,6 +71,27 @@ function makePlatform(applicationId) {
 		tokens: (credentials) => request(`/v1/vibe/applications/${applicationId}/users/tokens${withAttributes}`, {
 			method: "POST",
 			json: credentials
+		}, z.object({
+			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
+			session: z.object({
+				jwt: z.string(),
+				user: userSchema,
+				permissions: permissionsSchema
+			}).nullish(),
+			mfa: z.object({
+				action: z.enum([
+					"VERIFICATION_REQUIRED",
+					"SETUP_REQUIRED",
+					"SETUP_OPTIONAL",
+					"EMAIL_CODE_REQUIRED"
+				]),
+				challengeToken: z.string()
+			}).nullish()
+		})),
+		emailCodeVerify: (token, code) => request(`/v1/vibe/applications/${applicationId}/users/tokens/email-code/verify${withAttributes}`, {
+			method: "POST",
+			token,
+			json: { code }
 		}, z.object({
 			status: z.enum(["AUTHENTICATED", "MFA_REQUIRED"]),
 			session: z.object({
@@ -87,6 +108,10 @@ function makePlatform(applicationId) {
 				challengeToken: z.string()
 			}).nullish()
 		})),
+		emailCodeResend: (token) => request(`/v1/vibe/applications/${applicationId}/users/tokens/email-code/resend`, {
+			method: "POST",
+			token
+		}, z.null()),
 		sendSignInCode: (email) => request(`/v1/vibe/applications/${applicationId}/users/tokens/send-code`, {
 			method: "POST",
 			json: { email }

package/dist/auth/server.d.ts

@@ -1,5 +1,6 @@
 import { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator } from "./methods/authenticator.js";
 import { sendSignInCode, signInWithCode } from "./methods/code.js";
+import { resendEmailCode, verifyEmailCode } from "./methods/emailCode2fa.js";
 import { signInWithMagicLink } from "./methods/magicLink.js";
 import { signIn, signOut } from "./methods/password.js";
 import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./methods/passwordLink.js";
@@ -34,6 +35,8 @@ declare const auth: {
   sendAuthenticatorResetCode: typeof sendAuthenticatorResetCode;
   resetAuthenticator: typeof resetAuthenticator;
   removeAuthenticator: typeof removeAuthenticator;
+  verifyEmailCode: typeof verifyEmailCode;
+  resendEmailCode: typeof resendEmailCode;
   settings: typeof settings;
   updateProfile: typeof updateProfile;
   removeAvatar: typeof removeAvatar;

package/dist/auth/server.js

@@ -1,6 +1,7 @@
 import { settings } from "./methods/settings.js";
 import { confirmAuthenticatorSetup, removeAuthenticator, resetAuthenticator, sendAuthenticatorResetCode, skipAuthenticatorSetup, startAuthenticatorSetup, verifyAuthenticator } from "./methods/authenticator.js";
 import { sendSignInCode, signInWithCode } from "./methods/code.js";
+import { resendEmailCode, verifyEmailCode } from "./methods/emailCode2fa.js";
 import { signInWithMagicLink } from "./methods/magicLink.js";
 import { signIn, signOut } from "./methods/password.js";
 import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./methods/passwordLink.js";
@@ -33,6 +34,8 @@ const auth = {
 	sendAuthenticatorResetCode,
 	resetAuthenticator,
 	removeAuthenticator,
+	verifyEmailCode,
+	resendEmailCode,
 	settings,
 	updateProfile,
 	removeAvatar,

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.93";
+var version = "0.0.94";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.93",
+  "version": "0.0.94",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 # Softr SDK core

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

@@ -1,19 +1,19 @@
 ---
 name: ai
 description: >-
-  Run an AI model from the app on Softr's own keys, billed to the workspace's
-  AI credits, with nothing to connect: defineAiAction from @softr/sdk declares
-  the action with the catalog model it runs on and its permissions;
-  ai.generate from @softr/sdk/server runs it with a system text, a prompt, an
-  optional JSON schema for an answer that is data, and optional files;
-  ai.stream runs it for an answer the user watches being written. Load this
-  for a summary, an extraction, a classification, a draft, or a chat the app
-  asks a model for, before you decide whether a feature runs on Softr AI
-  or on the user's own account, and before you change the model it runs on.
+  Run an AI model from the app on Softr's own keys, billed to the workspace's AI
+  credits, with nothing to connect: defineAiAction from @softr/sdk declares the
+  action with the catalog model it runs on and its permissions; ai.generate from
+  @softr/sdk/server runs it with a system text, a prompt, an optional JSON
+  schema for an answer that is data, and optional files; ai.stream runs it for
+  an answer the user watches being written. Load this for a summary, an
+  extraction, a classification, a draft, or a chat the app asks a model for,
+  before you decide whether a feature runs on Softr AI or on the user's own
+  account, and before you change the model it runs on.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `ai` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineAiAction` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -3,13 +3,13 @@ name: auth
 description: >-
   Sign a visitor in, out or up from a server function with auth from
   @softr/sdk/server: password, code, Google and magic link, sign-up and its
-  confirmation, the authenticator-app steps, password reset links,
-  updateProfile, and getAuthSettings and useAuthSettings for the methods the app
-  enables. Covers the Result shape, its error codes, and toReturnPath.
+  confirmation, the emailed-code and authenticator-app steps, password reset
+  links, updateProfile, and getAuthSettings and useAuthSettings for the methods
+  the app enables. Covers the Result shape, its error codes, and toReturnPath.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -55,6 +55,13 @@ Signing out:
 | --- | --- |
 | `auth.signOut()` | Ends every session that visitor has in this app, on every device |
 
+Finishing a sign-in that wants a code from the visitor's inbox:
+
+| Call | Does |
+| --- | --- |
+| `auth.verifyEmailCode({ code })` | Answers it with the code that was emailed |
+| `auth.resendEmailCode()` | Emails that code again |
+
 Finishing a sign-in that wants an authenticator app:
 
 | Call | Does |
@@ -197,6 +204,8 @@ Those calls take only what the visitor typed. The sign-in they finish is the one
 
 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`.
 
+`signIn` has a third answer, `{ status: 'emailCodeRequired' }`, for an app that asks a password sign-in for a code from the visitor's inbox as well. The code is already on its way. Show a code field as the next step and finish with `auth.verifyEmailCode({ code })`, see [Finishing a sign-in that needs an emailed code](#finishing-a-sign-in-that-needs-an-emailed-code). That call answers like `signIn` does, so an app that also wants an authenticator app goes on to that step after it.
+
 ## Landing after sign-in
 
 A guard that turns a signed-out visitor away sends them to the page `softr.json` names for that, usually the login page. The page they wanted rides along in the search param named for the login page. `toReturnPath` from `@softr/sdk` reads it back:
@@ -255,10 +264,13 @@ if (answer.message !== null) return setMessage(answer.message)
 if (answer.outcome.status === 'authenticatorRequired') {
   return setStep({ name: 'secondFactor', opensOn: answer.outcome.step })
 }
+if (answer.outcome.status === 'emailCodeRequired') {
+  return setStep({ name: 'emailCode' })
+}
 await navigate({ href: target })
 ```
 
-Three exits: a message for the form to render, the second-factor step, the return target.
+Four exits: a message for the form to render, the emailed-code step, the authenticator step, the return target.
 
 A server function that throws `redirect` needs the hook. Call the imported function directly and the throw never reaches the router, so a successful sign-in leaves the visitor on the form.
 
@@ -385,6 +397,22 @@ The UI has to carry email into step two, plus the name if step one collected one
 
 `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 emailed code
+
+After `signIn` answers `emailCodeRequired`, the visitor owes the code that was just emailed to them:
+
+```ts
+// invalidCode for a wrong or expired code, otherwise the same two-armed result as signIn.
+const result = await auth.verifyEmailCode({ code })
+
+// For a "Resend code" link.
+const sent = await auth.resendEmailCode()
+```
+
+Send `authenticatorRequired` on to the authenticator step, never into the app.
+
+Asking for a resend too soon sends nothing and still succeeds. It answers `notAuthenticated` once the sign-in has run out of time, and the visitor then signs in again from the start.
+
 ### Finishing a sign-in that needs an authenticator app
 
 On `step: 'verify'` the visitor already has an app, and owes a code from it:

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 # Dates, times and numbers

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -3,13 +3,13 @@ name: routes-and-visibility
 description: >-
   Add a route file and declare its settings: definePage with its visibility
   (LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups) and its title,
-  guardRoute or assertRouteAccess in beforeLoad, pageHead in head,
-  isAuthorized and checkAccess anywhere, rendering an access error, and the
-  lint rules that require the declaration.
+  guardRoute or assertRouteAccess in beforeLoad, pageHead in head, isAuthorized
+  and checkAccess anywhere, rendering an access error, and the lint rules that
+  require the declaration.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.92
+  library_version: 0.0.94
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.