@softr/sdk 0.0.32 → 0.0.35-alpha.0

package/dist/action.d.ts

@@ -200,25 +200,25 @@ type WorkflowDefinition<TId extends string> = {
 declare function defineWorkflow<const TId extends string>(definition: WorkflowDefinition<TId>): WorkflowAction<TId>;
 type IntegrationResource = {
   type: "INTEGRATION";
-  datasourceId: string;
+  integrationId: string;
 };
 type IntegrationAction<TId extends string = string> = Action<IntegrationResource> & {
   id: TId;
 };
 type IntegrationDefinition<TId extends string> = {
   id: TId;
-  datasourceId: string;
+  integrationId: string;
   permissions: ActionPermissions;
 };
 /**
- * Declares an integration: which connected data source to call through, and who may call it.
+ * Declares an integration: which workspace integration to call through, and who may call it.
  *
  * Pass the returned object to `integration.createFetcher()` to get a bound fetcher.
  *
  * @example
  * const googleCalendar = defineIntegration({
  *   id: "googleCalendar",
- *   datasourceId: "25d60213-ef4f-4fa0-b094-a46931b2d120",
+ *   integrationId: "25d60213-ef4f-4fa0-b094-a46931b2d120",
  *   permissions: { userGroup: "LOGGED_IN_USERS" },
  * })
  *

package/dist/action.js

@@ -38,12 +38,12 @@ function defineWorkflow(definition) {
 	};
 }
 function defineIntegration(definition) {
-	const { id, datasourceId, permissions } = definition;
+	const { id, integrationId, permissions } = definition;
 	return {
 		id,
 		resource: {
 			type: "INTEGRATION",
-			datasourceId
+			integrationId
 		},
 		permissions
 	};

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,8 +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/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

@@ -12,7 +12,7 @@ async function integrationFetch(action, url, { method = "GET", headers = {}, bod
 		headers
 	};
 	if (upperMethod !== "GET" && upperMethod !== "HEAD" && body !== void 0) payload.body = body;
-	return fetch(`${dsUrl(action.resource.datasourceId)}/proxy`, {
+	return fetch(`${dsUrl(action.id)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",

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

@@ -191,9 +191,9 @@ function mapChartRows(columns, data) {
 	});
 }
 async function executeChart(query, state) {
-	const { datasourceId, select } = resolveTarget(query, "read");
+	const { actionId, select } = resolveTarget(query, "read");
 	const { body, columns } = buildChartRequest(state, select);
-	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
+	const res = await fetch(`${dsUrl(actionId)}/chart/data`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -202,7 +202,7 @@ async function executeChart(query, state) {
 		},
 		body: JSON.stringify(body)
 	});
-	if (!res.ok) throw new Error(`Softr datasource chart failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource chart failed for action "${actionId}": ${res.status}`);
 	const payload = await res.json();
 	return {
 		data: mapChartRows(columns, payload.data),
@@ -264,9 +264,9 @@ function readMetricValue(responseKey, data) {
 	return row[responseKey];
 }
 async function executeMetric(query, handle, filters) {
-	const { datasourceId, select } = resolveTarget(query, "read");
+	const { actionId, select } = resolveTarget(query, "read");
 	const { body, responseKey } = buildMetricRequest(handle, filters, select);
-	const res = await fetch(`${dsUrl(datasourceId)}/chart/data`, {
+	const res = await fetch(`${dsUrl(actionId)}/chart/data`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -275,7 +275,7 @@ async function executeMetric(query, handle, filters) {
 		},
 		body: JSON.stringify(body)
 	});
-	if (!res.ok) throw new Error(`Softr datasource metric failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource metric failed for action "${actionId}": ${res.status}`);
 	const payload = await res.json();
 	return {
 		value: readMetricValue(responseKey, payload.data),

package/dist/datasource/record.js

@@ -1,19 +1,19 @@
 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";
 
 //#region src/datasource/record.ts
 const MAX_RECORD_COUNT = 100;
-const dsUrl = (datasourceId) => {
+const dsUrl = (actionId) => {
 	const datasourceApiUrl = process.env.SOFTR_DATASOURCE_API_URL;
 	if (!datasourceApiUrl) panic("SOFTR_DATASOURCE_API_URL is not set.");
 	const applicationId = process.env.SOFTR_APPLICATION_ID;
 	if (!applicationId) panic("SOFTR_APPLICATION_ID is not set.");
-	return `${withoutTrailingSlash(datasourceApiUrl)}/v1/datasource/vibe/applications/${applicationId}/datasources/${datasourceId}`;
+	return `${withoutTrailingSlash(datasourceApiUrl)}/v1/datasource/vibe/applications/${applicationId}/actions/${actionId}`;
 };
 /**
 * Queries a list of records from the datasource.
@@ -65,12 +65,12 @@ function listRecords(query) {
 	return builder;
 }
 async function executeList(query, args) {
-	const { datasourceId, select } = resolveTarget(query, "read");
+	const { actionId, select } = resolveTarget(query, "read");
 	const count = Math.min(args.limit ?? 20, MAX_RECORD_COUNT);
 	const offset = args.offset ?? null;
 	const filterCriteria = args.filters.length ? dealiasFilterCriteria(buildFilterCriteria(andAll(args.filters)), select) : {};
 	const sortingOption = args.orderBy.length ? dealiasOrderBy(buildOrderBy(args.orderBy), select) : void 0;
-	const res = await fetch(`${dsUrl(datasourceId)}/records`, {
+	const res = await fetch(`${dsUrl(actionId)}/records`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -87,7 +87,7 @@ async function executeList(query, args) {
 			}
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource list failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource list failed for "${actionId}": ${res.status}`);
 	const payload = await res.json();
 	const nextOffset = payload.offset < payload.total ? payload.offset : null;
 	return {
@@ -139,9 +139,9 @@ function getRecord(query, options) {
 }
 async function executeGet(query, id, filters) {
 	assert(id, "a record id must not be empty");
-	const { datasourceId, select } = resolveTarget(query, "read");
+	const { actionId, select } = resolveTarget(query, "read");
 	const filterCriteria = filters.length ? dealiasFilterCriteria(buildFilterCriteria(andAll(filters)), select) : {};
-	const res = await fetch(`${dsUrl(datasourceId)}/records/${id}`, {
+	const res = await fetch(`${dsUrl(actionId)}/records/${id}`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -153,7 +153,7 @@ async function executeGet(query, id, filters) {
 			filterCriteria
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource get failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource get failed for action "${actionId}": ${res.status}`);
 	const contentLength = res.headers.get("Content-Length");
 	if (contentLength && parseInt(contentLength, 10) === 0) return null;
 	const record = await res.json();
@@ -171,10 +171,10 @@ async function executeGet(query, id, filters) {
 * })
 */
 async function createRecord(action, options) {
-	const { datasourceId, select } = resolveTarget(action, "create");
+	const { actionId, select } = resolveTarget(action, "create");
 	const data = options.data;
 	const rawFields = dealiasData(data, select);
-	const res = await fetch(`${dsUrl(datasourceId)}/records/new`, {
+	const res = await fetch(`${dsUrl(actionId)}/records/new`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -182,7 +182,7 @@ async function createRecord(action, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource create failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource create failed for action "${actionId}": ${res.status}`);
 	const record = await res.json();
 	return {
 		id: record.id,
@@ -200,10 +200,10 @@ async function createRecord(action, options) {
 */
 async function updateRecord(action, options) {
 	if (!options.id) throw new Error(`Softr datasource update: id must not be empty`);
-	const { datasourceId, select } = resolveTarget(action, "update");
+	const { actionId, select } = resolveTarget(action, "update");
 	const data = options.data;
 	const rawFields = dealiasData(data, select);
-	const res = await fetch(`${dsUrl(datasourceId)}/records/${options.id}`, {
+	const res = await fetch(`${dsUrl(actionId)}/records/${options.id}`, {
 		method: "PATCH",
 		headers: {
 			"Content-Type": "application/json",
@@ -211,7 +211,7 @@ async function updateRecord(action, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource update failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource update failed for action "${actionId}": ${res.status}`);
 	const record = await res.json();
 	return {
 		id: record.id,
@@ -225,12 +225,12 @@ async function updateRecord(action, options) {
 * await ds.delete(removePost, { id: "record-id" })
 */
 async function deleteRecord(action, options) {
-	const { datasourceId } = resolveTarget(action, "delete");
-	const res = await fetch(`${dsUrl(datasourceId)}/records/${options.id}`, {
+	const { actionId } = resolveTarget(action, "delete");
+	const res = await fetch(`${dsUrl(actionId)}/records/${options.id}`, {
 		method: "DELETE",
 		headers: { Authorization: `Bearer ${readSessionToken()}` }
 	});
-	if (!res.ok) throw new Error(`Softr datasource delete failed for "${datasourceId}": ${res.status}`);
+	if (!res.ok) throw new Error(`Softr datasource delete failed for action "${actionId}": ${res.status}`);
 }
 function resolveTarget(subject, operation) {
 	const declaredBy = operation === "read" ? "defineQuery" : "defineMutation";
@@ -238,7 +238,7 @@ function resolveTarget(subject, operation) {
 	const action = subject;
 	assert(action.resource.operation === operation, () => `action "${action.id}" is declared as ${action.resource.operation}, not ${operation}`);
 	return {
-		datasourceId: action.resource.datasourceId,
+		actionId: action.id,
 		select: action.resource.fields ?? {}
 	};
 }

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/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.32";
+var version = "0.0.35-alpha.0";
 
 //#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.32",
+  "version": "0.0.35-alpha.0",
   "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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 # 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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.35-alpha.0
+---
+
+**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

@@ -2,14 +2,14 @@
 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
+  defineIntegration from @softr/sdk declares the action with its integrationId
   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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.
@@ -34,14 +34,14 @@ When the user attaches integrations to the chat, they appear in the `## Attached
 - "Gmail" — database `<databaseId>`, integration `<integrationId>`, type `GMAIL`
 ```
 
-Use `databaseId` as `datasourceId` in `defineIntegration` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it anywhere. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path, including any query parameters, directly in the `url` string.
+Pass the `integration` value as `integrationId` in `defineIntegration`. The `database` value is the table coordinate; integrations do not use it, so do not pass it anywhere. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path, including any query parameters, directly in the `url` string.
 
 ## Declare the integration action
 
 ```ts
 const googleCalendar = defineIntegration({
   id: 'googleCalendar',
-  datasourceId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
+  integrationId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
   permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 ```
@@ -71,7 +71,7 @@ Include query parameters directly in the `url` string — there is no separate `
 ```ts
 const slackDs = defineIntegration({
   id: 'slack',
-  datasourceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  integrationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
   permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.32
+  library_version: 0.0.35-alpha.0
 ---
 
 **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.