@softr/sdk 0.0.12 → 0.0.14

package/dist/routes/manifest.js

@@ -0,0 +1,148 @@
+import { crawlRoutes, extractVisibility } from "./discover.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { inferFullPath } from "@tanstack/router-generator";
+
+//#region src/routes/manifest.ts
+var ManifestError = class extends Error {
+	detail;
+	constructor(detail) {
+		super(detail.message);
+		this.name = "ManifestError";
+		this.detail = detail;
+	}
+};
+/** Returns the manifest as the exact text to write. Throws on a declaration it cannot read. */
+async function generateRoutesManifest(root) {
+	const crawl = await crawlRoutes({ root });
+	const routeFiles = new Set([crawl.rootRouteNode.filePath]);
+	for (const node of crawl.routeNodes) routeFiles.add(node.filePath);
+	for (const pieces of Object.values(crawl.routePiecesByPath)) if (pieces.lazy) routeFiles.add(pieces.lazy.filePath);
+	const sources = /* @__PURE__ */ new Map();
+	for (const relative of routeFiles) {
+		const absolute = path.resolve(root, crawl.routesDirectory, relative);
+		const source = await readIfPresent(absolute);
+		if (source !== null) sources.set(absolute, source);
+	}
+	const manifest = buildManifest({
+		crawl,
+		root,
+		sources
+	});
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+function buildManifest(opts) {
+	const routesDirectory = opts.crawl.routesDirectory;
+	const toNode = (node) => {
+		const projectRelative = toProjectRelative(opts.root, routesDirectory, node.filePath);
+		const routePath = node.routePath;
+		if (routePath === void 0) throw new Error(`the route crawl produced a node with no route path: ${projectRelative}`);
+		let declared = visibilityOf(opts, node.filePath);
+		const lazyPiece = opts.crawl.routePiecesByPath[routePath]?.lazy;
+		if (lazyPiece && lazyPiece.filePath !== node.filePath) {
+			const lazyDeclared = visibilityOf(opts, lazyPiece.filePath);
+			if (lazyDeclared !== null && declared !== null) throw new ManifestError({
+				code: "duplicate-declaration",
+				message: `${routePath} declares visibility in both ${projectRelative} and ${lazyDeclared.filePath}; a route has exactly one rule`,
+				filePath: lazyDeclared.filePath,
+				line: lazyDeclared.line,
+				column: lazyDeclared.column
+			});
+			if (lazyDeclared !== null) declared = lazyDeclared;
+		}
+		return {
+			routePath,
+			filePath: projectRelative,
+			...node._fsRouteType ? { _fsRouteType: node._fsRouteType } : {},
+			inferFullPath: inferFullPath(node) ?? null,
+			createFileRouteProps: [...node.createFileRouteProps ?? []].sort(),
+			visibility: declared?.value ?? null,
+			children: (node.children ?? []).map(toNode)
+		};
+	};
+	const rootNode = opts.crawl.rootRouteNode;
+	const rootRelative = toProjectRelative(opts.root, routesDirectory, rootNode.filePath);
+	const rootDeclared = visibilityOf(opts, rootNode.filePath);
+	if (rootDeclared !== null) throw new ManifestError({
+		code: "root-declaration",
+		message: "the root route cannot carry a visibility rule: it would gate sign-in with no way back in. Move this declaration to the routes you want gated.",
+		filePath: rootRelative,
+		line: rootDeclared.line,
+		column: rootDeclared.column
+	});
+	return { root: {
+		routePath: ROOT_ROUTE_ID,
+		filePath: rootRelative,
+		inferFullPath: inferFullPath(rootNode) ?? null,
+		createFileRouteProps: [...rootNode.createFileRouteProps ?? []].sort(),
+		visibility: null,
+		children: opts.crawl.routeTree.map(toNode)
+	} };
+}
+/**
+* `rootRouteId` from `@tanstack/router-core`, which is what a consumer matches against — not the
+* generator's `rootPathId`, which is the base name of `__root.tsx` and names a file, not a route.
+*/
+const ROOT_ROUTE_ID = "__root__";
+/** The crawl's paths are relative to the routes directory; the manifest's are project-relative. */
+function toProjectRelative(root, routesDirectory, filePath) {
+	const absolute = path.resolve(root, routesDirectory, filePath);
+	return path.relative(root, absolute).split(path.sep).join("/");
+}
+const USER_GROUPS = [
+	"ALL_USERS",
+	"NON_LOGGED_IN_USERS",
+	"LOGGED_IN_USERS"
+];
+function checkVisibilityShape(declared) {
+	const reject = (message) => {
+		throw new ManifestError({
+			code: "invalid-visibility",
+			message: `${declared.filePath}: ${message}`,
+			filePath: declared.filePath,
+			line: declared.line,
+			column: declared.column
+		});
+	};
+	const visibility = declared.value;
+	if (typeof visibility !== "object" || Array.isArray(visibility)) reject(`the visibility rule must be an object literal like { userGroup: 'ALL_USERS' }, not ${JSON.stringify(visibility)}`);
+	for (const key of Object.keys(visibility)) {
+		if (key === "userGroup" || key === "userGroupIds") continue;
+		reject(`"${key}" is not part of a visibility rule; a rule has userGroup and, under LOGGED_IN_USERS, userGroupIds. Check the spelling.`);
+	}
+	const userGroup = visibility["userGroup"];
+	if (typeof userGroup !== "string" || !USER_GROUPS.includes(userGroup)) reject(`userGroup must be one of ${USER_GROUPS.join(", ")}, not ${JSON.stringify(userGroup)}. A rule the build cannot read is a route with no rule at all.`);
+	if (!("userGroupIds" in visibility)) return;
+	if (userGroup !== "LOGGED_IN_USERS") reject(`userGroupIds only means anything under LOGGED_IN_USERS, not under ${userGroup}`);
+	const ids = visibility["userGroupIds"];
+	if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string")) reject(`userGroupIds must be an array of group id strings, not ${JSON.stringify(ids)}. Drop the key entirely to mean "any logged-in user".`);
+}
+function visibilityOf(opts, filePath) {
+	const projectRelative = toProjectRelative(opts.root, opts.crawl.routesDirectory, filePath);
+	const source = opts.sources.get(path.resolve(opts.root, opts.crawl.routesDirectory, filePath));
+	if (source === void 0) return null;
+	const result = extractVisibility(source, projectRelative);
+	if (!result.ok) throw new ManifestError(result.error);
+	if (result.visibility === null) return null;
+	const declared = {
+		...result.visibility,
+		filePath: projectRelative
+	};
+	checkVisibilityShape(declared);
+	return declared;
+}
+/**
+* Only ENOENT becomes `null`. The caller reads `null` as "nothing declared here", so swallowing any
+* other read error would turn an unreadable declaration into an ungated route.
+*/
+async function readIfPresent(filePath) {
+	try {
+		return await readFile(filePath, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+//#endregion
+export { ManifestError, generateRoutesManifest };

package/dist/routes/mem-fs.js

@@ -0,0 +1,71 @@
+import * as nodeFs from "node:fs/promises";
+import path from "node:path";
+
+//#region src/routes/mem-fs.ts
+/**
+* Reads through to disk and swallows every write. Driving the generator without this rewrites the
+* app's route sources and strips Start's `Register` block from its routeTree.gen.ts.
+*/
+function createReadOnlyFs() {
+	const writes = /* @__PURE__ */ new Map();
+	return {
+		async stat(filePath) {
+			const stat = await statOrNull(path.resolve(filePath));
+			if (stat === null) return {
+				mtimeMs: SYNTHETIC_MTIME,
+				mode: 420,
+				uid: 0,
+				gid: 0
+			};
+			return {
+				mtimeMs: stat.mtimeMs,
+				mode: Number(stat.mode),
+				uid: Number(stat.uid),
+				gid: Number(stat.gid)
+			};
+		},
+		async rename(oldPath, newPath) {
+			const from = path.resolve(oldPath);
+			const content = writes.get(from);
+			if (content !== void 0) {
+				writes.delete(from);
+				writes.set(path.resolve(newPath), content);
+			}
+		},
+		async writeFile(filePath, content) {
+			writes.set(path.resolve(filePath), content);
+		},
+		async readFile(filePath) {
+			const resolved = path.resolve(filePath);
+			const pending = writes.get(resolved);
+			const stat = await statOrNull(resolved);
+			if (pending !== void 0) return {
+				stat: { mtimeMs: stat?.mtimeMs ?? SYNTHETIC_MTIME },
+				fileContent: pending
+			};
+			if (stat === null) return "file-not-existing";
+			try {
+				const fileContent = await nodeFs.readFile(resolved, "utf8");
+				return {
+					stat: { mtimeMs: stat.mtimeMs },
+					fileContent
+				};
+			} catch {
+				return "file-not-existing";
+			}
+		},
+		async chmod() {},
+		async chown() {}
+	};
+}
+const SYNTHETIC_MTIME = 1n;
+async function statOrNull(filePath) {
+	try {
+		return await nodeFs.stat(filePath, { bigint: true });
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { createReadOnlyFs };

package/dist/routes/visibility.d.ts

@@ -0,0 +1,142 @@
+import { SoftrUserGroupId, User } from "../auth/user.js";
+import { SoftrContext } from "../auth/context.js";
+
+//#region src/routes/visibility.d.ts
+
+/**
+ * Who may see a route.
+ *
+ * - `ALL_USERS` — everyone, signed in or not.
+ * - `NON_LOGGED_IN_USERS` — signed-out visitors only.
+ * - `LOGGED_IN_USERS` — signed-in visitors; with `userGroupIds`, only members of
+ *   at least one of those groups.
+ */
+type RouteVisibility = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+/**
+ * Why a visitor was denied.
+ *
+ * - `unauthenticated` — the route needs a signed-in visitor and there is none.
+ * - `forbidden` — signed in, but in none of the groups the route names.
+ * - `alreadySignedIn` — the route is for signed-out visitors only.
+ */
+declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadySignedIn"];
+type AccessReason = (typeof ACCESS_REASONS)[number];
+/**
+ * What a guard does when it refuses a visitor: redirect to a path, or throw an
+ * {@link AccessError} for the route's `errorComponent` to render. A bare string
+ * is shorthand for redirecting there.
+ */
+type AccessBehaviour = string | {
+  strategy: "redirect";
+  to: string;
+} | {
+  strategy: "throw";
+};
+/** Per-reason overrides of the default {@link AccessBehaviour}. */
+type GuardOverrides = Partial<Record<AccessReason, AccessBehaviour>>;
+/** The result of {@link VisibilityHandle.check}: passed, or denied with a reason. */
+type AccessCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reason: AccessReason;
+};
+/** The one field of {@link SoftrContext} every access check reads. */
+type AccessContext = Pick<SoftrContext, "user">;
+/** Decides whether a visitor passes a visibility rule, without throwing. */
+
+/**
+ * The access error a guard throws. It is plain data, not an `Error` subclass, so
+ * take it as `unknown` in an `errorComponent` and narrow it with
+ * {@link isAccessError}. It carries the reason and nothing else: the error is
+ * serialized into the page, so it never names the groups the route wanted.
+ *
+ * @example
+ * errorComponent: ({ error }: { error: unknown }) =>
+ *   isAccessError(error) ? <NoAccess /> : <AppError />
+ */
+type AccessError = {
+  type: "access_error";
+  reason: AccessReason;
+};
+/**
+ * True for any access error thrown by a guard, whatever its reason.
+ *
+ * An access error arrives as `unknown` — hydrated from the page, or thrown by
+ * anything else at all — so every field is checked before it is narrowed.
+ */
+declare function isAccessError(error: unknown): error is AccessError;
+/** True for an access error thrown because nobody was signed in. */
+declare function isUnauthenticatedError(error: unknown): error is AccessError;
+/** True for an access error thrown because the visitor was in none of the groups. */
+declare function isForbiddenError(error: unknown): error is AccessError;
+/** True for an access error thrown because a signed-out-only route saw a user. */
+declare function isAlreadySignedInError(error: unknown): error is AccessError;
+type Narrowed<R extends RouteVisibility> = R extends {
+  userGroup: "LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: User;
+} : R extends {
+  userGroup: "NON_LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: null;
+} : AccessContext;
+/** The four ways to apply a rule, returned by {@link defineVisibility}. */
+type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
+  /**
+   * A `beforeLoad` handler that denies a visitor who fails the rule.
+   *
+   * By default an unauthenticated visitor is redirected to `/login`, an already
+   * signed-in one to `/`, and a forbidden one gets an {@link AccessError} thrown
+   * in place, for the route's `errorComponent` to render. Pass `overrides` to
+   * change what any one reason does.
+   *
+   * @example
+   * beforeLoad: visibility.guard({ unauthenticated: "/sign-in" })
+   */
+  guard(overrides?: GuardOverrides): (opts: {
+    context: AccessContext;
+  }) => void;
+  /**
+   * Throws the same access error or redirect `guard()` would, for code that
+   * needs to run its own checks after the rule.
+   *
+   * @example
+   * beforeLoad: ({ context }) => {
+   *   visibility.assert(context)
+   *   if (context.user.trialExpired) throw redirect({ to: "/renew" })
+   * }
+   */
+  assert(context: AccessContext): void;
+  /**
+   * Whether the visitor passes the rule. Narrows `context.user` where the rule
+   * allows it.
+   */
+  isAuthorized(context: AccessContext): context is Narrowed<R>;
+  /** The decision and, when a visitor is refused, the reason. Throws nothing. */
+  check(context: AccessContext): AccessCheck;
+};
+/**
+ * Declares who may see a route, and returns the handle that enforces it.
+ *
+ * One call per route file, at module scope: the build reads these declarations
+ * to publish the app's route visibility, so the rule must be a literal.
+ *
+ * @example
+ * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ *
+ * export const Route = createFileRoute("/about")({
+ *   beforeLoad: visibility.guard(),
+ *   component: About,
+ * })
+ */
+declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
+//#endregion
+export { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };

package/dist/routes/visibility.js

@@ -0,0 +1,125 @@
+import { redirect } from "@tanstack/react-router";
+
+//#region src/routes/visibility.ts
+/**
+* Why a visitor was denied.
+*
+* - `unauthenticated` — the route needs a signed-in visitor and there is none.
+* - `forbidden` — signed in, but in none of the groups the route names.
+* - `alreadySignedIn` — the route is for signed-out visitors only.
+*/
+const ACCESS_REASONS = [
+	"unauthenticated",
+	"forbidden",
+	"alreadySignedIn"
+];
+/** Decides whether a visitor passes a visibility rule, without throwing. */
+function checkAccess(rule, context) {
+	const { user } = context;
+	switch (rule.userGroup) {
+		case "ALL_USERS": return { ok: true };
+		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
+			ok: false,
+			reason: "alreadySignedIn"
+		};
+		case "LOGGED_IN_USERS": {
+			if (user === null) return {
+				ok: false,
+				reason: "unauthenticated"
+			};
+			const required = rule.userGroupIds ?? [];
+			if (required.length === 0) return { ok: true };
+			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
+				ok: false,
+				reason: "forbidden"
+			};
+		}
+	}
+}
+function isAccessReason(value) {
+	return ACCESS_REASONS.some((reason) => reason === value);
+}
+/**
+* True for any access error thrown by a guard, whatever its reason.
+*
+* An access error arrives as `unknown` — hydrated from the page, or thrown by
+* anything else at all — so every field is checked before it is narrowed.
+*/
+function isAccessError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const candidate = error;
+	if (candidate.type !== "access_error") return false;
+	return isAccessReason(candidate.reason);
+}
+function isReason(error, reason) {
+	return isAccessError(error) && error.reason === reason;
+}
+/** True for an access error thrown because nobody was signed in. */
+function isUnauthenticatedError(error) {
+	return isReason(error, "unauthenticated");
+}
+/** True for an access error thrown because the visitor was in none of the groups. */
+function isForbiddenError(error) {
+	return isReason(error, "forbidden");
+}
+/** True for an access error thrown because a signed-out-only route saw a user. */
+function isAlreadySignedInError(error) {
+	return isReason(error, "alreadySignedIn");
+}
+const DEFAULT_ACCESS_BEHAVIOUR = {
+	unauthenticated: {
+		strategy: "redirect",
+		to: "/login"
+	},
+	forbidden: { strategy: "throw" },
+	alreadySignedIn: {
+		strategy: "redirect",
+		to: "/"
+	}
+};
+/** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
+function thrownFor(reason, overrides) {
+	const behaviour = overrides?.[reason] ?? DEFAULT_ACCESS_BEHAVIOUR[reason];
+	const resolved = typeof behaviour === "string" ? {
+		strategy: "redirect",
+		to: behaviour
+	} : behaviour;
+	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
+	return {
+		type: "access_error",
+		reason
+	};
+}
+/**
+* Declares who may see a route, and returns the handle that enforces it.
+*
+* One call per route file, at module scope: the build reads these declarations
+* to publish the app's route visibility, so the rule must be a literal.
+*
+* @example
+* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+*
+* export const Route = createFileRoute("/about")({
+*   beforeLoad: visibility.guard(),
+*   component: About,
+* })
+*/
+function defineVisibility(rule) {
+	return {
+		guard: (overrides) => ({ context }) => {
+			const result = checkAccess(rule, context);
+			if (result.ok) return;
+			throw thrownFor(result.reason, overrides);
+		},
+		assert: (context) => {
+			const result = checkAccess(rule, context);
+			if (result.ok) return;
+			throw thrownFor(result.reason, void 0);
+		},
+		isAuthorized: (context) => checkAccess(rule, context).ok,
+		check: (context) => checkAccess(rule, context)
+	};
+}
+
+//#endregion
+export { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError };

package/dist/server.d.ts

@@ -1,115 +1,6 @@
-import { c as ListResult, h as UpdateOptions, i as CreateOptions, l as MetricOptions, n as ChartDataOptions, o as GetOptions, p as SoftrRecord, r as ChartDataResult, s as ListOptions, u as MetricResult, v as User } from "./types-n-Sir_Y2.js";
+import { auth } from "./auth/server.js";
+import { ds } from "./core/datasource.js";
+import { workflow } from "./core/workflow.js";
+import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-
-//#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
-//#region src/auth/methods/password.d.ts
-/**
- * Signs a visitor in with an email and password.
- *
- * The cache is primed from the same `/me` the resolver would have called anyway,
- * so the next request costs no round-trip.
- */
-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.
- *
- * A platform that could not revoke leaves the caller signed out here and
- * possibly still signed in elsewhere — loud outside production, logged in it,
- * because the local half already succeeded.
- */
-declare function signOut(): Promise<void>;
-//#endregion
-//#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
-//#region src/auth/server.d.ts
-/**
- * Server-only auth methods, should be called from the app's own `createServerFn` handlers.
- */
-declare const auth: {
-  signIn: typeof signIn;
-  signOut: typeof signOut;
-  signUp: typeof signUp;
-  confirmSignUp: typeof confirmSignUp;
-};
-//#endregion
-//#region src/core/datasource.d.ts
-declare function listRecords(datasourceId: string, options?: ListOptions): Promise<ListResult>;
-declare function getRecord(datasourceId: string, options: GetOptions): Promise<SoftrRecord | null>;
-declare function createRecord(datasourceId: string, options: CreateOptions): Promise<SoftrRecord>;
-declare function updateRecord(datasourceId: string, options: UpdateOptions): Promise<SoftrRecord>;
-declare function deleteRecord(datasourceId: string, id: string): Promise<void>;
-declare function getMetric(datasourceId: string, options: MetricOptions): Promise<MetricResult>;
-declare function getChartData(datasourceId: string, options: ChartDataOptions): Promise<ChartDataResult>;
-declare const ds: {
-  list: typeof listRecords;
-  get: typeof getRecord;
-  create: typeof createRecord;
-  update: typeof updateRecord;
-  delete: typeof deleteRecord;
-  metric: typeof getMetric;
-  chartData: typeof getChartData;
-};
-//#endregion
-//#region src/core/workflow.d.ts
-declare function triggerWorkflow(workflowId: string, payload?: Record<string, unknown>): Promise<void>;
-declare const workflow: {
-  trigger: typeof triggerWorkflow;
-};
-//#endregion
-//#region src/core/integration.d.ts
-declare function integrationFetch(integrationId: string, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-declare const integration: {
-  fetch: typeof integrationFetch;
-};
-//#endregion
 export { auth, ds, integration, workflow };