@softr/sdk 0.0.50-alpha.1 → 0.0.50

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/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.50";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.50-alpha.1",
+  "version": "0.0.50",
   "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.50
 ---
 
 # 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.50
 ---
 
 **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.50
 ---
 
 **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.

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.50
 ---
 
 # 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
 }
 ```
 
@@ -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.50
 ---
 
 **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.

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.50
 ---
 
 **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.

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.50
 ---
 
 **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.50
 ---
 
 **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.

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.50
 ---
 
 **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.

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.50
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/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.50
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -64,8 +64,6 @@ defineVisibility({                                      // those groups only
 
 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.
-
 ## Core Patterns
 
 ### Guard a whole section with one layout route

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.50
 ---
 
 **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.

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 };