@softr/sdk 0.0.3 → 0.0.5

package/dist/index.d.ts

@@ -1,84 +1,37 @@
-import { a as ListResult, c as SoftrRecord, d as WorkflowAPI, i as ListOptions, l as SoftrSDK, n as DatasourceAPI, o as SoftrMe, r as DatasourcePermissions, s as SoftrPermissions, t as AuthAPI, u as SoftrUser } from "./types-BLLUI6MI.js";
+import { A as defineVisibility, C as AccessReason, D as SoftrUserGroups, E as SoftrUserGroupId, F as q, M as isAlreadySignedInError, N as isForbiddenError, O as User, P as isUnauthenticatedError, S as AccessError, T as SoftrContext, _ as SoftrUser, a as CreateOptions, b as AccessBehaviour, c as GetOptions, d as MetricOptions, f as MetricResult, g as SoftrSDK, h as SoftrRecord, i as ChartDataResult, j as isAccessError, k as VisibilityHandle, l as ListOptions, m as SoftrPermissions, n as AuthAPI, o as DatasourceAPI, p as SoftrMe, r as ChartDataOptions, s as DatasourcePermissions, t as AggregationFunction, u as ListResult, v as UpdateOptions, w as RouteVisibility, x as AccessCheck, y as WorkflowAPI } from "./types-BYfW8LV3.js";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
 
-//#region src/routes/visibility.d.ts
-type RouteVisibility = {
-  userGroup: "ALL_USERS";
-} | {
-  userGroup: "NON_LOGGED_IN_USERS";
-} | {
-  userGroup: "LOGGED_IN_USERS";
-  userGroupIds?: Array<SoftrUserGroupId>;
-};
-/** Shape of the TanStack route context after the root route's beforeLoad. */
-type SoftrContext = {
-  user: SoftrUser | null;
-};
-type RefusalReason = "unauthenticated" | "forbidden" | "alreadySignedIn";
-type RefusalBehaviour = string | {
-  strategy: "redirect";
-  to: string;
-} | {
-  strategy: "throw";
-};
-type GuardOverrides = Partial<Record<RefusalReason, RefusalBehaviour>>;
-type CheckResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "unauthenticated" | "alreadySignedIn";
-} | {
-  ok: false;
-  reason: "forbidden";
-  requiredGroupIds: Array<SoftrUserGroupId>;
-};
-declare class VisibilityError extends Error {
-  readonly reason: RefusalReason;
-  readonly requiredGroupIds: Array<SoftrUserGroupId> | undefined;
-  constructor(reason: RefusalReason, requiredGroupIds?: Array<SoftrUserGroupId>);
-}
-interface VisibilityHandle {
-  /** Structured check — returns { ok: true } or { ok: false, reason }. */
-  check(context: SoftrContext): CheckResult;
-  /** Returns true if the visitor passes the rule. */
-  isAuthorized(context: SoftrContext): boolean;
-  /**
-   * Throws a VisibilityError if not authorized. Acts as a TypeScript assertion,
-   * narrowing context.user to non-null for code that follows.
-   *
-   * @example
-   * beforeLoad: ({ context }) => {
-   *   visibility.assert(context)
-   *   if (context.user.trialExpired) throw redirect({ to: '/renew' })
-   * }
-   */
-  assert(context: SoftrContext): asserts context is SoftrContext & {
-    user: SoftrUser;
-  };
-  /**
-   * Returns a TanStack beforeLoad handler. On refusal, throws a VisibilityError
-   * caught by the route's errorComponent.
-   *
-   * For redirect-on-refusal, use isAuthorized or check directly and throw
-   * TanStack's redirect() yourself.
-   *
-   * @example
-   * beforeLoad: visibility.guard()
-   * errorComponent: ({ error }) => isVisibilityError(error) ? <NoAccess /> : <AppError />
-   */
-  guard(overrides?: GuardOverrides): (params: {
-    context: SoftrContext;
-  }) => void;
-}
-declare function defineVisibility(rule: RouteVisibility): VisibilityHandle;
-declare function isVisibilityError(error: unknown): error is VisibilityError;
-declare function isUnauthenticatedError(error: unknown): error is VisibilityError & {
-  reason: "unauthenticated";
-};
-declare function isForbiddenError(error: unknown): error is VisibilityError & {
-  reason: "forbidden";
-};
-declare function isAlreadySignedInError(error: unknown): error is VisibilityError & {
-  reason: "alreadySignedIn";
-};
+//#region src/auth/session.d.ts
+
+/**
+ * Returns the signed-in visitor, or `null` when nobody is signed in.
+ *
+ * Await it in the root route's `beforeLoad` to publish the visitor as route
+ * context, which every `defineVisibility` guard then reads. It requires
+ * {@link softrAuthMiddleware} to be registered.
+ *
+ * @example
+ * export const Route = createRootRouteWithContext<SoftrContext>()({
+ *   beforeLoad: async () => ({ user: await getSoftrUser() }),
+ * })
+ */
+declare const getSoftrUser: _tanstack_react_start0.OptionalFetcher<undefined, undefined, Promise<User | null>>;
+//#endregion
+//#region src/auth/middleware.d.ts
+/**
+ * Resolves the Softr visitor for every request, so that `getSoftrUser` and the
+ * route guards have someone to check.
+ *
+ * Register it once, as a global request middleware in the app's `src/start.ts`.
+ * It touches nothing but the visitor.
+ *
+ * @example
+ * export const startInstance = createStart(() => ({
+ *   requestMiddleware: [softrAuthMiddleware()],
+ * }))
+ */
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, {
+  user: User | null;
+}>;
 //#endregion
-export { type AuthAPI, type CheckResult, type DatasourceAPI, type DatasourcePermissions, type GuardOverrides, type ListOptions, type ListResult, type RefusalBehaviour, type RefusalReason, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrSDK, type SoftrUser, VisibilityError, type VisibilityHandle, type WorkflowAPI, defineVisibility, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, isVisibilityError };
+export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type AuthAPI, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourceAPI, type DatasourcePermissions, type GetOptions, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrSDK, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, type WorkflowAPI, defineVisibility, getSoftrUser, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware };

package/dist/index.js

@@ -1,73 +1,170 @@
+import { a as q } from "./query-C6022JhD.js";
+import { redirect } from "@tanstack/react-router";
+import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
+
 //#region src/routes/visibility.ts
-var VisibilityError = class extends Error {
-	reason;
-	requiredGroupIds;
-	constructor(reason, requiredGroupIds) {
-		super(`Access denied: ${reason}`);
-		this.name = "VisibilityError";
-		this.reason = reason;
-		this.requiredGroupIds = requiredGroupIds;
-	}
-};
-function runCheck(rule, context) {
+/**
+* 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;
-	if (rule.userGroup === "ALL_USERS") return { ok: true };
-	if (rule.userGroup === "NON_LOGGED_IN_USERS") return user ? {
-		ok: false,
-		reason: "alreadySignedIn"
-	} : { ok: true };
-	if (!user) return {
-		ok: false,
-		reason: "unauthenticated"
-	};
-	const { userGroupIds } = rule;
-	if (userGroupIds?.length) {
-		if (!userGroupIds.some((id) => user.userGroupIds.includes(id))) return {
+	switch (rule.userGroup) {
+		case "ALL_USERS": return { ok: true };
+		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
 			ok: false,
-			reason: "forbidden",
-			requiredGroupIds: userGroupIds
+			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"
+			};
+		}
 	}
-	return { ok: true };
 }
-function throwIfDenied(result) {
-	if (result.ok) return;
-	throw new VisibilityError(result.reason, result.reason === "forbidden" ? result.requiredGroupIds : void 0);
+function isAccessReason(value) {
+	return ACCESS_REASONS.some((reason) => reason === value);
 }
-function defineVisibility(rule) {
-	function check(context) {
-		return runCheck(rule, context);
-	}
-	function isAuthorized(context) {
-		return runCheck(rule, context).ok;
-	}
-	function assert(context) {
-		throwIfDenied(runCheck(rule, context));
-	}
-	function guard(_overrides) {
-		return ({ context }) => {
-			throwIfDenied(runCheck(rule, context));
-		};
-	}
-	return {
-		check,
-		isAuthorized,
-		assert,
-		guard
-	};
+/**
+* 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 isVisibilityError(error) {
-	return error instanceof VisibilityError;
+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 error instanceof VisibilityError && error.reason === "unauthenticated";
+	return isReason(error, "unauthenticated");
 }
+/** True for an access error thrown because the visitor was in none of the groups. */
 function isForbiddenError(error) {
-	return error instanceof VisibilityError && error.reason === "forbidden";
+	return isReason(error, "forbidden");
 }
+/** True for an access error thrown because a signed-out-only route saw a user. */
 function isAlreadySignedInError(error) {
-	return error instanceof VisibilityError && error.reason === "alreadySignedIn";
+	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
+//#region src/auth/session.ts
+async function resolveVisitor(_request) {
+	return null;
+}
+function visitorFromContext(context) {
+	if (typeof context !== "object" || context === null || !("user" in context)) throw new Error("softrAuthMiddleware has not run: the Start global context carries no `user`. Register it as a global request middleware, e.g. createStart(() => ({ requestMiddleware: [softrAuthMiddleware()] })).");
+	return context.user ?? null;
+}
+/**
+* Returns the signed-in visitor, or `null` when nobody is signed in.
+*
+* Await it in the root route's `beforeLoad` to publish the visitor as route
+* context, which every `defineVisibility` guard then reads. It requires
+* {@link softrAuthMiddleware} to be registered.
+*
+* @example
+* export const Route = createRootRouteWithContext<SoftrContext>()({
+*   beforeLoad: async () => ({ user: await getSoftrUser() }),
+* })
+*/
+const getSoftrUser = createServerFn({ method: "GET" }).handler(async () => visitorFromContext(getGlobalStartContext()));
+
+//#endregion
+//#region src/auth/middleware.ts
+/**
+* Resolves the Softr visitor for every request, so that `getSoftrUser` and the
+* route guards have someone to check.
+*
+* Register it once, as a global request middleware in the app's `src/start.ts`.
+* It touches nothing but the visitor.
+*
+* @example
+* export const startInstance = createStart(() => ({
+*   requestMiddleware: [softrAuthMiddleware()],
+* }))
+*/
+function softrAuthMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ request, next }) => {
+		return next({ context: { user: await resolveVisitor(request) } });
+	});
 }
 
 //#endregion
-export { VisibilityError, defineVisibility, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, isVisibilityError };
+export { defineVisibility, getSoftrUser, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware };