@softr/sdk 0.0.50-alpha.1 → 0.0.51

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,13 +3,20 @@ import { z } from "zod";
 //#region src/auth/user.d.ts
 
 /**
- * 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.
+ * 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"
+ *   }
+ * }
  */
 interface SoftrUserGroups {}
-/** A Softr user group id, narrowed to the app's own ids by {@link SoftrUserGroups}. */
+/** A Softr user group id, narrowed to your own ids if you declare {@link SoftrUserGroups}. */
 type SoftrUserGroupId = SoftrUserGroups extends {
   ids: infer Id extends string;
 } ? Id : string;

package/dist/cli.js

@@ -2,9 +2,7 @@
 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";
@@ -13,44 +11,26 @@ 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 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 {
+	const docFiles = writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
+	const report = {
 		types: OUTPUT,
-		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))
-		}],
+		docsIndex: `${DOCS_DIR}/README.md`,
 		datasources: input.datasources.map(({ id, name }) => ({
 			id,
 			name,
-			doc: `${DOCS_DIR}/${requireDefined(datasourceDocs.fileNames.get(id))}`
+			doc: `${DOCS_DIR}/${requireDefined(docFiles.get(id))}`
 		}))
 	};
-}
-function printReport(report) {
-	console.log(`[softr] wrote ${report.types}`);
-	for (const doc of report.docs) {
-		const state = doc.changed ? "updated" : "unchanged";
-		console.log(`[softr] ${state} ${doc.path} for ${doc.subject}`);
+	if (json) {
+		process.stdout.write(`${JSON.stringify(report)}\n`);
+		return;
 	}
+	console.log(`[softr] wrote ${report.types}`);
+	console.log(`[softr] wrote ${report.docsIndex}`);
 	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, userGroups] = await Promise.all([apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token), apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/access-control/user-groups`, token)]);
+	const registered = await apiFetch(`${studioApiUrl}/v1/applications/${applicationId}/datasources`, token);
 	return {
 		datasources: await Promise.all(registered.map(async ({ name, datasource }) => {
 			return {
@@ -28,7 +28,7 @@ async function fetchSoftrEnvInput(source) {
 				name
 			};
 		})),
-		userGroups
+		userGroupIds: null
 	};
 }
 async function apiFetch(url, token) {

package/dist/codegen/softr-env.js

@@ -13,8 +13,7 @@ function renderSoftrEnv(input, sdkVersion) {
 		"",
 		"declare module \"@softr/sdk\" {",
 		indent(interfaces),
-		"",
-		indent(renderUserGroups(input.userGroups)),
+		...input.userGroupIds === null ? [] : ["", indent(renderUserGroups(input.userGroupIds))],
 		"}",
 		""
 	].join("\n");
@@ -34,11 +33,10 @@ 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 docs/user-groups.md for the app's user groups.
+ * and guide how to use it.
  *
  * 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,32 +1,11 @@
 //#region src/codegen/user-groups.ts
-const DOC_NOTE = "> This document is generated automatically when a change is made in the app's user groups.";
-function renderUserGroups(groups) {
+function renderUserGroups(ids) {
 	return [
 		"interface SoftrUserGroups {",
-		`  ids: ${groups.length === 0 ? "never" : groups.map(({ id }) => JSON.stringify(id)).join(" | ")};`,
+		`  ids: ${ids.length === 0 ? "never" : ids.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, renderUserGroupsDoc };
+export { renderUserGroups };

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

@@ -1,26 +1,24 @@
 import { requireDefined } from "../assertions.js";
 import { renderDatasourceDoc, renderDatasourceIndex } from "./datasource-docs.js";
 import { docFileNames } from "./doc-file-names.js";
-import { writeIfChanged } from "./write-if-changed.js";
+import { mkdirSync, writeFileSync } from "node:fs";
 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. `changed` is true when any file it
-* wrote now reads differently.
+* directory a developer ran the bin from.
 */
 function writeDatasourceDocs(datasources, docsDir) {
 	const context = {
 		datasources: new Map(datasources.map((datasource) => [datasource.id, datasource])),
 		fileNames: docFileNames(datasources)
 	};
-	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)
-	};
+	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;
 }
 
 //#endregion

package/dist/datasource/fields.js

@@ -24,9 +24,17 @@ function makeSortSet(aliases) {
 	};
 	return set;
 }
-/** Ands a list of filters into one group, which is what an accumulated `where` needs. */
+/**
+* Ands the filters of every `where` call into one, which is what an accumulated `where` needs.
+*
+* The backend takes a group inside a group and no deeper, and the docs promise the caller both levels.
+* A wrapper added here would spend one of them: a single `where` handing over an AND with an OR inside
+* would arrive three deep and be refused. So one filter goes through as it is, and a group that is itself
+* an AND contributes its members to the group built here rather than sitting inside it.
+*/
 function andAll(filters) {
-	return group("AND", filters);
+	if (filters.length === 1) return filters[0];
+	return group("AND", filters.flatMap((filter) => filter[INTERNAL_KIND] === "LOGICAL_GROUP" && filter.logicalOperator === "AND" ? filter.filters : [filter]));
 }
 function group(logicalOperator, filters) {
 	return {

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.50-alpha.1";
+var version = "0.0.51";
 
 //#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-alpha.1",
+  "version": "0.0.51",
   "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-alpha.1
+  library_version: 0.0.51
 ---
 
 # Softr SDK core
@@ -137,6 +137,6 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
+  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your 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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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,12 +4,11 @@ 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 and the generated SoftrUserGroups that
-  narrows group ids to the app's own.
+  middleware. Covers the null guest.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50-alpha.1
+  library_version: 0.0.51
 ---
 
 # The current user
@@ -30,7 +29,7 @@ type User = {
   id: string
   email: string
   fullName: string
-  userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
+  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
 }
 ```
 
@@ -72,7 +71,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 }) => {
@@ -84,14 +83,6 @@ 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
-
-The generated `softr-env.d.ts` declares `SoftrUserGroups` with every group id the app has, the predefined groups included. So `user.userGroupIds` and every `userGroupIds` the SDK accepts narrow to those ids, and an id the app does not have stops compiling. A new group appears there once it exists on the app.
-
-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.
-
-Never declare `SoftrUserGroups` yourself. A second declaration does not merge with the generated one. TypeScript keeps one of the two without an error, so the ids you wrote are either ignored or hide the real ones.
-
 ## 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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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,21 +51,25 @@ 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".
-
-Take every id in `userGroupIds` 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.
+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".
 
 ## Core Patterns
 
@@ -75,7 +80,7 @@ Take every id in `userGroupIds` from `docs/user-groups.md`, which lists each gro
 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),
@@ -85,7 +90,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
 
@@ -125,7 +130,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
 
@@ -134,8 +139,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')({
@@ -157,7 +162,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-alpha.1
+  library_version: 0.0.51
 ---
 
 **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}',

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

@@ -1,22 +0,0 @@
-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 };