@softr/sdk 0.0.42 → 0.0.44

package/dist/boot-error.js

@@ -23,6 +23,17 @@ function bootErrorMiddleware() {
 		}
 	});
 }
+/**
+* Faults of the dev server rather than the app: a module graph swapped under a render already in
+* flight, so React's dispatcher or a split chunk belongs to a generation that is gone. The next
+* request reads the settled graph and succeeds, which is why these clear on their own — and why
+* showing one is worse than useless. The page invites the reader to copy it to the agent, and an
+* agent handed a phantom spends a repair round looking for it in code that is correct.
+*/
+const TRANSIENT = [/Cannot read properties of (?:null|undefined) \(reading 'use[A-Z]/, /Failed to fetch dynamically imported module/];
+function isTransientBootError(message) {
+	return TRANSIENT.some((pattern) => pattern.test(message));
+}
 function errorPage(error) {
 	if (process.env.NODE_ENV === "production") return page("Something went wrong", "This page couldn’t be shown. Try again in a moment, and if it keeps happening, reach out to the owner of this app.", { note: "If you are the owner, you can check what happened in Studio." });
 	const cause = error instanceof Error ? error.cause : void 0;
@@ -31,6 +42,7 @@ function errorPage(error) {
 	const stack = root instanceof Error ? root.stack : void 0;
 	return page("This app crashed", "The app stopped before it could start. The technical details below show where it failed and can be copied to the agent to help fix the issue.", {
 		note: "These details are only shown because the app is running in development mode.",
+		autoRetry: isTransientBootError(message),
 		detail: `<pre class="message">${escapeHtml(message)}</pre>`,
 		actions: stack ? `<button type="button" id="toggle" aria-expanded="true" aria-controls="panel">
              <svg class="chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
@@ -71,7 +83,7 @@ function errorPage(error) {
            <\/script>` : ""
 	});
 }
-function page(title, description, { note = "", detail = "", actions = "", panel = "" } = {}) {
+function page(title, description, { note = "", detail = "", actions = "", panel = "", autoRetry = false } = {}) {
 	return `<!doctype html>
 <html lang="en">
   <head>
@@ -222,7 +234,7 @@ function page(title, description, { note = "", detail = "", actions = "", panel
     </style>
   </head>
   <body>
-    <main>
+    <main${autoRetry ? " hidden" : ""}>
       <div class="alert">
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
       </div>
@@ -241,9 +253,37 @@ function page(title, description, { note = "", detail = "", actions = "", panel
       </div>
       ${panel}
     </main>
+    ${autoRetry ? RETRY_SCRIPT : ""}
   </body>
 </html>`;
 }
+/**
+* One reload, then the page reveals itself. The reload is what the reader would have done by hand,
+* so a fault that clears is never seen; a fault that survives it shows the same page it always did.
+* Session storage is what remembers the attempt, and a preview frame may refuse it — then there is
+* no way to count, and the honest move is to show the error rather than risk reloading forever.
+*/
+const RETRY_SCRIPT = `<noscript><style>main[hidden] { display: flex !important }</style></noscript>
+<script>
+  (() => {
+    const KEY = 'softr:boot-retry'
+    const reveal = () => { document.querySelector('main').hidden = false }
+
+    let store = null
+    try { store = sessionStorage } catch { /* blocked in this frame */ }
+    if (!store) return reveal()
+
+    const now = Date.now()
+    if (now - Number(store.getItem(KEY) ?? 0) < 15000) {
+      store.removeItem(KEY)
+      return reveal()
+    }
+
+    store.setItem(KEY, String(now))
+    // A beat, so the reload lands after the dev server has finished rebuilding rather than during.
+    setTimeout(() => location.reload(), 500)
+  })()
+<\/script>`;
 function escapeHtml(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }

package/dist/package.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "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.42
+  library_version: 0.0.43
 ---
 
 # 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.42
+  library_version: 0.0.43
 ---
 
 **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.42
+  library_version: 0.0.43
 ---
 
 **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.42
+  library_version: 0.0.43
 ---
 
 **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

@@ -1,15 +1,16 @@
 ---
 name: file-uploads
 description: >-
-  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk 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.
+  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk
+  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.42
+  library_version: 0.0.43
 ---
 
 **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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.42
+  library_version: 0.0.43
 ---
 
 **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.
@@ -148,6 +148,10 @@ Match the `integrationType` from the attached integrations section to find the b
 | XERO | `https://api.xero.com` |
 | ZOOM | `https://api.zoom.us` |
 
+## When the type is in the table but nothing is attached
+
+The service is not out of reach, it is not connected yet. Load `connect-a-service` and ask the user for it: the answer carries the `integrationId` this skill needs.
+
 ## When the service is not a Softr integration
 
 If the API the user needs is not in the table above, call it directly from a server function using the native `fetch`. The user supplies their own credentials and the call lives entirely in the server function handler.

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.42
+  library_version: 0.0.43
 ---
 
 **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

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

@@ -6,13 +6,13 @@ description: >-
   four ways to enforce a rule (guard, assert, isAuthorized, check). Covers
   per-reason overrides, the redirect and throw strategies, rendering an access
   error with isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
-  declaration alongside the rules that reject a duplicate, computed or
-  root-level one.
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
+  requires a declaration alongside the rules that reject a duplicate, computed
+  or root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.42
+  library_version: 0.0.43
 ---
 
 **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.42
+  library_version: 0.0.43
 ---
 
 **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.
@@ -28,7 +28,7 @@ import { workflow } from '@softr/sdk/server'
 
 ## Declare the workflow action
 
-Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent.
+Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent. The workflow must have a **Run custom workflow** trigger — no other trigger type can be fired from app code.
 
 ```ts
 const sendWelcomeEmail = defineWorkflow({
@@ -45,7 +45,7 @@ const sendWelcomeEmail = defineWorkflow({
 ```
 
 - `id` is a name you choose, unique across the app.
-- `workflowId` and `triggerId` are opaque UUIDs from the workflow definition in the Softr UI. Pass them as inline string literals — never derive them at runtime.
+- `workflowId` and `triggerId` are opaque UUIDs identifying the workflow and its **Run custom workflow** trigger. `list_workflows` returns both. Pass them as inline string literals — never derive them at runtime.
 - `permissions` declares who may run the trigger. Uses the same format as queries and mutations.
 - `body` is hardcoded data the server resolves before calling the workflow. It is **not** passed by the caller at runtime — the workflow always receives it. Template values draw from the signed-in user and the current time (see table below).
 
@@ -107,6 +107,8 @@ const submit = useServerFn(run)
 
 **Computing `workflowId` or `triggerId` at runtime.** Both are static UUIDs from the workflow definition. Derive them from user input and the call fails at request time.
 
+**Pointing at a workflow with no Run custom workflow trigger.** A workflow that runs on a schedule, a table event or an integration event has no trigger the app can call, and `workflow.trigger` fails at request time. Confirm the workflow has one before writing the `defineWorkflow`. If it does not, say which trigger it has instead — never that the workflow is missing — and name the ones that do have a Run custom workflow trigger.
+
 **Passing nested objects in the runtime payload.** The second argument to `workflow.trigger` only accepts flat values — `string`, `number`, `boolean`, or `null`. Put anything that needs server-side resolution in the action's `body` instead.
 
 **Not awaiting the result.** `workflow.trigger` is async. Fire-and-forget loses the result and swallows any error.