@softr/sdk 0.0.50 → 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/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/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.50";
+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",
+  "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
+  library_version: 0.0.51
 ---
 
 # Softr SDK core

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.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
+  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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.50
+  library_version: 0.0.51
 ---
 
 # The current user
@@ -71,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 }) => {

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.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
+  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
+  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
+  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
+  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
+  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
+  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,19 +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".
+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
 
@@ -73,7 +80,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 +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
 
@@ -123,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
 
@@ -132,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')({
@@ -155,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
+  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}',