@softr/sdk 0.0.50 → 0.0.52

package/dist/action.d.ts

@@ -3,12 +3,11 @@ import { SoftrUserGroupId } from "./auth/user.js";
 //#region src/action.d.ts
 type ActionOperation = "read" | "create" | "update" | "delete";
 type ActionPermissions = {
-  userGroup: "ALL_USERS";
+  userGroupTypes: readonly ["NON_LOGGED_IN_USERS"];
+  customGroups?: never;
 } | {
-  userGroup: "NON_LOGGED_IN_USERS";
-} | {
-  userGroup: "LOGGED_IN_USERS";
-  userGroupIds?: Array<SoftrUserGroupId>;
+  userGroupTypes: readonly ["LOGGED_IN_USERS"] | readonly ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] | readonly ["LOGGED_IN_USERS", "NON_LOGGED_IN_USERS"];
+  customGroups?: ReadonlyArray<SoftrUserGroupId>;
 };
 type Action<TResource> = {
   id: string;
@@ -109,7 +108,7 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   id: "publishedPosts",
  *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
- *   permissions: { userGroup: "ALL_USERS" },
+ *   permissions: { userGroupTypes: ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] },
  * })
  *
  * const { records } = await ds
@@ -135,7 +134,7 @@ declare function defineQuery<const TId extends string, const TDatasource$1 exten
  *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "update",
  *   fields: { status: "V1StGXR8", closedAt: "Z7pQm4Kd" },
- *   permissions: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["grp_staff"] },
  * })
  *
  * await ds.update(closeOrder, { id, data: { status: "closed" } })
@@ -145,7 +144,7 @@ declare function defineQuery<const TId extends string, const TDatasource$1 exten
  *   id: "removeOrder",
  *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "delete",
- *   permissions: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["grp_staff"] },
  * })
  *
  * await ds.delete(removeOrder, { id })
@@ -191,7 +190,7 @@ type WorkflowDefinition<TId extends string> = {
  *   id: "notifyTeam",
  *   workflowId: "wf_abc123",
  *   triggerId: "tr_xyz789",
- *   permissions: { userGroup: "LOGGED_IN_USERS" },
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"] },
  *   body: { requestedBy: "{LOGGED_IN_USER:EMAIL}", at: "{CURRENT_DATE_TIME}" },
  * });
  *
@@ -228,7 +227,7 @@ type IntegrationDefinition<TId extends string> = {
  *   integrationId: "25d60213-ef4f-4fa0-b094-a46931b2d120",
  *   method: "GET",
  *   url: "https://www.googleapis.com/calendar/v3/calendars/primary/events",
- *   permissions: { userGroup: "LOGGED_IN_USERS" },
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"] },
  * })
  *
  * const listEvents = integration.createFetcher(listCalendarEvents)

package/dist/auth/user.d.ts

@@ -3,20 +3,13 @@ import { z } from "zod";
 //#region src/auth/user.d.ts
 
 /**
- * Declare this interface in your app to narrow every group id the SDK takes and
- * returns. Without a declaration, a group id is a plain `string`.
- *
- * @example
- * declare module "@softr/sdk" {
- *   interface SoftrUserGroups {
- *     ids:
- *       | "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
- *       | "f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b"
- *   }
- * }
+ * The app's group ids. The app's generated types declare them, the predefined
+ * groups included. Every group id the SDK takes and returns narrows to them.
+ * Never declare it by hand: a second declaration does not merge with the
+ * generated one.
  */
 interface SoftrUserGroups {}
-/** A Softr user group id, narrowed to your own ids if you declare {@link SoftrUserGroups}. */
+/** A Softr user group id, narrowed to the app's own ids by {@link SoftrUserGroups}. */
 type SoftrUserGroupId = SoftrUserGroups extends {
   ids: infer Id extends string;
 } ? Id : string;

package/dist/cli.js

@@ -2,7 +2,9 @@
 import { version } from "./package.js";
 import { requireDefined } from "./assertions.js";
 import { fetchSoftrEnvInput, metadataSourceFromEnv } from "./codegen/fetch-metadata.js";
+import { renderUserGroupsDoc } from "./codegen/user-groups.js";
 import { renderSoftrEnv } from "./codegen/softr-env.js";
+import { writeIfChanged } from "./codegen/write-if-changed.js";
 import { writeDatasourceDocs } from "./codegen/write-datasource-docs.js";
 import { writeFileSync } from "node:fs";
 import path from "node:path";
@@ -11,26 +13,44 @@ import { parseArgs } from "node:util";
 //#region src/cli.ts
 const OUTPUT = "softr-env.d.ts";
 const DOCS_DIR = "docs/datasources";
+const USER_GROUPS_DOC = "docs/user-groups.md";
 async function generate({ json }) {
 	if (json) console.info = console.error;
 	const input = await fetchSoftrEnvInput(metadataSourceFromEnv());
 	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(input, version), "utf8");
-	const docFiles = writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
-	const report = {
+	const report = writeDocs(input);
+	if (json) {
+		process.stdout.write(`${JSON.stringify(report)}\n`);
+		return;
+	}
+	printReport(report);
+}
+function writeDocs(input) {
+	const datasourceDocs = writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
+	return {
 		types: OUTPUT,
-		docsIndex: `${DOCS_DIR}/README.md`,
+		docs: [{
+			subject: "datasources",
+			path: `${DOCS_DIR}/README.md`,
+			changed: datasourceDocs.changed
+		}, {
+			subject: "user groups",
+			path: USER_GROUPS_DOC,
+			changed: writeIfChanged(path.resolve(process.cwd(), USER_GROUPS_DOC), renderUserGroupsDoc(input.userGroups))
+		}],
 		datasources: input.datasources.map(({ id, name }) => ({
 			id,
 			name,
-			doc: `${DOCS_DIR}/${requireDefined(docFiles.get(id))}`
+			doc: `${DOCS_DIR}/${requireDefined(datasourceDocs.fileNames.get(id))}`
 		}))
 	};
-	if (json) {
-		process.stdout.write(`${JSON.stringify(report)}\n`);
-		return;
-	}
+}
+function printReport(report) {
 	console.log(`[softr] wrote ${report.types}`);
-	console.log(`[softr] wrote ${report.docsIndex}`);
+	for (const doc of report.docs) {
+		const state = doc.changed ? "updated" : "unchanged";
+		console.log(`[softr] ${state} ${doc.path} for ${doc.subject}`);
+	}
 	for (const datasource of report.datasources) console.log(`[softr] wrote ${datasource.doc} for ${datasource.name} (${datasource.id})`);
 }
 const { positionals, values } = parseArgs({

package/dist/codegen/datasource-docs.js

@@ -194,7 +194,7 @@ function renderExamples(datasource, datasources) {
 		"  fields: {",
 		...sampled.map((field) => `    ${keyOf(field)}: ${quoted(field.id)}, // ${fieldTypeLiteral(field).slice(1, -1)}`),
 		"  },",
-		"  permissions: { userGroup: 'ALL_USERS' },",
+		"  permissions: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] },",
 		"})",
 		"",
 		`const list${name} = createServerFn().handler(async () => {`,
@@ -226,7 +226,7 @@ function renderExamples(datasource, datasources) {
 		"  fields: {",
 		...writable.map((field) => `    ${keyOf(field)}: ${quoted(field.id)},`),
 		"  },",
-		"  permissions: { userGroup: 'LOGGED_IN_USERS' },",
+		"  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },",
 		"})",
 		"",
 		`const add${name} = createServerFn({ method: 'POST' }).handler(async () =>`,

package/dist/codegen/fetch-metadata.js

@@ -19,7 +19,7 @@ function metadataSourceFromEnv(env = process.env) {
 }
 async function fetchSoftrEnvInput(source) {
 	const { studioApiUrl, datasourceApiUrl, applicationId, token } = source;
-	const registered = await apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token);
+	const [registered, userGroups] = await Promise.all([apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token), apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/access-control/user-groups`, token)]);
 	return {
 		datasources: await Promise.all(registered.map(async ({ name, datasource }) => {
 			return {
@@ -28,7 +28,7 @@ async function fetchSoftrEnvInput(source) {
 				name
 			};
 		})),
-		userGroupIds: null
+		userGroups
 	};
 }
 async function apiFetch(url, token) {

package/dist/codegen/softr-env.js

@@ -13,7 +13,8 @@ function renderSoftrEnv(input, sdkVersion) {
 		"",
 		"declare module \"@softr/sdk\" {",
 		indent(interfaces),
-		...input.userGroupIds === null ? [] : ["", indent(renderUserGroups(input.userGroupIds))],
+		"",
+		indent(renderUserGroups(input.userGroups)),
 		"}",
 		""
 	].join("\n");
@@ -33,10 +34,11 @@ function header(sdkVersion) {
  * THIS FILE IS AUTO GENERATED, DO NOT EDIT THIS MANUALLY
  *
  * This file exists for type checking. See docs/datasources/ for field reference
- * and guide how to use it.
+ * and guide how to use it, and docs/user-groups.md for the app's user groups.
  *
  * Generated by @softr/sdk@${sdkVersion}
  * This file is regenerated automatically when a change is made to the datasource
+ * or to the app's user groups
  */
 
 export {};`;

package/dist/codegen/user-groups.js

@@ -1,11 +1,32 @@
 //#region src/codegen/user-groups.ts
-function renderUserGroups(ids) {
+const DOC_NOTE = "> This document is generated automatically when a change is made in the app's user groups.";
+function renderUserGroups(groups) {
 	return [
 		"interface SoftrUserGroups {",
-		`  ids: ${ids.length === 0 ? "never" : ids.map((id) => JSON.stringify(id)).join(" | ")};`,
+		`  ids: ${groups.length === 0 ? "never" : groups.map(({ id }) => JSON.stringify(id)).join(" | ")};`,
 		"}"
 	].join("\n");
 }
+function renderUserGroupsDoc(groups) {
+	const heading = [
+		"# User groups",
+		"",
+		DOC_NOTE,
+		""
+	];
+	if (groups.length === 0) return [
+		...heading,
+		"This app has no user groups.",
+		""
+	].join("\n");
+	return [
+		...heading,
+		"User groups available in this app:",
+		"",
+		...groups.map(({ id, name, type }) => `- ${name} (${id}), ${type.toLowerCase()}`),
+		""
+	].join("\n");
+}
 
 //#endregion
-export { renderUserGroups };
+export { renderUserGroups, renderUserGroupsDoc };

package/dist/codegen/write-datasource-docs.js

@@ -1,24 +1,26 @@
 import { requireDefined } from "../assertions.js";
 import { renderDatasourceDoc, renderDatasourceIndex } from "./datasource-docs.js";
 import { docFileNames } from "./doc-file-names.js";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { writeIfChanged } from "./write-if-changed.js";
 import path from "node:path";
 
 //#region src/codegen/write-datasource-docs.ts
 /**
 * Writes the index and one file per datasource, and touches nothing else in
 * `docsDir`: the caller resolves it against `process.cwd()`, which can be any
-* directory a developer ran the bin from.
+* directory a developer ran the bin from. `changed` is true when any file it
+* wrote now reads differently.
 */
 function writeDatasourceDocs(datasources, docsDir) {
 	const context = {
 		datasources: new Map(datasources.map((datasource) => [datasource.id, datasource])),
 		fileNames: docFileNames(datasources)
 	};
-	mkdirSync(docsDir, { recursive: true });
-	writeFileSync(path.join(docsDir, "README.md"), renderDatasourceIndex(datasources, context), "utf8");
-	for (const datasource of datasources) writeFileSync(path.join(docsDir, requireDefined(context.fileNames.get(datasource.id))), renderDatasourceDoc(datasource, context), "utf8");
-	return context.fileNames;
+	const writes = [writeIfChanged(path.join(docsDir, "README.md"), renderDatasourceIndex(datasources, context)), ...datasources.map((datasource) => writeIfChanged(path.join(docsDir, requireDefined(context.fileNames.get(datasource.id))), renderDatasourceDoc(datasource, context)))];
+	return {
+		fileNames: context.fileNames,
+		changed: writes.includes(true)
+	};
 }
 
 //#endregion

package/dist/codegen/write-if-changed.js

@@ -0,0 +1,22 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/codegen/write-if-changed.ts
+/** Returns whether it had to write. */
+function writeIfChanged(file, content) {
+	if (readOrNull(file) === content) return false;
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, content, "utf8");
+	return true;
+}
+function readOrNull(file) {
+	try {
+		return readFileSync(file, "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+//#endregion
+export { writeIfChanged };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.50";
+var version = "0.0.52";
 
 //#endregion
 export { version };

package/dist/visibility/audience.d.ts

@@ -16,7 +16,7 @@ type Props = {
  * Requires the root route to resolve {@link getSoftrContext}.
  *
  * @example
- * const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ * const membersOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
  *
  * <Audience visibility={membersOnly} fallback={<Upgrade />}>
  *   <DangerZone />

package/dist/visibility/audience.js

@@ -11,7 +11,7 @@ import { useCurrentUser } from "../auth/isomorphic.js";
 * Requires the root route to resolve {@link getSoftrContext}.
 *
 * @example
-* const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+* const membersOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
 *
 * <Audience visibility={membersOnly} fallback={<Upgrade />}>
 *   <DangerZone />

package/dist/visibility/visibility.d.ts

@@ -2,22 +2,20 @@ import { SoftrUserGroupId, User } from "../auth/user.js";
 import { SoftrContext } from "../auth/context.js";
 
 //#region src/visibility/visibility.d.ts
-
+type AudienceSet = readonly ["NON_LOGGED_IN_USERS"] | readonly ["LOGGED_IN_USERS"] | readonly ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] | readonly ["LOGGED_IN_USERS", "NON_LOGGED_IN_USERS"];
 /**
- * Who may see a route.
+ * Who may see a route or region. `customGroups` narrows only the
+ * `LOGGED_IN_USERS` half.
  *
- * - `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.
+ * @example
+ * { userGroupTypes: ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"] }
+ * { userGroupTypes: ["NON_LOGGED_IN_USERS"] }
+ * { userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["…"] }
+ * { userGroupTypes: ["NON_LOGGED_IN_USERS", "LOGGED_IN_USERS"], customGroups: ["…"] }
  */
 type VisibilityRule = {
-  userGroup: "ALL_USERS";
-} | {
-  userGroup: "NON_LOGGED_IN_USERS";
-} | {
-  userGroup: "LOGGED_IN_USERS";
-  userGroupIds?: Array<SoftrUserGroupId>;
+  userGroupTypes: AudienceSet;
+  customGroups?: ReadonlyArray<SoftrUserGroupId>;
 };
 declare const visibilityBrand: unique symbol;
 /** A rule {@link defineVisibility} has produced. */
@@ -43,15 +41,12 @@ type AccessCheck = {
 type AccessContext = Pick<SoftrContext, "user">;
 /** The decision and, when a visitor is denied, the reason. Throws nothing. */
 declare function checkAccess(visibility: Visibility, context: AccessContext): AccessCheck;
-type Narrowed<R extends VisibilityRule> = R extends {
-  userGroup: "LOGGED_IN_USERS";
-} ? AccessContext & {
+/** Narrows `context.user` only for a rule naming exactly one audience; naming both narrows to neither. */
+type Narrowed<R extends VisibilityRule> = R["userGroupTypes"] extends ReadonlyArray<infer T> ? [T] extends ["LOGGED_IN_USERS"] ? AccessContext & {
   user: User;
-} : R extends {
-  userGroup: "NON_LOGGED_IN_USERS";
-} ? AccessContext & {
+} : [T] extends ["NON_LOGGED_IN_USERS"] ? AccessContext & {
   user: null;
-} : AccessContext;
+} : AccessContext : AccessContext;
 /**
  * Declares who may see a route or a region of the page.
  *
@@ -59,7 +54,7 @@ type Narrowed<R extends VisibilityRule> = R extends {
  * declarations out of the source to publish the app's route visibility.
  *
  * @example
- * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ * const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
  *
  * export const Route = createFileRoute("/about")({
  *   beforeLoad: guardRoute(visibility),

package/dist/visibility/visibility.js

@@ -14,25 +14,21 @@ const ACCESS_REASONS = [
 /** The decision and, when a visitor is denied, the reason. Throws nothing. */
 function checkAccess(visibility, context) {
 	const { user } = context;
-	switch (visibility.userGroup) {
-		case "ALL_USERS": return { ok: true };
-		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
-			ok: false,
-			reason: "alreadyAuthenticated"
-		};
-		case "LOGGED_IN_USERS": {
-			if (user === null) return {
-				ok: false,
-				reason: "unauthenticated"
-			};
-			const required = visibility.userGroupIds ?? [];
-			if (required.length === 0) return { ok: true };
-			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
-				ok: false,
-				reason: "forbidden"
-			};
-		}
-	}
+	const audiences = visibility.userGroupTypes;
+	if (user === null) return audiences.includes("NON_LOGGED_IN_USERS") ? { ok: true } : {
+		ok: false,
+		reason: "unauthenticated"
+	};
+	if (!audiences.includes("LOGGED_IN_USERS")) return {
+		ok: false,
+		reason: "alreadyAuthenticated"
+	};
+	const required = visibility.customGroups ?? [];
+	if (required.length === 0) return { ok: true };
+	return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
+		ok: false,
+		reason: "forbidden"
+	};
 }
 /**
 * Declares who may see a route or a region of the page.
@@ -41,7 +37,7 @@ function checkAccess(visibility, context) {
 * declarations out of the source to publish the app's route visibility.
 *
 * @example
-* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+* const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
 *
 * export const Route = createFileRoute("/about")({
 *   beforeLoad: guardRoute(visibility),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 # Softr SDK core
@@ -137,6 +137,6 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```

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

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -38,7 +38,7 @@ const sales = defineQuery({
     closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
     rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
   },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 ```
 

package/skills/softr-sdk/current-user/SKILL.md

@@ -4,11 +4,12 @@ description: >-
   Read the signed-in Softr visitor: useCurrentUser and the User type,
   context.user in a route's beforeLoad, and context.user inside a server
   function handler, where Start types it from the app's registered request
-  middleware. Covers the null guest.
+  middleware. Covers the null guest and the generated SoftrUserGroups that
+  narrows group ids to the app's own.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 # The current user
@@ -29,7 +30,7 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```
 
@@ -71,7 +72,7 @@ const myInvoices = defineQuery({
   // The datasource id from the table's registration on the application — not the table id.
   datasourceId: '00000000-0000-0000-0000-000000000001',
   fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
@@ -83,6 +84,12 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 
 `context.user` is typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
 
+### Group ids are the app's own
+
+For every group's name and id, read `docs/user-groups.md`. It lists every group the app has, the predefined ones included. Copy an id from there; never derive one from a group's name.
+
+`user.userGroupIds` and every `customGroups` the SDK accepts take only those ids, so an id the app does not have stops compiling. A new group appears in the list once it exists on the app.
+
 ## References
 
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
@@ -34,7 +34,7 @@ const createApplication = defineMutation({
   datasourceId: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
   operation: 'create',
   fields: { name: 'V1StGXR8', resume: 'Z7pQm4Kd' },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const submitApplication = createServerFn({ method: 'POST' })

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -48,7 +48,7 @@ const listCalendarEvents = defineIntegration({
   integrationId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
   method: 'GET',
   url: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 ```
 
@@ -88,7 +88,7 @@ const getStripeCustomer = defineIntegration({
   integrationId: 'wsint-stripe',
   method: 'GET',
   url: 'https://api.stripe.com/v1/customers/{id}',
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const fetchCustomer = createServerFn({ method: 'GET' })
@@ -109,7 +109,7 @@ const postSlackMessage = defineIntegration({
   integrationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
   method: 'POST',
   url: 'https://slack.com/api/chat.postMessage',
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const sendSlackMessage = createServerFn({ method: 'POST' })

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -45,7 +45,7 @@ const createProject = defineMutation({
     status: 'Ru7bVx2cNq0Ed9',  // SELECT, choice ids 'draft' | 'active' | 'archived'
     dueDate: 'Xp2dLh6vKz9Fa3', // DATETIME
   },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 ```
 
@@ -53,7 +53,7 @@ The declaration follows the same rules as a read, spelled out in [record-queries
 
 The mutation's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete mutation declares no `fields`, and giving it some is a type error.
 
-An update or a delete must not be open to visitors: its `permissions` must be `{ userGroup: 'LOGGED_IN_USERS' }`. A visitor who is not logged in must never change or remove a record, so `ALL_USERS` and `NON_LOGGED_IN_USERS` are rejected for these two operations. A create may stay open to visitors, for a sign-up or a contact form.
+An update or a delete must not be open to visitors: its `permissions` must be `{ userGroupTypes: ['LOGGED_IN_USERS'] }`. A visitor who is not logged in must never change or remove a record, so naming `NON_LOGGED_IN_USERS` is rejected for these two operations. A create may stay open to visitors, for a sign-up or a contact form.
 
 ## Core Patterns
 
@@ -81,7 +81,7 @@ const updateProject = defineMutation({
   datasourceId: '00000000-0000-0000-0000-000000000000',
   operation: 'update',
   fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const archiveProject = createServerFn({ method: 'POST' })
@@ -102,7 +102,7 @@ const deleteProject = defineMutation({
   id: 'deleteProject',
   datasourceId: '00000000-0000-0000-0000-000000000000',
   operation: 'delete',
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const removeProject = createServerFn({ method: 'POST' })
@@ -123,7 +123,7 @@ const projectDetail = defineQuery({
   id: 'projectDetail',
   datasourceId: '00000000-0000-0000-0000-000000000000',
   fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const project = await ds.get(projectDetail, { id })

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -46,7 +46,7 @@ const publishedPosts = defineQuery({
     publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
     views: 'mB4kQ8yTn1sWc7',      // NUMBER
   },
-  permissions: { userGroup: 'ALL_USERS' },
+  permissions: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] },
 })
 ```
 
@@ -54,9 +54,9 @@ const publishedPosts = defineQuery({
 - `datasourceId` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `application_register_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name.
 - The keys of `fields` are names you choose. The values are field ids, opaque strings the table's schema gives you: `database_get_table` returns them for a Softr table, `integration_list_table_fields` for a table on a connected database. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
 - `permissions` declares who may run the query, and the SDK enforces it:
-  - `{ userGroup: 'ALL_USERS' }`: everyone, signed out included.
-  - `{ userGroup: 'NON_LOGGED_IN_USERS' }`: signed-out visitors only.
-  - `{ userGroup: 'LOGGED_IN_USERS' }`: any signed-in visitor, narrowed to particular groups with `userGroupIds: ['00000000-0000-0000-0000-00000000000a']`.
+  - `{ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }`: everyone, signed out included. `customGroups` narrows only the signed-in half.
+  - `{ userGroupTypes: ['NON_LOGGED_IN_USERS'] }`: signed-out visitors only.
+  - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`.
 - Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
 
 A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.
@@ -135,7 +135,7 @@ const myInvoices = defineQuery({
   id: 'myInvoices',
   datasourceId: '00000000-0000-0000-0000-000000000001',
   fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 
 const listMyInvoices = createServerFn().handler(async ({ context }) => {
@@ -157,7 +157,7 @@ const productStatuses = defineQuery({
   id: 'productStatuses',
   datasourceId: '00000000-0000-0000-0000-000000000001', // the linked table's datasource id
   fields: { name: 'fZk3Qm9pLw2Xa1' },
-  permissions: { userGroup: 'ALL_USERS' },
+  permissions: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] },
 })
 
 const listProductStatuses = createServerFn().handler(async () => {

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
@@ -26,8 +26,8 @@ Wrap the region in `Audience` and give it a rule:
 import { Audience, defineVisibility } from '@softr/sdk'
 
 const staffOnly = defineVisibility({
-  userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
+  userGroupTypes: ['LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
 })
 
 function InvoiceActions({ invoice }: { invoice: Invoice }) {

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

@@ -2,17 +2,18 @@
 name: routes-and-visibility
 description: >-
   Add a route file to a Softr app and declare who may see it: defineVisibility
-  with ALL_USERS, LOGGED_IN_USERS or NON_LOGGED_IN_USERS, userGroupIds, and the
-  ways to apply a rule: guardRoute and assertRouteAccess in a route,
-  isAuthorized and checkAccess anywhere. Covers per-reason overrides, the
-  redirect and throw strategies, rendering an access error with isAccessError,
-  isUnauthenticatedError, isForbiddenError and isAlreadyAuthenticatedError,
-  guarding a layout, and the lint rule that requires a declaration alongside the
-  rules that reject a duplicate, computed or root-level one.
+  with a userGroupTypes set naming LOGGED_IN_USERS and/or NON_LOGGED_IN_USERS,
+  customGroups, and the ways to apply a rule: guardRoute and assertRouteAccess
+  in a route, isAuthorized and checkAccess anywhere. Covers per-reason
+  overrides, the redirect and throw strategies, rendering an access error with
+  isAccessError, isUnauthenticatedError, isForbiddenError and
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
+  requires a declaration alongside the rules that reject a duplicate, computed
+  or root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -29,7 +30,7 @@ Every route file, without exception, looks like this:
 import { createFileRoute } from '@tanstack/react-router'
 import { defineVisibility, guardRoute } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
+const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
 
 export const Route = createFileRoute('/_app/billing')({
   beforeLoad: guardRoute(visibility),
@@ -50,19 +51,27 @@ Four constraints on that shape, because Softr reads the file rather than running
 - The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
 - 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.
 
-The four rules:
+`userGroupTypes` is a set, so a rule names one audience or several:
 
 ```ts
-defineVisibility({ userGroup: 'ALL_USERS' })            // everyone, signed in or not
-defineVisibility({ userGroup: 'NON_LOGGED_IN_USERS' })  // signed-out only: login, signup
-defineVisibility({ userGroup: 'LOGGED_IN_USERS' })      // any signed-in visitor
-defineVisibility({                                      // those groups only
-  userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
+defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] })  // everyone, signed in or not
+defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS'] })                     // signed-out only: login, signup
+defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })                         // any signed-in visitor
+defineVisibility({                                                                // those groups only
+  userGroupTypes: ['LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
+})
+defineVisibility({                                                                // signed-out visitors AND those groups
+  userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
 })
 ```
 
-Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
+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
+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.
 
 ## Core Patterns
 
@@ -73,7 +82,7 @@ Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
 import { Outlet, createFileRoute } from '@tanstack/react-router'
 import { defineVisibility, guardRoute } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
+const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
 
 export const Route = createFileRoute('/_app')({
   beforeLoad: guardRoute(visibility),
@@ -83,7 +92,7 @@ export const Route = createFileRoute('/_app')({
 
 The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own rule too.
 
-A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can *throw* — a `userGroupIds` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
+A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can *throw* — a `customGroups` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
 
 ### Change what a denied visitor gets
 
@@ -123,7 +132,7 @@ All three reasons are required, because nothing fills in a reason the file leave
 | `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. `ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
+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.
 
 ### Render the error in place
 
@@ -132,8 +141,8 @@ import { createFileRoute } from '@tanstack/react-router'
 import { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
 
 const visibility = defineVisibility({
-  userGroup: 'LOGGED_IN_USERS',
-  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
+  userGroupTypes: ['LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
 })
 
 export const Route = createFileRoute('/_app/billing')({
@@ -155,7 +164,7 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 `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 `context.user` for the rest of the handler: `User` under `LOGGED_IN_USERS`, `null` under `NON_LOGGED_IN_USERS`. `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'

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.52
 ---
 
 **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.
@@ -35,7 +35,7 @@ const sendWelcomeEmail = defineWorkflow({
   id: 'sendWelcomeEmail',
   workflowId: 'c9d8e7f6-a5b4-4c3d-8e2f-1a0b9c8d7e6f',
   triggerId: '926da496-749f-4006-999c-197d8a556122',
-  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
   body: {
     email: '{LOGGED_IN_USER:EMAIL}',  // resolved server-side from the signed-in user
     name: '{LOGGED_IN_USER:NAME}',