@softr/sdk 0.0.91 → 0.0.92-emailotc.0

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/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react6 from "react";
+import * as react2 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react6.JSX.Element;
+}: Props): react2.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/formatting.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import * as react0 from "react";
+import * as react3 from "react";
 import { ReactNode } from "react";
 
 //#region src/formatting.d.ts
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
+}): react3.FunctionComponentElement<react3.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react0.FunctionComponentElement<react0.FragmentProps>;
+}): react3.FunctionComponentElement<react3.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.91";
+var version = "0.0.92-emailotc.0";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react4 from "react";
+import * as react0 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react4.FunctionComponentElement<react4.FragmentProps>;
+declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.91",
+  "version": "0.0.92-emailotc.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" }
-  },
-  "bin": { "softr-sdk": "./dist/cli.js" },
-  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
-  "publishConfig": { "access": "public" },
+    ".": {
+      "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",
+    "schema",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -42,7 +63,9 @@
       "optional": true
     }
   },
-  "keywords": ["tanstack-intent"],
+  "keywords": [
+    "tanstack-intent"
+  ],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

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

@@ -3,7 +3,7 @@ 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,
+  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:
@@ -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: