@softr/sdk 0.0.93-alpha.1 → 0.0.93-alpha.2

package/dist/core/email.d.ts

@@ -1,4 +1,5 @@
 import { EmailAction } from "../action.js";
+import { StepError, StepErrorCode } from "./step.js";
 
 //#region src/core/email.d.ts
 /** A file the email carries, by the URL the app holds it under. */
@@ -32,20 +33,14 @@ interface EmailSent {
   /** Null when the mail provider did not report one; the email was still sent. */
   messageId: string | null;
 }
-declare const EMAIL_ERROR_CODES: readonly ["NOT_FOUND", "INVALID_INPUT", "UNAVAILABLE", "TIMEOUT"];
-type EmailErrorCode = (typeof EMAIL_ERROR_CODES)[number];
+type EmailErrorCode = StepErrorCode;
 /**
- * Thrown when Softr did not send the email. `code` says why:
- *
- * - `NOT_FOUND`: no such email action, or the caller is not in its audience.
- * - `INVALID_INPUT`: a missing subject or body, an entry that is not exactly one address, more than 50 recipients, an attachment that is not one of the app's uploads, or an idempotency key over 128 characters.
- * - `UNAVAILABLE`: Softr could not send it, for example with no workflow credits left, past the Softr fallback
- *   address's daily limit or with an unconfirmed sender, or could not be reached.
- * - `TIMEOUT`: no answer in time. It may still have been sent; retry with the same idempotency key.
+ * Thrown when Softr did not send the email; a {@link StepError}, so `code` says why. For an email, `INVALID_INPUT`
+ * is a missing subject or body, an entry that is not exactly one address, more than 50 recipients, an attachment
+ * that is not one of the app's uploads, or an idempotency key over 128 characters; `UNAVAILABLE` includes the Softr
+ * fallback address past its daily limit and an unconfirmed sender.
  */
-declare class EmailError extends Error {
-  readonly status: number;
-  readonly code: EmailErrorCode;
+declare class EmailError extends StepError {
   constructor(status: number, code: EmailErrorCode, message: string);
 }
 /** Sends one email through the action. Never retries by itself. */

package/dist/core/email.js

@@ -3,33 +3,21 @@ import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { sessionConfig } from "../auth/config.js";
 import { readSessionToken } from "../auth/session.js";
+import { StepError, readStepFailure } from "./step.js";
 
 //#region src/core/email.ts
 /** Longer than Softr waits for the send itself, so its own timeout answers first. */
 const TIMEOUT_MS = 12e4;
-const EMAIL_ERROR_CODES = [
-	"NOT_FOUND",
-	"INVALID_INPUT",
-	"UNAVAILABLE",
-	"TIMEOUT"
-];
 /**
-* Thrown when Softr did not send the email. `code` says why:
-*
-* - `NOT_FOUND`: no such email action, or the caller is not in its audience.
-* - `INVALID_INPUT`: a missing subject or body, an entry that is not exactly one address, more than 50 recipients, an attachment that is not one of the app's uploads, or an idempotency key over 128 characters.
-* - `UNAVAILABLE`: Softr could not send it, for example with no workflow credits left, past the Softr fallback
-*   address's daily limit or with an unconfirmed sender, or could not be reached.
-* - `TIMEOUT`: no answer in time. It may still have been sent; retry with the same idempotency key.
+* Thrown when Softr did not send the email; a {@link StepError}, so `code` says why. For an email, `INVALID_INPUT`
+* is a missing subject or body, an entry that is not exactly one address, more than 50 recipients, an attachment
+* that is not one of the app's uploads, or an idempotency key over 128 characters; `UNAVAILABLE` includes the Softr
+* fallback address past its daily limit and an unconfirmed sender.
 */
-var EmailError = class extends Error {
-	status;
-	code;
+var EmailError = class extends StepError {
 	constructor(status, code, message) {
-		super(message);
+		super(status, code, message);
 		this.name = "EmailError";
-		this.status = status;
-		this.code = code;
 	}
 };
 /** Sends one email through the action. Never retries by itself. */
@@ -65,10 +53,7 @@ async function sendEmail(action, init) {
 		assert(typeof sent === "object" && sent !== null && "messageId" in sent && (typeof sent.messageId === "string" || sent.messageId === null), "the send answered without a messageId");
 		return { messageId: sent.messageId };
 	}
-	const failure = await res.json().catch(() => null);
-	const known = typeof failure === "object" && failure !== null ? failure : {};
-	const code = ("code" in known ? EMAIL_ERROR_CODES.find((errorCode) => errorCode === known.code) : void 0) ?? (res.status === 404 ? "NOT_FOUND" : res.status === 400 ? "INVALID_INPUT" : "UNAVAILABLE");
-	const message = "message" in known && typeof known.message === "string" && known.message !== "" ? known.message : `Email "${action.id}" failed with HTTP ${res.status}`;
+	const { code, message } = await readStepFailure(res, `Email "${action.id}" failed with HTTP ${res.status}`);
 	throw new EmailError(res.status, code, message);
 }
 const email = { send: sendEmail };

package/dist/core/step.d.ts

@@ -0,0 +1,20 @@
+//#region src/core/step.d.ts
+/** Why Softr did not run a workflow step the app runs by itself, whatever the step. */
+declare const STEP_ERROR_CODES: readonly ["NOT_FOUND", "INVALID_INPUT", "UNAVAILABLE", "TIMEOUT", "RATE_LIMITED"];
+type StepErrorCode = (typeof STEP_ERROR_CODES)[number];
+/**
+ * Thrown when Softr did not run a step the app runs by itself, such as sending an email. `code` says why:
+ *
+ * - `NOT_FOUND`: no such action, or the caller is not in its audience.
+ * - `INVALID_INPUT`: the call's inputs were refused; the message says which.
+ * - `UNAVAILABLE`: Softr could not run it, for example with no workflow credits left, or could not be reached.
+ * - `TIMEOUT`: no answer in time. It may still have run; retry with the same idempotency key.
+ * - `RATE_LIMITED`: the app ran its actions too often in the last minute or day; try again later.
+ */
+declare class StepError extends Error {
+  readonly status: number;
+  readonly code: StepErrorCode;
+  constructor(status: number, code: StepErrorCode, message: string);
+}
+//#endregion
+export { StepError, StepErrorCode };

package/dist/core/step.js

@@ -0,0 +1,48 @@
+//#region src/core/step.ts
+/** Why Softr did not run a workflow step the app runs by itself, whatever the step. */
+const STEP_ERROR_CODES = [
+	"NOT_FOUND",
+	"INVALID_INPUT",
+	"UNAVAILABLE",
+	"TIMEOUT",
+	"RATE_LIMITED"
+];
+/**
+* Thrown when Softr did not run a step the app runs by itself, such as sending an email. `code` says why:
+*
+* - `NOT_FOUND`: no such action, or the caller is not in its audience.
+* - `INVALID_INPUT`: the call's inputs were refused; the message says which.
+* - `UNAVAILABLE`: Softr could not run it, for example with no workflow credits left, or could not be reached.
+* - `TIMEOUT`: no answer in time. It may still have run; retry with the same idempotency key.
+* - `RATE_LIMITED`: the app ran its actions too often in the last minute or day; try again later.
+*/
+var StepError = class extends Error {
+	status;
+	code;
+	constructor(status, code, message) {
+		super(message);
+		this.name = "StepError";
+		this.status = status;
+		this.code = code;
+	}
+};
+/** The code and message of a step Softr refused, read from its answer; `fallbackMessage` when it sent none. */
+async function readStepFailure(res, fallbackMessage) {
+	const failure = await res.json().catch(() => null);
+	const known = typeof failure === "object" && failure !== null ? failure : {};
+	return {
+		code: ("code" in known ? STEP_ERROR_CODES.find((errorCode) => errorCode === known.code) : void 0) ?? codeOfStatus(res.status),
+		message: "message" in known && typeof known.message === "string" && known.message !== "" ? known.message : fallbackMessage
+	};
+}
+function codeOfStatus(status) {
+	switch (status) {
+		case 400: return "INVALID_INPUT";
+		case 404: return "NOT_FOUND";
+		case 429: return "RATE_LIMITED";
+		default: return "UNAVAILABLE";
+	}
+}
+
+//#endregion
+export { StepError, readStepFailure };

package/dist/package.js

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

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { upload } from "./core/file-upload.js";
 import { AiError, ai } from "./core/ai.js";
+import { StepError, StepErrorCode } from "./core/step.js";
 import { EmailError, EmailErrorCode, email } from "./core/email.js";
 import { auth } from "./auth/server.js";
 import { FieldChoice, RecordOption, RecordOptions } from "./core/options.js";
@@ -7,4 +8,4 @@ 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 { AiError, EmailError, type EmailErrorCode, type FieldChoice, type RecordOption, type RecordOptions, ai, auth, ds, email, integration, upload, workflow };
+export { AiError, EmailError, type EmailErrorCode, type FieldChoice, type RecordOption, type RecordOptions, StepError, type StepErrorCode, ai, auth, ds, email, integration, upload, workflow };

package/dist/server.js

@@ -4,7 +4,8 @@ import { auth } from "./auth/server.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import { AiError, ai } from "./core/ai.js";
+import { StepError } from "./core/step.js";
 import { EmailError, email } from "./core/email.js";
 import "@tanstack/react-start/server-only";
 
-export { AiError, EmailError, ai, auth, ds, email, integration, upload, workflow };
+export { AiError, EmailError, StepError, ai, auth, ds, email, integration, upload, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.93-alpha.1",
+  "version": "0.0.93-alpha.2",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 # Softr SDK core

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **Boundary.** `ai` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineAiAction` and every type come from `@softr/sdk` and can be imported anywhere.

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 # The current user

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **Boundary.** `email` and `EmailError` live on `@softr/sdk/server` and run only inside a `createServerFn` handler — importing them into a component fails the build. `defineEmailAction` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -36,13 +36,14 @@ The action's `permissions` is its audience: everyone in it can send an email thr
 
 Every email comes from the app's email sender, unless the action names one of the workspace's senders with `senderId`.
 
-- Read the app's sender with `application_get` before you promise an address. That tool shows the sign-in emails' default, an `@softr.app` address, when no sender is set. Emails from an email action then come from Softr's address instead: the workspace's name at `<workspaceId>@softr-email.com`, limited to 30 emails a day for the whole workspace, its workflows included. That address is for testing only. Say so in your closing message when no sender is set, and that the app needs its own sender before real users rely on its emails.
-- Changing the app's sender also changes the address its sign-in emails come from. Ask the user before you call `application_configure_email_sender`, and name both effects.
-- Set `senderId` only when the user wants this email from a specific address, such as `billing@`. Pick it from `workspace_list_email_senders`, copied exactly. A sender the mail provider has not confirmed makes every send fail until it is confirmed.
+- Read the app's sender with `application_get` before you say where the emails come from, and name it. Never write "if no sender is set": read it. That tool shows the sign-in emails' default, an `@softr.app` address, when no sender is set. Emails from an email action then come from Softr's address instead: the workspace's name at `<workspaceId>@softr-email.com`, limited to 30 emails a day for the whole workspace, its workflows included. That address is for testing only. Say so in your closing message when no sender is set, and that the app needs its own sender before real users rely on its emails.
+- When the app has no sender of its own, list the workspace's senders with `workspace_list_email_senders` and offer the confirmed ones by name: for this email (`senderId`, nothing else changes) or as the app's sender. Never pick one yourself.
+- Changing the app's sender also changes the address its sign-in emails come from. Ask the user before you call `application_configure_email_sender`, and name both effects. A workspace whose plan has no custom senders is refused; then say that sending from their own address needs the Professional plan.
+- Set `senderId` only when the user wants this email from a specific address, such as `billing@`. Pick it from `workspace_list_email_senders`, copied exactly. A sender the mail provider has not confirmed makes every send fail until it is confirmed. That confirmation is all an email action needs; the domain's DNS records (DKIM, Return-Path) are needed only before Studio lets the app pick the address as its own sender, and they help the emails stay out of spam.
 
 ## What it costs
 
-Every email costs **5 workflow credits per recipient**, from the workspace's monthly workflow credits, which its workflows spend too: 500 on Free (about 100 single-recipient emails), 2,500 on Basic (about 500), 10,000 on Pro (about 2,000), 25,000 on Business (about 5,000). The plan and the closing message say so in plain numbers, for example: "Each submission emails you, at 5 workflow credits per email — about 100 emails a month on the Free plan."
+Every email costs **5 workflow credits per recipient**, from the workspace's monthly workflow credits, which its workflows spend too. You do not know the workspace's plan, so never name one or count how many emails it covers. The plan and the closing message give the cost and where to watch it, for example: "Each submission emails you, at 5 workflow credits per email. Track them in Settings → Billing → Workflow usage, where this app has its own row."
 
 Emails sent from the preview are real and charged, and the actions in the code reach the live app as soon as they are saved. Send at most one test email, and only when the user asks for one. Never send emails in a loop to try something out.
 
@@ -99,13 +100,13 @@ const submit = createServerFn({ method: 'POST' })
 - `subject` and `body`. Required. `body` is plain text or HTML. Escape what visitors typed before you put it into HTML.
 - `to`, `cc`, `bcc`, `replyTo`: each used only where the action does not fix it, and `cc` and `bcc` never when it fixes `to`. Each entry is one address. At most 50 recipients per email.
 - `attachments`: `{ name, url }` each, a file uploaded to this app (the Softr SDK `file-uploads` guidance); any other URL is refused with `INVALID_INPUT`. 10 MB in total.
-- `idempotencyKey`: the same key sends once, however often the call is repeated. Pass one derived from what the email is about, such as the record it announces, so a retried request never sends twice. At most 128 characters. Left out, every call is a new email.
+- `idempotencyKey`: the same key sends once, however often the call is repeated. Pass one derived from what the email is about, such as the record it announces, so a retried request never sends twice. When nothing is saved first, the form makes one key per submission (`crypto.randomUUID()` when the person starts submitting), sends it with the request and reuses it when they retry. At most 128 characters. Left out, every call is a new email, so a retry after `TIMEOUT` or a double click sends twice.
 
 It answers `{ messageId }` once the email is sent. The answer never lists the recipients.
 
 ## Failure modes
 
-**Not handling `EmailError`.** `email.send` throws an `EmailError` with `status`, `code` and `message` when the email was not sent, and never retries by itself. Catch it, keep what the request already saved, and show the person a line they can act on: "Saved, but the email could not be sent." The codes:
+**Not handling `EmailError`.** `email.send` throws an `EmailError`, a `StepError` from `@softr/sdk/server`, with `status`, `code` and `message` when the email was not sent, and never retries by itself. Catch it, keep what the request already saved, and show the person a line they can act on: "Saved, but the email could not be sent." The codes:
 
 | `code` | Meaning |
 | --- | --- |
@@ -113,6 +114,9 @@ It answers `{ messageId }` once the email is sent. The answer never lists the re
 | `INVALID_INPUT` | No subject or body, an entry or placeholder that is not exactly one address, more than 50 recipients, an attachment that is not one of the app's uploads, or an idempotency key over 128 characters |
 | `UNAVAILABLE` | Softr could not send it or could not be reached: no workflow credits left, Softr's address past its 30 emails today, an unconfirmed sender, or an outage |
 | `TIMEOUT` | No answer in time. It may still have been sent: retry only with the same key |
+| `RATE_LIMITED` | The app sent too often in the last minute or day. Tell the person to try again later |
+
+**Letting a mistyped address reach Softr.** An address the person typed (the reply-to of a contact form, a client's email) that is not one address is refused with `INVALID_INPUT`, which reads as a vague failure. Check its format in the validator and tell them which field is wrong.
 
 **Calling from client code.** `email` is server-only. Wrap the send in a `createServerFn` and call that from the form or the button.
 

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **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/formatting/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 # Dates, times and numbers

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **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.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **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/pwa/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 # Installing the app

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **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. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `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.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.93-alpha.1
+  library_version: 0.0.93-alpha.2
 ---
 
 **Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

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