@softr/sdk 0.0.11 → 0.0.13

package/dist/assertions.js

@@ -0,0 +1,68 @@
+//#region src/assertions.ts
+function requireDefined(value, message) {
+	if (value === null || value === void 0) {
+		let error = "Unexpected null or undefined value";
+		if (message) error += ": " + message;
+		throwAtCaller(requireDefined, new Error(error));
+	}
+	return value;
+}
+function assert(condition, message) {
+	if (!condition) throwAtCaller(assert, new AssertionError(unwrapErrorMessage(message)));
+}
+/**
+* Shorthand for throw new AssertionError("Error message")
+* Useful because it is an expression instead of a statement.
+* Can be assigned to any value, because it never returns.
+*/
+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.
+* This is useful for cases where something unexpected happens, but you can still
+* continue in a slightly broken state.
+* For example, if a block has defined a style control with a hardcoded id and
+* that style control is not found, this is definitely a bug, but it's still
+* possible to go on rendering with a fallback value for this style.
+* It is recommended to liberally use soft assertions so that we fail loudly in
+* staging and local environments.
+*
+* A hard assertion would be more appropriate if we wanted to display some data
+* from an object but that object is null. It's better to throw an assertion
+* error at the place we detect this, instead of continuing and potentially
+* causing an exception in an unrelated part of the code.
+*/
+function softAssert(condition, message) {
+	if (!condition) if (process.env.NODE_ENV !== "production") throwAtCaller(softAssert, new SoftAssertionError(unwrapErrorMessage(message)));
+	else console.error(`Assertion failed: ${unwrapErrorMessage(message)}`);
+}
+var AssertionError = class extends Error {
+	name = "AssertionError";
+};
+var SoftAssertionError = class extends Error {
+	name = "SoftAssertionError";
+};
+var UnimplementedError = class extends Error {
+	name = "UnimplementedError";
+};
+function unwrapErrorMessage(message) {
+	return typeof message === "function" ? message() : message ?? "";
+}
+/**
+* Uses chrome's non-standard Error.captureStackTrace to set the top of the stack
+* trace to start from the caller of the supplied function {@param f}.
+* Useful in assertion functions to make sure that the stack trace shows the spot
+* where the assertion failed, not the place where the assertion was thrown.
+*/
+function throwAtCaller(f, ex) {
+	if (Error.captureStackTrace) Error.captureStackTrace(ex, f);
+	throw ex;
+}
+
+//#endregion
+export { assert, panic, requireDefined, softAssert, todo };

package/dist/auth/config.js

@@ -0,0 +1,27 @@
+import { assert } from "../assertions.js";
+
+//#region src/auth/config.ts
+const DEFAULT_SESSION_MAX_AGE = 2160 * 60 * 60;
+function sessionConfig() {
+	const missing = [];
+	const applicationId = process.env.SOFTR_APPLICATION_ID;
+	if (!applicationId) missing.push("SOFTR_APPLICATION_ID");
+	const sessionSecret = process.env.SOFTR_SESSION_SECRET;
+	if (!sessionSecret) missing.push("SOFTR_SESSION_SECRET");
+	if (missing.length > 0) throw new Error(`Missing ${missing.join(", ")}.`);
+	assert(applicationId && sessionSecret);
+	const rawMaxAge = process.env.SOFTR_SESSION_MAX_AGE;
+	let sessionMaxAge = DEFAULT_SESSION_MAX_AGE;
+	if (rawMaxAge) {
+		sessionMaxAge = Number(rawMaxAge);
+		if (!Number.isInteger(sessionMaxAge) || sessionMaxAge <= 0) throw new Error(`SOFTR_SESSION_MAX_AGE must be a positive whole number of seconds, got "${rawMaxAge}".`);
+	}
+	return {
+		applicationId,
+		sessionSecret,
+		sessionMaxAge
+	};
+}
+
+//#endregion
+export { sessionConfig };

package/dist/auth/context.d.ts

@@ -0,0 +1,18 @@
+import { User } from "./user.js";
+import { Permissions } from "./permissions.js";
+
+//#region src/auth/context.d.ts
+/** Who the visitor is and what they may do, for one request. */
+type Session = {
+  /** The visitor, or `null` when signed out. */
+  user: User | null;
+  /** What the visitor may do, signed in or not. */
+  permissions: Permissions;
+};
+/**
+ * The route context the root route publishes — see `getSoftrContext`. The same
+ * session, under the name it carries in the public API.
+ */
+type SoftrContext = Session;
+//#endregion
+export { Session, SoftrContext };

package/dist/auth/isomorphic.d.ts

@@ -0,0 +1,73 @@
+import { User } from "./user.js";
+import { DatasourcePermissions } from "../types.js";
+import { Permissions } from "./permissions.js";
+import { Session, SoftrContext } from "./context.js";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
+
+//#region src/auth/isomorphic.d.ts
+
+/**
+ * Resolves the Softr visitor and their permissions for every request, so that
+ * `getSoftrContext` and the route guards have something to read.
+ *
+ * Register it once, as a global request middleware in the app's `src/start.ts`.
+ * It touches nothing but the session.
+ *
+ * @example
+ * export const startInstance = createStart(() => ({
+ *   requestMiddleware: [softrAuthMiddleware()],
+ * }))
+ */
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, {
+  user: User | null;
+  permissions: Permissions;
+}>;
+/**
+ * Resolves the route context of the root route: the visitor and what they may
+ * do. It requires {@link softrAuthMiddleware} to be registered.
+ *
+ * @example
+ * export const Route = createRootRouteWithContext<SoftrContext>()({
+ *   beforeLoad: async () => await getSoftrContext(),
+ * })
+ */
+declare const getSoftrContext: _tanstack_react_start0.OptionalFetcher<undefined, undefined, Promise<Session>>;
+/**
+ * The context to hand `createRouter`, before any request has resolved one.
+ *
+ * @example
+ * createRouter({ routeTree, context: initialSoftrContext() })
+ *
+ * @example
+ * createRouter({ routeTree, context: { ...initialSoftrContext(), something: "else" } })
+ */
+declare function initialSoftrContext(): SoftrContext;
+/**
+ * Resolves the current user, returning `null` for anonymous visitors.
+ *
+ * @example
+ * function Greeting() {
+ *   const user = useCurrentUser()
+ *   return <p>{user ? `Hello, ${user.name}` : "Please sign in"}</p>
+ * }
+ */
+declare function useCurrentUser(): User | null;
+/**
+ * Resolves what the current user may do with one datasource.
+ *
+ * A rendering hint: every request is authorized again on the server, so never
+ * let this stand in for a permission check.
+ *
+ * Requires the root route to resolve {@link getSoftrContext}.
+ *
+ * @example
+ * function NewRecordButton() {
+ *   const { create } = usePermissions(datasourceId)
+ *   return create ? <button>New record</button> : null
+ * }
+ *
+ * @throws if the application has no such datasource.
+ */
+declare function usePermissions(datasourceId: string): DatasourcePermissions;
+//#endregion
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };

package/dist/auth/isomorphic.js

@@ -0,0 +1,113 @@
+import { assert, panic, requireDefined } from "../assertions.js";
+import { writeCookies } from "../cookies.js";
+import { sessionConfig } from "./config.js";
+import { makePlatform } from "./platform.js";
+import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
+import { rootRouteId, useRouteContext } from "@tanstack/react-router";
+import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
+
+//#region src/auth/isomorphic.ts
+/**
+* Resolves the Softr visitor and their permissions for every request, so that
+* `getSoftrContext` and the route guards have something to read.
+*
+* Register it once, as a global request middleware in the app's `src/start.ts`.
+* It touches nothing but the session.
+*
+* @example
+* export const startInstance = createStart(() => ({
+*   requestMiddleware: [softrAuthMiddleware()],
+* }))
+*/
+function softrAuthMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next }) => {
+		async function getSession() {
+			const token = readSessionToken();
+			const cached = readSessionData(token);
+			if (cached !== null) return cached;
+			const result = await makePlatform(sessionConfig().applicationId).session(token);
+			if (!result.ok) panic(result.message);
+			const session = result.data;
+			if (token !== null && session.user === null) {
+				clearSession();
+				return session;
+			}
+			writeCookies([makeSessionDataCookie(session, token)]);
+			return session;
+		}
+		const { user, permissions } = await getSession();
+		return next({ context: {
+			user,
+			permissions
+		} });
+	});
+}
+/**
+* Resolves the route context of the root route: the visitor and what they may
+* do. It requires {@link softrAuthMiddleware} to be registered.
+*
+* @example
+* export const Route = createRootRouteWithContext<SoftrContext>()({
+*   beforeLoad: async () => await getSoftrContext(),
+* })
+*/
+const getSoftrContext = createServerFn({ method: "GET" }).handler(async () => {
+	const context = getGlobalStartContext();
+	assert(typeof context === "object" && context !== null && "user" in context && "permissions" in context, "softrAuthMiddleware has not run: the Start global context carries no session. Register it as a global request middleware, e.g. createStart(() => ({ requestMiddleware: [softrAuthMiddleware()] })).");
+	return context;
+});
+/**
+* The context to hand `createRouter`, before any request has resolved one.
+*
+* @example
+* createRouter({ routeTree, context: initialSoftrContext() })
+*
+* @example
+* createRouter({ routeTree, context: { ...initialSoftrContext(), something: "else" } })
+*/
+function initialSoftrContext() {
+	return {
+		user: null,
+		permissions: { datasource: {} }
+	};
+}
+/**
+* Resolves the current user, returning `null` for anonymous visitors.
+*
+* @example
+* function Greeting() {
+*   const user = useCurrentUser()
+*   return <p>{user ? `Hello, ${user.name}` : "Please sign in"}</p>
+* }
+*/
+function useCurrentUser() {
+	return useRouteContext({
+		from: rootRouteId,
+		select: (context) => context.user
+	});
+}
+/**
+* Resolves what the current user may do with one datasource.
+*
+* A rendering hint: every request is authorized again on the server, so never
+* let this stand in for a permission check.
+*
+* Requires the root route to resolve {@link getSoftrContext}.
+*
+* @example
+* function NewRecordButton() {
+*   const { create } = usePermissions(datasourceId)
+*   return create ? <button>New record</button> : null
+* }
+*
+* @throws if the application has no such datasource.
+*/
+function usePermissions(datasourceId) {
+	return useRouteContext({
+		from: rootRouteId,
+		select: (context) => requireDefined(context.permissions.datasource[datasourceId], `the application has no datasource "${datasourceId}"`)
+	});
+}
+
+//#endregion
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };

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

@@ -0,0 +1,22 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/password.d.ts
+
+/**
+ * Signs a visitor in with an email and password.
+ */
+declare function signIn(credentials: {
+  email: string;
+  password: string;
+}): Promise<Result<User, AuthError>>;
+/**
+ * Signs the visitor out and clears the session cookies.
+ *
+ * This revokes **every** outstanding session for that user in this app, on every
+ * device: the platform stamps `tokensInvalidatedAt` and rejects anything issued
+ * before it. There is no per-device sign-out.
+ */
+declare function signOut(): Promise<void>;
+//#endregion
+export { signIn, signOut };

package/dist/auth/methods/password.js

@@ -0,0 +1,51 @@
+import { panic, softAssert, todo } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { clearSession, makeSessionDataCookie, makeSessionTokenCookie, readSessionToken } from "../session.js";
+import { authError } from "./utils.js";
+
+//#region src/auth/methods/password.ts
+/**
+* Signs a visitor in with an email and password.
+*/
+async function signIn(credentials) {
+	const platform = makePlatform(sessionConfig().applicationId);
+	const result = await platform.signIn(credentials);
+	if (!result.ok) {
+		if (result.status === 401 || result.status === 429) return authError(result.status === 401 ? "invalidCredentials" : "tooManyAttempts", result.message);
+		if (result.status >= 500) panic(result.message);
+		if (result.status === 400) todo(result.message);
+		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows sign-in.`);
+	}
+	const body = result.data;
+	if (body?.authenticatorAppAction) todo(`Sign-in needs an authenticator step (${body.authenticatorAppAction}), which the SDK cannot finish yet.`);
+	const token = body?.jwt;
+	if (!token) todo("This app is configured for passwordless sign-in, which the SDK cannot finish yet.");
+	const sessionResult = await platform.session(token);
+	if (!sessionResult.ok) panic(sessionResult.message);
+	const session = sessionResult.data;
+	if (session.user === null) panic("Session token issued, but no user came back with it.");
+	writeCookies([makeSessionTokenCookie(token), makeSessionDataCookie(session, token)]);
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* Signs the visitor out and clears the session cookies.
+*
+* This revokes **every** outstanding session for that user in this app, on every
+* device: the platform stamps `tokensInvalidatedAt` and rejects anything issued
+* before it. There is no per-device sign-out.
+*/
+async function signOut() {
+	const token = readSessionToken();
+	clearSession();
+	if (!token) return;
+	const result = await makePlatform(sessionConfig().applicationId).signOut(token);
+	softAssert(result.ok || result.status < 500, () => `Could not revoke the session (${result.status}). This browser is signed out, but other devices may still be.`);
+}
+
+//#endregion
+export { signIn, signOut };

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

@@ -0,0 +1,37 @@
+import { User } from "../user.js";
+import { AuthError, Result } from "./utils.js";
+
+//#region src/auth/methods/signup.d.ts
+
+/**
+ * Starts a sign-up flow by emailing a verification code.
+ *
+ * User only exists once `confirmSignUp` returns the code.
+ */
+declare function signUp(details: {
+  email: string;
+  name?: string;
+}): Promise<Result<null, AuthError>>;
+/**
+ * Finishes sign-up flow with the emailed code and signs the visitor in.
+ *
+ * The platform splits on how the app is configured: a code-only app creates the
+ * user on the second `sign-up` request and answers with a token, while a
+ * password app answers it with an empty 200 and expects the password on
+ * `users/new`.
+ */
+declare function confirmSignUp(details: {
+  email: string;
+  /**
+   * What `users/new` creates the account with, and unused on a code-only app,
+   * which never reaches that request.
+   *
+   * TODO: temporary in one respect — it is spent a second time on the
+   * 400-after-create workaround below, which goes away with the platform fix.
+   */
+  password: string;
+  code: string;
+  name?: string;
+}): Promise<Result<User, AuthError>>;
+//#endregion
+export { confirmSignUp, signUp };

package/dist/auth/methods/signup.js

@@ -0,0 +1,89 @@
+import { panic, todo } from "../../assertions.js";
+import { writeCookies } from "../../cookies.js";
+import { sessionConfig } from "../config.js";
+import { makePlatform } from "../platform.js";
+import { makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { authError } from "./utils.js";
+import { signIn } from "./password.js";
+
+//#region src/auth/methods/signup.ts
+/**
+* Starts a sign-up flow by emailing a verification code.
+*
+* User only exists once `confirmSignUp` returns the code.
+*/
+async function signUp(details) {
+	const result = await makePlatform(sessionConfig().applicationId).signUp(signUpBody(details));
+	if (!result.ok) {
+		if (result.status >= 500) panic(result.message);
+		if (result.status === 409) return authError("emailTaken", result.message);
+		return authError("invalidDetails", result.message);
+	}
+	return {
+		success: true,
+		data: null
+	};
+}
+/**
+* Finishes sign-up flow with the emailed code and signs the visitor in.
+*
+* The platform splits on how the app is configured: a code-only app creates the
+* user on the second `sign-up` request and answers with a token, while a
+* password app answers it with an empty 200 and expects the password on
+* `users/new`.
+*/
+async function confirmSignUp(details) {
+	const platform = makePlatform(sessionConfig().applicationId);
+	const verified = await platform.signUp({
+		...signUpBody(details),
+		token: details.code
+	});
+	if (!verified.ok) {
+		if (verified.status >= 500) panic(verified.message);
+		if (verified.status === 409) return authError("emailTaken", verified.message);
+		return authError("invalidCode", verified.message);
+	}
+	let token = verified.data?.jwt;
+	if (!token) {
+		const created = await platform.new({
+			...signUpBody(details),
+			password: details.password,
+			token: details.code
+		});
+		if (created.ok) token = created.data?.jwt;
+		else {
+			if (created.status >= 500) panic(created.message);
+			if (created.status === 409) return authError("emailTaken", created.message);
+			const signedIn = await signIn({
+				email: details.email,
+				password: details.password
+			});
+			if (!signedIn.success) return authError("invalidCode", created.message);
+			return signedIn;
+		}
+	}
+	if (!token) todo("The sign-up returned no session token. This app is configured for a sign-up flow the SDK cannot finish yet.");
+	const result = await platform.session(token);
+	if (!result.ok) panic(result.message);
+	const session = result.data;
+	if (session.user === null) panic("Session token issued, but no user could be resolved for it.");
+	writeCookies([makeSessionTokenCookie(token), makeSessionDataCookie(session, token)]);
+	return {
+		success: true,
+		data: session.user
+	};
+}
+/**
+* `name` is dropped when absent rather than sent as `undefined`: the platform's
+* validator runs on whatever key is present, and an explicit null is not the
+* same request as no name at all.
+*/
+function signUpBody(details) {
+	return details.name === void 0 ? { email: details.email } : {
+		email: details.email,
+		name: details.name
+	};
+}
+
+//#endregion
+export { confirmSignUp, signUp };

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

@@ -0,0 +1,15 @@
+//#region src/auth/methods/utils.d.ts
+type Result<T, E = Error> = {
+  success: false;
+  error: E;
+} | {
+  success: true;
+  data: T;
+};
+type AuthError = {
+  code: AuthErrorCode;
+  message: string;
+};
+type AuthErrorCode = "invalidCredentials" | "tooManyAttempts" | "emailTaken" | "invalidDetails" | "invalidCode";
+//#endregion
+export { AuthError, Result };

package/dist/auth/methods/utils.js

@@ -0,0 +1,13 @@
+//#region src/auth/methods/utils.ts
+function authError(code, message) {
+	return {
+		success: false,
+		error: {
+			code,
+			message
+		}
+	};
+}
+
+//#endregion
+export { authError };

package/dist/auth/permissions.d.ts

@@ -0,0 +1,17 @@
+import { DatasourcePermissions } from "../types.js";
+import { z } from "zod";
+
+//#region src/auth/permissions.d.ts
+
+/**
+ * What the visitor may do in this app, as the platform sees it.
+ *
+ * Rendering hints, not enforcement: every data request is authorized again
+ * server-side, and these may go stale between the two.
+ */
+type Permissions = {
+  /** Keyed by datasource id. */
+  datasource: Record<string, DatasourcePermissions>;
+};
+//#endregion
+export { Permissions };

package/dist/auth/permissions.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+//#region src/auth/permissions.ts
+const datasourcePermissionsSchema = z.object({
+	read: z.boolean(),
+	create: z.boolean(),
+	update: z.boolean(),
+	delete: z.boolean()
+});
+const permissionsSchema = z.object({ datasource: z.record(z.string(), datasourcePermissionsSchema) });
+
+//#endregion
+export { permissionsSchema };