@softr/sdk 0.0.31 → 0.0.33

package/dist/auth/isomorphic.js

@@ -1,11 +1,11 @@
 import { assert, panic, requireDefined } from "../assertions.js";
 import { writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
+import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
 import { makePlatform } from "./platform.js";
 import { bootErrorMiddleware } from "../boot-error.js";
-import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
-import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
+import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 
 //#region src/auth/isomorphic.ts
 /**

package/dist/auth/methods/authenticator.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { clearPendingAuth, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionToken } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/authenticator.ts

package/dist/auth/methods/code.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/code.ts

package/dist/auth/methods/magicLink.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/magicLink.ts

package/dist/auth/methods/password.js

@@ -1,8 +1,8 @@
 import { assert, panic, softAssert } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readSessionToken } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/password.ts

package/dist/auth/methods/signup.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/signup.ts

package/dist/auth/methods/social.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
-import { makePlatform } from "../platform.js";
 import { clearPendingAuth, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie } from "../session.js";
+import { makePlatform } from "../platform.js";
 import { authError } from "./utils.js";
 
 //#region src/auth/methods/social.ts

package/dist/auth/platform.js

@@ -1,7 +1,8 @@
+import { fetch } from "../fetch.js";
 import { panic } from "../assertions.js";
+import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
-import { permissionsSchema } from "./permissions.js";
 import { z } from "zod";
 
 //#region src/auth/platform.ts

package/dist/auth/session.js

@@ -1,10 +1,10 @@
 import { readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
+import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
-import { permissionsSchema } from "./permissions.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 import { z } from "zod";
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 
 //#region src/auth/session.ts
 const SESSION_TOKEN = "session_token";

package/dist/boot-error.js

@@ -1,5 +1,5 @@
-import { isNotFound, isRedirect } from "@tanstack/react-router";
 import { createMiddleware } from "@tanstack/react-start";
+import { isNotFound, isRedirect } from "@tanstack/react-router";
 
 //#region src/boot-error.ts
 /**

package/dist/client.d.ts

@@ -1 +1,3 @@
-import "@tanstack/react-start/client-only";
+import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import "@tanstack/react-start/client-only";
+export { type FileItem, useFileUpload };

package/dist/client.js

@@ -1,3 +1,4 @@
+import { useFileUpload } from "./core/use-file-upload.js";
 import "@tanstack/react-start/client-only";
 
-export {  };
+export { useFileUpload };

package/dist/codegen/fetch-metadata.js

@@ -1,3 +1,4 @@
+import { fetch } from "../fetch.js";
 import { panic } from "../assertions.js";
 
 //#region src/codegen/fetch-metadata.ts

package/dist/core/file-upload.d.ts

@@ -0,0 +1,16 @@
+import { DatasourceAction } from "../action.js";
+
+//#region src/core/file-upload.d.ts
+
+/**
+ * The shape of a single uploaded file as it is stored in a record field.
+ * Pre-load existing attachments from the record into this shape for edit forms.
+ */
+type FileAttachment = {
+  url: string;
+  filename: string;
+  id: string;
+};
+declare function upload(action: DatasourceAction, file: File): Promise<FileAttachment>;
+//#endregion
+export { FileAttachment, upload };

package/dist/core/file-upload.js

@@ -0,0 +1,34 @@
+import { fetch } from "../fetch.js";
+import { sessionConfig } from "../auth/config.js";
+import { readSessionToken } from "../auth/session.js";
+import { platformApiUrl } from "../auth/platform.js";
+import { randomUUID } from "node:crypto";
+
+//#region src/core/file-upload.ts
+async function upload(action, file) {
+	const { applicationId } = sessionConfig();
+	const baseUrl = await platformApiUrl();
+	const uploadUrl = new URL(`${baseUrl}/v1/vibe/applications/${applicationId}/actions/${action.id}/uploads`);
+	uploadUrl.searchParams.set("fileName", file.name);
+	const formData = new FormData();
+	formData.append("file", file);
+	const token = readSessionToken();
+	const res = await fetch(uploadUrl.toString(), {
+		method: "POST",
+		headers: token ? { Authorization: `Bearer ${token}` } : {},
+		body: formData
+	});
+	if (!res.ok) throw new Error(`File upload failed: ${res.status}`);
+	const rawUrl = await res.json();
+	const parsed = new URL(rawUrl);
+	const fileId = parsed.searchParams.get("fileId") || randomUUID();
+	parsed.searchParams.delete("fileId");
+	return {
+		url: parsed.toString(),
+		filename: file.name || "Untitled file",
+		id: fileId
+	};
+}
+
+//#endregion
+export { upload };

package/dist/core/integration.js

@@ -1,3 +1,4 @@
+import { fetch } from "../fetch.js";
 import { readSessionToken } from "../auth/session.js";
 import { dsUrl } from "../datasource/record.js";
 

package/dist/core/upload-fn.js

@@ -0,0 +1,16 @@
+import { assert } from "../assertions.js";
+import { upload } from "./file-upload.js";
+import { createServerFn } from "@tanstack/react-start";
+
+//#region src/core/upload-fn.ts
+const uploadServerFn = createServerFn({ method: "POST" }).validator((data) => data).handler(async ({ data }) => {
+	const actionJson = data.get("action");
+	const file = data.get("file");
+	assert(typeof actionJson === "string", "upload: action is required");
+	assert(file instanceof File, "upload: file is required");
+	const attachment = await upload(JSON.parse(actionJson), file);
+	return new Response(JSON.stringify(attachment), { headers: { "Content-Type": "application/json" } });
+});
+
+//#endregion
+export { uploadServerFn };

package/dist/core/use-file-upload.d.ts

@@ -0,0 +1,28 @@
+import { DatasourceAction } from "../action.js";
+import { FileAttachment } from "./file-upload.js";
+
+//#region src/core/use-file-upload.d.ts
+type FileItem = {
+  status: 'uploading';
+  id: string;
+  filename: string;
+  progress: number;
+  cancel: () => void;
+} | (FileAttachment & {
+  status: 'done';
+}) | {
+  status: 'error';
+  id: string;
+  filename: string;
+  error: Error;
+};
+declare function useFileUpload(action: DatasourceAction, options?: {
+  initialAttachments?: FileAttachment[];
+}): {
+  files: FileItem[];
+  isUploading: boolean;
+  upload: (file: File) => void;
+  remove: (id: string) => void;
+};
+//#endregion
+export { FileItem, useFileUpload };

package/dist/core/use-file-upload.js

@@ -0,0 +1,105 @@
+import { uploadServerFn } from "./upload-fn.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/core/use-file-upload.ts
+/**
+* The state machine behind useFileUpload, decoupled from React so it can be
+* tested directly with a plain dispatch function.
+*/
+function createFileUploadStore(uploadFn, dispatch) {
+	let nextId = 0;
+	return {
+		upload(file) {
+			const id = String(++nextId);
+			const controller = new AbortController();
+			const cancel = () => {
+				controller.abort();
+				dispatch((prev) => prev.filter((item) => item.id !== id));
+			};
+			const onProgress = (progress) => {
+				dispatch((prev) => prev.map((item) => item.id === id && item.status === "uploading" ? {
+					...item,
+					progress
+				} : item));
+			};
+			dispatch((prev) => [...prev, {
+				status: "uploading",
+				id,
+				filename: file.name,
+				progress: 0,
+				cancel
+			}]);
+			uploadFn(file, {
+				onProgress,
+				signal: controller.signal
+			}).then((attachment) => {
+				dispatch((prev) => prev.map((item) => item.id === id ? {
+					...attachment,
+					status: "done"
+				} : item));
+			}).catch((error) => {
+				if (controller.signal.aborted) return;
+				dispatch((prev) => prev.map((item) => item.id === id ? {
+					status: "error",
+					id,
+					filename: file.name,
+					error: error instanceof Error ? error : /* @__PURE__ */ new Error("Upload failed")
+				} : item));
+			});
+		},
+		remove(id) {
+			dispatch((prev) => prev.filter((item) => item.id !== id));
+		}
+	};
+}
+function xhrUpload(action, file, { onProgress, signal }) {
+	return new Promise((resolve, reject) => {
+		const xhr = new XMLHttpRequest();
+		const fd = new FormData();
+		fd.append("file", file);
+		fd.append("action", JSON.stringify(action));
+		xhr.upload.onprogress = (e) => {
+			if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
+		};
+		signal.addEventListener("abort", () => {
+			xhr.abort();
+			reject(new DOMException("Upload cancelled", "AbortError"));
+		});
+		xhr.onload = () => {
+			if (xhr.status < 200 || xhr.status >= 300) {
+				reject(/* @__PURE__ */ new Error(`File upload failed: ${xhr.status}`));
+				return;
+			}
+			try {
+				resolve(JSON.parse(xhr.responseText));
+			} catch {
+				reject(/* @__PURE__ */ new Error("File upload: unexpected response format"));
+			}
+		};
+		xhr.onerror = () => reject(/* @__PURE__ */ new Error("File upload failed: network error"));
+		xhr.open("POST", uploadServerFn.url);
+		xhr.send(fd);
+	});
+}
+function useFileUpload(action, options) {
+	const [files, dispatch] = useState(() => (options?.initialAttachments ?? []).map((a) => ({
+		...a,
+		status: "done"
+	})));
+	const actionRef = useRef(action);
+	useEffect(() => {
+		actionRef.current = action;
+	});
+	const store = useRef(createFileUploadStore((file, opts) => xhrUpload(actionRef.current, file, opts), dispatch));
+	const upload = useCallback((file) => store.current.upload(file), []);
+	const remove = useCallback((id) => store.current.remove(id), []);
+	return {
+		files,
+		isUploading: files.some((f) => f.status === "uploading"),
+		upload,
+		remove
+	};
+}
+
+//#endregion
+export { useFileUpload };

package/dist/core/workflow.js

@@ -1,6 +1,7 @@
+import { fetch } from "../fetch.js";
 import { sessionConfig } from "../auth/config.js";
-import { platformApiUrl } from "../auth/platform.js";
 import { readSessionToken } from "../auth/session.js";
+import { platformApiUrl } from "../auth/platform.js";
 
 //#region src/core/workflow.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/datasource/chart.js

@@ -1,3 +1,4 @@
+import { fetch } from "../fetch.js";
 import { assert, panic } from "../assertions.js";
 import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";

package/dist/datasource/record.js

@@ -1,7 +1,8 @@
+import { fetch } from "../fetch.js";
 import { assert, panic } from "../assertions.js";
-import { isDatasourceAction } from "../action.js";
 import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";
+import { isDatasourceAction } from "../action.js";
 import { buildFilterCriteria, buildOrderBy, dealiasFilterCriteria, dealiasOrderBy } from "./filter.js";
 import { andAll, makeFieldSet, makeSortSet } from "./fields.js";
 

package/dist/fetch.js

@@ -0,0 +1,21 @@
+import { logger } from "./logger.js";
+
+//#region src/fetch.ts
+const fetch = async (input, init) => {
+	if (process.env.NODE_ENV === "production") return globalThis.fetch(input, init);
+	const url = input instanceof Request ? input.url : String(input);
+	const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+	const started = Date.now();
+	try {
+		const response = await globalThis.fetch(input, init);
+		logger.info(`${method} ${response.status} ${url} ${Date.now() - started}ms`);
+		return response;
+	} catch (error) {
+		const label = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+		logger.info(`${method} ERR ${url} ${label} in ${Date.now() - started}ms`);
+		throw error;
+	}
+};
+
+//#endregion
+export { fetch };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
 import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { FileAttachment } from "./core/file-upload.js";
 import { SoftrContext } from "./auth/context.js";
 import { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type ActionPermissions, DefaultErrorOverlay, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/logger.js

@@ -0,0 +1,15 @@
+//#region src/logger.ts
+const PREFIX = "[@softr/sdk]";
+function emit(method, args) {
+	if (process.env.NODE_ENV === "production") return;
+	console[method](PREFIX, ...args);
+}
+const logger = {
+	info: (...args) => emit("info", args),
+	log: (...args) => emit("log", args),
+	warn: (...args) => emit("warn", args),
+	error: (...args) => emit("error", args)
+};
+
+//#endregion
+export { logger };

package/dist/package.js

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

package/dist/server.d.ts

@@ -1,6 +1,7 @@
+import { upload } from "./core/file-upload.js";
 import { auth } from "./auth/server.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { auth, ds, integration, workflow };
+export { auth, ds, integration, upload, workflow };

package/dist/server.js

@@ -1,7 +1,8 @@
+import { upload } from "./core/file-upload.js";
 import { auth } from "./auth/server.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
 
-export { auth, ds, integration, workflow };
+export { auth, ds, integration, upload, workflow };

package/dist/vite.d.ts

@@ -1,7 +1,7 @@
 import { PluginOption } from "vite";
 
 //#region src/vite.d.ts
-/** Everything Softr adds to an app's Vite config: the studio edit engine, when the pod supplies one. */
+/** Everything Softr adds to an app's Vite config: the studio edit engine, when there is a pod. */
 declare function softr(): PluginOption[];
 //#endregion
 export { softr };

package/dist/vite.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 //#region src/vite.ts
-/** Everything Softr adds to an app's Vite config: the studio edit engine, when the pod supplies one. */
+/** Everything Softr adds to an app's Vite config: the studio edit engine, when there is a pod. */
 function softr() {
 	return [editEngine()];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "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.31
+  library_version: 0.0.33
 ---
 
 # 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.31
+  library_version: 0.0.33
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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.31
+  library_version: 0.0.33
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.31
+  library_version: 0.0.33
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -0,0 +1,153 @@
+---
+name: file-uploads
+description: >-
+  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk/client does
+  everything — XHR upload with real progress, per-upload cancel, and isUploading to block
+  form submission. No route registration needed; the SDK ships its own server function.
+  For server-side uploads or plain forms, use upload(actionId, file) from @softr/sdk/server.
+  For edit forms pass initialAttachments to pre-load existing attachments.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.33
+---
+
+**Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk/client` and run only in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.
+
+# File uploads
+
+`useFileUpload` handles the full upload cycle — XHR with real progress, per-upload cancel, and state management. It uses a server function the SDK registers itself, so no route file is needed in the app.
+
+## Setup
+
+```ts
+import { defineMutation, type FileAttachment } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+import { useFileUpload, type FileItem } from '@softr/sdk/client'
+```
+
+## Core pattern
+
+```ts
+const createApplication = defineMutation({
+  id: 'createApplication',
+  datasourceId: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
+  operation: 'create',
+  fields: { name: 'V1StGXR8', resume: 'Z7pQm4Kd' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const submitApplication = createServerFn({ method: 'POST' })
+  .validator((data: { name: string; resume: FileAttachment[] }) => data)
+  .handler(async ({ data }) => {
+    await ds.create(createApplication, { data })
+  })
+
+function ApplicationForm() {
+  const { files, isUploading, upload, remove } = useFileUpload(createApplication)
+
+  return (
+    <form onSubmit={async (e) => {
+      e.preventDefault()
+      if (isUploading) return
+      const resume = files.filter(f => f.status === 'done') as FileAttachment[]
+      await submitApplication({ data: { name: e.currentTarget.name.value, resume } })
+    }}>
+      <input name="name" />
+      <input type="file" onChange={(e) => { const f = e.target.files?.[0]; if (f) upload(f) }} />
+      {files.map((f) => (
+        <div key={f.id}>
+          {f.filename}
+          {f.status === 'uploading' && <> — {f.progress}% <button type="button" onClick={f.cancel}>Cancel</button></>}
+          {f.status === 'done' && <button type="button" onClick={() => remove(f.id)}>Remove</button>}
+          {f.status === 'error' && <span> — Failed: {f.error.message}</span>}
+        </div>
+      ))}
+      <button type="submit" disabled={isUploading}>Submit</button>
+    </form>
+  )
+}
+```
+
+`useFileUpload` takes the same `DatasourceAction` you pass to `ds.create` / `ds.update` — no separate upload action to declare.
+
+## What `FileAttachment` looks like
+
+```ts
+type FileAttachment = {
+  url: string      // clean URL, no internal query params
+  filename: string // original filename
+  id: string       // file id extracted from the upload response
+}
+```
+
+Pass `attachments` as the field value in `ds.create` / `ds.update`.
+
+## FileItem shape
+
+`files` is a single ordered array. Each entry is a discriminated union on `status`:
+
+```ts
+type FileItem =
+  | { status: 'uploading'; id: string; filename: string; progress: number; cancel: () => void }
+  | { status: 'done';      id: string; filename: string; url: string }   // FileAttachment + status
+  | { status: 'error';     id: string; filename: string; error: Error }
+```
+
+Items appear in insertion order and transition in place — a completed upload stays at its original position rather than moving to a separate list.
+
+For form submission, filter to `done` items: `files.filter(f => f.status === 'done') as FileAttachment[]`.
+
+## Blocking form submission
+
+`isUploading` is `true` while any item has `status: 'uploading'`. Disable the submit button and guard the submit handler.
+
+## Edit forms: pre-loading existing attachments
+
+```ts
+const { files, isUploading, upload, remove } = useFileUpload(
+  updateApplication,
+  { initialAttachments: record.fields.resume ?? [] },
+)
+```
+
+Pre-loaded attachments appear as `status: 'done'` items at the start of `files`. The existing attachments already have the `FileAttachment` shape from the datasource record.
+
+## Server-side uploads and plain forms
+
+For server-side use (no progress tracking needed) or plain HTML forms, use `upload` directly:
+
+```ts
+import { upload, ds } from '@softr/sdk/server'
+
+const submitResume = createServerFn({ method: 'POST' })
+  .validator((fields: FormData) => fields)
+  .handler(async ({ data }) => {
+    const uploaded = await upload(createApplication, data.get('cv') as File)
+    await ds.create(createApplication, {
+      data: { fullName: data.get('fullName') as string, cv: [uploaded] },
+    })
+    return new Response(null, { status: 303, headers: { Location: '/thank-you' } })
+  })
+
+function ApplyForm() {
+  return (
+    <form action={submitResume.url} method="POST">
+      <input type="text" name="fullName" />
+      <input type="file" name="cv" />
+      <button type="submit">Apply for this role</button>
+    </form>
+  )
+}
+```
+
+## Failure modes
+
+**Submitting while `isUploading` is true.** Only `done` items have a `url` and should be submitted. In-progress uploads finish after the record is saved and are never included. Always filter to `status === 'done'` before passing to `ds.create` / `ds.update`.
+
+**Not passing `initialAttachments` on an edit form.** The hook starts with an empty list. Without pre-loading, the first save erases existing attachments.
+
+## References
+
+- [record-mutations/SKILL.md](../record-mutations/SKILL.md): creating and updating records with the collected attachments
+- [current-user/SKILL.md](../current-user/SKILL.md): gating uploads to the signed-in user

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

@@ -3,13 +3,13 @@ name: integrations
 description: >-
   Call a third-party service connected to the app as an integration:
   defineIntegration from @softr/sdk declares the action with its datasourceId
-  and permissions; integration.createFetcher from @softr/sdk/server binds it
-  and returns a fetcher function you call with url, optional method, headers,
-  and body. Check res.ok before res.json().
+  and permissions; integration.createFetcher from @softr/sdk/server binds it and
+  returns a fetcher function you call with url, optional method, headers, and
+  body. Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.31
+  library_version: 0.0.33
 ---
 
 **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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.31
+  library_version: 0.0.33
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.31
+  library_version: 0.0.33
 ---
 
 **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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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.31
+  library_version: 0.0.33
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

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

@@ -1,14 +1,15 @@
 ---
 name: workflows
 description: >-
-  Trigger a Softr workflow from a server function: defineWorkflow from @softr/sdk
-  declares the action with its workflowId, triggerId, permissions, and optional
-  hardcoded body; workflow.trigger from @softr/sdk/server fires it with an optional
-  flat runtime payload and resolves to void when the workflow finishes.
+  Trigger a Softr workflow from a server function: defineWorkflow from
+  @softr/sdk declares the action with its workflowId, triggerId, permissions,
+  and optional hardcoded body; workflow.trigger from @softr/sdk/server fires it
+  with an optional flat runtime payload and resolves to void when the workflow
+  finishes.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.31
+  library_version: 0.0.33
 ---
 
 **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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.