@softr/sdk 0.0.51 → 0.0.52

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/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.51";
+var version = "0.0.52";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.51",
+  "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.51
+  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.51
+  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.51
+  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.

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.51
+  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
 }
 ```
 
@@ -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.51
+  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.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.51
+  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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.51
+  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.51
+  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.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.51
+  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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.51
+  library_version: 0.0.52
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.51
+  library_version: 0.0.52
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -71,6 +71,8 @@ Everyone is both audiences, as in the first line above. A set names each audienc
 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
 
 ### 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.51
+  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.