@softr/sdk 0.0.64-alpha.1 → 0.0.65-alpha.0

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -49,6 +49,7 @@ Four constraints on that shape, because Softr reads the file rather than running
 - The call must initialise a top-level `const`.
 - The import must be a direct named import from `@softr/sdk`.
 - The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
+- Every value inside the literal is written there too. A group id taken from a `const`, a spread or an import is rejected, even when two routes share it: repeat the id on each.
 - Never declare on `__root.tsx`. The root cannot carry an audience, so a declaration there would gate nothing while looking like it does. Softr rejects it. Put the rule on a layout below the root instead.
 
 `userGroupTypes` is a set, so a rule names one audience or several:
@@ -68,7 +69,7 @@ defineVisibility({
 ```
 
 Everyone is both audiences, as in the first line above. A set names each audience at most once and
-is never empty — the type and the build both reject one that does not. `customGroups` narrows only the `LOGGED_IN_USERS` half of the set; absent or empty it
+is never empty — the type and the build both reject one that does not. `customGroups` never stands alone: it narrows the `LOGGED_IN_USERS` half of the set, so the rule still names that half, and one without `userGroupTypes` is a type error. Absent or empty it
 means **any** signed-in visitor, not "nobody".
 
 Take every id in `customGroups` from `docs/user-groups.md`, which lists each group the app has with its name and id. An id the app does not have is a type error.
@@ -115,12 +116,6 @@ Every app declares where a denied visitor goes in `softr.json`, at the app root,
 {
   "$schema": "./node_modules/@softr/sdk/schema/softr.schema.json",
   "auth": {
-    "routes": {
-      "login": { "path": "/login", "redirectParam": "redirect" },
-      "resetPassword": { "path": "/reset-password", "tokenParam": "token" },
-      "acceptInvitation": { "path": "/accept-invitation", "tokenParam": "token" },
-      "magicLink": { "path": "/magic-authentication", "tokenParam": "magic-token" }
-    },
     "guard": {
       "unauthenticated": "/login",
       "alreadyAuthenticated": "/",
@@ -130,17 +125,13 @@ Every app declares where a denied visitor goes in `softr.json`, at the app root,
 }
 ```
 
-Every key is required, because nothing fills in one the file leaves out:
+All three reasons are required, because nothing fills in a reason the file leaves out:
 
-| Reason | Condition | Goes to |
-| --- | --- | --- |
-| `unauthenticated` | Route needs a visitor, none present | `guard.unauthenticated` |
-| `forbidden` | Signed in, in none of the named groups | `guard.forbidden` |
-| `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route | `guard.alreadyAuthenticated` |
-
-`guard.unauthenticated` is where signed-out visitors go. It is usually the same as `routes.login.path`, but it can be another page, such as a public landing page. Every `unauthenticated` redirect, an override's included, carries the page they wanted under `routes.login.redirectParam`. The login page reads it back with `toReturnPath`. See [auth/SKILL.md](../auth/SKILL.md).
-
-`auth.routes` names the app's sign-in pages. To move one, rename its route file and edit its `path` in `auth.routes` to match. When `guard.unauthenticated` points at the login page, edit it too.
+| Reason | Condition |
+| --- | --- |
+| `unauthenticated` | Route needs a visitor, none present |
+| `forbidden` | Signed in, in none of the named groups |
+| `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route |
 
 That file covers every route at once; a route's own overrides win over it. A rule naming both audiences with no `customGroups` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
 
@@ -172,22 +163,20 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### Run the check and then keep going
 
-`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, context)` applies the same rule and throws the same access error, using the default behaviour for each reason. It takes no overrides.
 
-It also narrows `opts.context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
+It also narrows `context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
 
 ```ts
 import { redirect } from '@tanstack/react-router'
 import { assertRouteAccess } from '@softr/sdk'
 
-beforeLoad: (opts) => {
-  assertRouteAccess(visibility, opts)
-  if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
+beforeLoad: ({ context }) => {
+  assertRouteAccess(visibility, context)
+  if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
 },
 ```
 
-Take `opts` whole. A `context` destructured in the parameter list does not narrow.
-
 Reach for `assertRouteAccess` when the route wants the error thrown for it, `isAuthorized(visibility, context)` when it wants the same narrowing without a throw, and `checkAccess(visibility, context)` when it needs to branch on why. `checkAccess` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
 
 `guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **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.

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

@@ -1,47 +0,0 @@
-import { User } from "../user.js";
-import { AuthError, Result } from "./utils.js";
-
-//#region src/auth/methods/passwordLink.d.ts
-
-/**
- * Emails a link to set a new password.
- *
- * Succeeds whether or not the address has an account, and sends nothing when
- * it has none.
- */
-declare function requestPasswordReset(details: {
-  email: string;
-}): Promise<Result<null, AuthError>>;
-/**
- * Checks a password reset or invitation link, and returns the address it was
- * mailed to. The link stays usable.
- */
-declare function checkPasswordLink(details: {
-  token: string;
-}): Promise<Result<{
-  email: string;
-}, AuthError>>;
-/**
- * Sets a new password with a password reset or invitation link, and signs the
- * visitor in.
- *
- * Any success uses up the link, `authenticatorRequired` included, and ends
- * the visitor's other sessions.
- */
-declare function setPasswordWithLink(details: {
-  token: string;
-  password: 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 { checkPasswordLink, requestPasswordReset, setPasswordWithLink };

package/dist/auth/methods/passwordLink.js

@@ -1,86 +0,0 @@
-import { assert, panic } from "../../assertions.js";
-import { writeCookies } from "../../cookies.js";
-import { sessionConfig } from "../config.js";
-import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
-import { makePlatform } from "../platform.js";
-import { authError } from "./utils.js";
-
-//#region src/auth/methods/passwordLink.ts
-/**
-* Emails a link to set a new password.
-*
-* Succeeds whether or not the address has an account, and sends nothing when
-* it has none.
-*/
-async function requestPasswordReset(details) {
-	const result = await makePlatform(sessionConfig().applicationId).forgotPassword(details);
-	if (!result.ok) {
-		if (result.status === 429) return authError("tooManyAttempts", result.message);
-		panic(`Expected the password reset link to be emailed, but got ${result.status}: ${result.message}.`);
-	}
-	return {
-		success: true,
-		data: null
-	};
-}
-/**
-* Checks a password reset or invitation link, and returns the address it was
-* mailed to. The link stays usable.
-*/
-async function checkPasswordLink(details) {
-	const result = await makePlatform(sessionConfig().applicationId).checkPasswordToken(details);
-	if (!result.ok) {
-		if (result.status === 429) return authError("tooManyAttempts", result.message);
-		if (result.status === 400 || result.status === 401) return authError("linkExpired", result.message);
-		panic(`Expected the link to be checked, but got ${result.status}: ${result.message}.`);
-	}
-	return {
-		success: true,
-		data: result.data
-	};
-}
-/**
-* Sets a new password with a password reset or invitation link, and signs the
-* visitor in.
-*
-* Any success uses up the link, `authenticatorRequired` included, and ends
-* the visitor's other sessions.
-*/
-async function setPasswordWithLink(details) {
-	const result = await makePlatform(sessionConfig().applicationId).setPassword(details);
-	if (!result.ok) {
-		if (result.status === 429) return authError("tooManyAttempts", result.message);
-		if (result.status === 400 && result.message === "Password must be at least 8 characters long.") return authError("invalidDetails", result.message);
-		if (result.status === 400 || result.status === 401) return authError("linkExpired", result.message);
-		panic(`Expected the password to be set, but got ${result.status}: ${result.message}.`);
-	}
-	if (result.data.status === "MFA_REQUIRED") {
-		const { mfa } = result.data;
-		assert(mfa, "Expected a challenge from setting a password, 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 setting a password, 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 { checkPasswordLink, requestPasswordReset, setPasswordWithLink };

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

@@ -1,11 +0,0 @@
-import { AuthSettings } from "../platform.js";
-
-//#region src/auth/methods/settings.d.ts
-
-/**
- * How visitors may sign in and sign up to this app, as configured in Studio.
- * A login or sign-up page renders only the methods it lists.
- */
-declare function settings(): Promise<AuthSettings>;
-//#endregion
-export { settings };

package/dist/auth/methods/settings.js

@@ -1,17 +0,0 @@
-import { panic } from "../../assertions.js";
-import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
-
-//#region src/auth/methods/settings.ts
-/**
-* How visitors may sign in and sign up to this app, as configured in Studio.
-* A login or sign-up page renders only the methods it lists.
-*/
-async function settings() {
-	const result = await makePlatform(sessionConfig().applicationId).authSettings();
-	if (!result.ok) panic(`Expected the auth settings, but got ${result.status}: ${result.message}`);
-	return result.data;
-}
-
-//#endregion
-export { settings };

package/dist/auth/platform.d.ts

@@ -1,46 +0,0 @@
-import "./user.js";
-import "./context.js";
-import { z } from "zod";
-
-//#region src/auth/platform.d.ts
-
-declare const authSettingsSchema: z.ZodObject<{
-  loginEnabled: z.ZodBoolean;
-  authenticationMethods: z.ZodArray<z.ZodEnum<{
-    EMAIL: "EMAIL";
-    SSO: "SSO";
-    GOOGLE: "GOOGLE";
-    MAGIC_LINK: "MAGIC_LINK";
-  }>>;
-  signUpPolicy: z.ZodNullable<z.ZodEnum<{
-    DISABLED: "DISABLED";
-    OPEN_TO_PUBLIC: "OPEN_TO_PUBLIC";
-    DOMAIN_RESTRICTED: "DOMAIN_RESTRICTED";
-  }>>;
-  sessionExpirationDays: z.ZodNullable<z.ZodNumber>;
-  inactivityTimeoutMinutes: z.ZodNullable<z.ZodNumber>;
-  emailAuth: z.ZodNullable<z.ZodObject<{
-    loginMethods: z.ZodArray<z.ZodEnum<{
-      PASSWORD: "PASSWORD";
-      EMAIL_CODE: "EMAIL_CODE";
-    }>>;
-    strongPasswords: z.ZodBoolean;
-    emailCodeExpirationMinutes: z.ZodNullable<z.ZodNumber>;
-  }, z.core.$strip>>;
-  googleAuth: z.ZodNullable<z.ZodObject<{
-    clientId: z.ZodNullable<z.ZodString>;
-    userType: z.ZodNullable<z.ZodEnum<{
-      INTERNAL: "INTERNAL";
-      EXTERNAL: "EXTERNAL";
-    }>>;
-  }, z.core.$strip>>;
-  sso: z.ZodNullable<z.ZodObject<{
-    type: z.ZodNullable<z.ZodEnum<{
-      SAML: "SAML";
-      OPEN_ID: "OPEN_ID";
-    }>>;
-  }, z.core.$strip>>;
-}, z.core.$strip>;
-type AuthSettings = z.infer<typeof authSettingsSchema>;
-//#endregion
-export { AuthSettings };

package/dist/softr-config.d.ts

@@ -1 +0,0 @@
-import { z } from "zod";