@softr/sdk 0.0.47-alpha.0 → 0.0.47

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.47-alpha.0
+  library_version: 0.0.47
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

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

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

@@ -0,0 +1,90 @@
+---
+name: mcp
+description: >-
+  Open the app to AI assistants over MCP: softrMcpMiddleware({ actions }) from
+  @softr/sdk, registered in src/start.ts ahead of softrAuthMiddleware, turns the
+  actions you list into tools an assistant can call as the signed-in visitor.
+  The list is explicit — an action left out is invisible over MCP. The app's own
+  login must honour a `redirect` search param, or the approval step dead-ends.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.47
+---
+
+**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.
+
+# MCP
+
+An app can answer an AI assistant on its own origin. The assistant signs in as an ordinary app user, and the actions you list become the tools it may call. Not wired by default — a new app serves no MCP endpoint until you add the middleware.
+
+## The URL
+
+The app's own public origin, plus `/_softr/mcp`:
+
+```
+https://myapp.mysoftr.app/_softr/mcp
+```
+
+Custom domain, default subdomain, a staging host — whatever origin the app is published on, the path is the same. That whole string is the MCP URL. The origin on its own is the app's home page, and an assistant pointed at it gets HTML back.
+
+## Setup
+
+```ts
+// src/start.ts
+import { createCsrfMiddleware, createStart } from '@tanstack/react-start'
+import { softrAuthMiddleware, softrMcpMiddleware } from '@softr/sdk'
+import { listCafes, addCafe } from './actions'
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [
+    createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' }),
+    softrMcpMiddleware({ actions: [listCafes, addCafe] }),
+    softrAuthMiddleware(),
+  ],
+}))
+```
+
+Order is part of the contract. `softrMcpMiddleware` goes **before** `softrAuthMiddleware`, and that is the only order it supports.
+
+## Choosing the actions
+
+The list is the whole tool surface. Write it out:
+
+- An action you leave out is invisible to the assistant, even where the app's pages use it freely.
+- An action you list still obeys its own `permissions`. Listing it does not widen who may run it — the assistant runs as whoever signed in, with that user's groups.
+- Two actions with the same `id` throw at startup. So does anything that is not a `defineQuery` or `defineMutation` value.
+
+Reads first. Add a write only when the user asked for one, and name it back to them.
+
+## The login round trip
+
+Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to the app's sign-in page with a `redirect` search param holding where to come back to. That page is `/login` unless you pass `loginPath`:
+
+```ts
+softrMcpMiddleware({ actions: [listCafes], loginPath: '/sign-in' })
+```
+
+**The app's login has to honour that param.** Carry it through every exit that ends a sign-in, the second-factor step included, and send the visitor there instead of the home page. Drop it anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
+
+Validate it before following it. A path on this app and nothing else. Ask the URL parser rather than checking prefixes: resolve the value against a placeholder origin and reject it unless the origin survives. Browsers read `\` as `/` and drop tabs and newlines, so a value that does not start with `//` can still leave the app. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
+
+The blank template does this in `src/routes/_auth/login.tsx`, `src/routes/verify.tsx` and `src/lib/after-auth.ts`. Read those before writing your own.
+
+## Failure modes
+
+**Registering with no actions.** `softrMcpMiddleware()` is valid and serves an endpoint with nothing on it. The assistant connects, lists tools, finds only `whoami`. Pass the actions.
+
+**Registering after `softrAuthMiddleware`.** Not a supported order. Put the MCP middleware first.
+
+**Handing over the app's URL as the MCP URL.** The origin is where the app's pages are. Without `/_softr/mcp` on the end the assistant has nothing to talk to, and the owner is left comparing a URL that looks right against a connection that never works.
+
+**A login that drops `redirect`.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
+
+**Following `redirect` unchecked, or checked by prefix.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. Let the URL parser decide, and fall back to `/`.
+
+## References
+
+- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the read actions you expose
+- [record-mutations/SKILL.md](../record-mutations/SKILL.md): declaring the write actions you expose
+- [auth/SKILL.md](../auth/SKILL.md): the sign-in and second-factor flows the round trip passes through

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

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

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.47-alpha.0
+  library_version: 0.0.47
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

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

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

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.47-alpha.0
+  library_version: 0.0.47
 ---
 
 **Boundary.** `defineVisibility`, 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.47-alpha.0
+  library_version: 0.0.47
 ---
 
 **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.

package/dist/pwa.d.ts

@@ -1,49 +0,0 @@
-import * as react0 from "react";
-import "@tanstack/react-start";
-
-//#region src/pwa.d.ts
-
-/**
- * The links that make the app installable: its manifest and its home screen
- * icon. Render it once, anywhere in the root route; React moves the links into
- * `<head>`.
- *
- * @example
- * function RootComponent() {
- *   return (
- *     <>
- *       <SoftrPwaHead />
- *       <Outlet />
- *     </>
- *   )
- * }
- */
-declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
-type PwaPlatform = "ios" | "android" | "desktop";
-type PwaInstall = {
-  available: false;
-} | {
-  available: true;
-  /** Which steps install the app on this device. */
-  platform: PwaPlatform;
-  /** The name the home screen will show. */
-  name: string;
-  /** The icon the home screen will show. */
-  iconUrl: string;
-};
-/**
- * Whether to offer installing the app, and on which platform. Render an
- * install button only while this says `available`: it is unavailable while
- * loading, when the builder has not turned the PWA on, when Softr has switched
- * it off, and when the app already runs installed.
- *
- * @example
- * function InstallButton() {
- *   const install = usePwaInstall()
- *   if (!install.available) return null
- *   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
- * }
- */
-declare function usePwaInstall(): PwaInstall;
-//#endregion
-export { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall };

package/dist/pwa.js

@@ -1,147 +0,0 @@
-import { logger } from "./logger.js";
-import { fetch } from "./fetch.js";
-import { sessionConfig } from "./auth/config.js";
-import { platformApiUrl } from "./auth/platform.js";
-import { Fragment, createElement, useEffect, useState } from "react";
-import { createMiddleware } from "@tanstack/react-start";
-import { z } from "zod";
-
-//#region src/pwa.ts
-const MANIFEST_PATH = "/manifest.webmanifest";
-const ICON_PATH = "/apple-touch-icon.png";
-const INSTALL_PATH = "/_softr/pwa.json";
-const TTL_MS = 6e4;
-const CACHE_CONTROL = "public, max-age=60";
-const pwaSchema = z.object({
-	manifest: z.record(z.string(), z.unknown()),
-	install: z.object({
-		name: z.string(),
-		iconUrl: z.string()
-	})
-});
-let cached;
-/**
-* The app's PWA, or `null` when it is not installable right now. Never
-* rejects: a failure reads as not installable and is not remembered, so the
-* next request tries again.
-*/
-function readPwa() {
-	const now = Date.now();
-	if (cached !== void 0 && cached.expires > now) return cached.pwa;
-	const entry = {
-		expires: now + TTL_MS,
-		pwa: fetchPwa().catch((error) => {
-			logger.warn("Could not read the PWA settings:", error);
-			if (cached === entry) cached = void 0;
-			return null;
-		})
-	};
-	cached = entry;
-	return entry.pwa;
-}
-async function fetchPwa() {
-	const { applicationId } = sessionConfig();
-	const response = await fetch(`${await platformApiUrl()}/v1/vibe/applications/${applicationId}/pwa`, { headers: { accept: "application/json" } });
-	if (response.status === 404) return null;
-	if (!response.ok) throw new Error(`The platform answered ${response.status}`);
-	return pwaSchema.parse(await response.json());
-}
-/**
-* Serves the app's web app manifest, its home screen icon, and what an install
-* button needs to know, from the app's own origin. Every other request passes
-* through untouched.
-*
-* Answers 404, never an error page, when the app is not installable: a browser
-* silently drops a manifest it cannot parse, so a 500 there would be invisible.
-*/
-function pwaMiddleware() {
-	return createMiddleware({ type: "request" }).server(async ({ next, pathname }) => {
-		if (pathname !== MANIFEST_PATH && pathname !== ICON_PATH && pathname !== INSTALL_PATH) return next();
-		const pwa = await readPwa();
-		if (pwa === null) return new Response(null, { status: 404 });
-		if (pathname === MANIFEST_PATH) return new Response(JSON.stringify(pwa.manifest), { headers: {
-			"content-type": "application/manifest+json",
-			"cache-control": CACHE_CONTROL
-		} });
-		if (pathname === INSTALL_PATH) return Response.json(pwa.install, { headers: { "cache-control": CACHE_CONTROL } });
-		try {
-			const iconResponse = await fetch(pwa.install.iconUrl);
-			if (!iconResponse.ok) return new Response(null, { status: 404 });
-			return new Response(iconResponse.body, { headers: {
-				"content-type": "image/png",
-				"cache-control": CACHE_CONTROL
-			} });
-		} catch (error) {
-			logger.warn("Could not fetch the PWA icon:", error);
-			return new Response(null, { status: 404 });
-		}
-	});
-}
-/**
-* The links that make the app installable: its manifest and its home screen
-* icon. Render it once, anywhere in the root route; React moves the links into
-* `<head>`.
-*
-* @example
-* function RootComponent() {
-*   return (
-*     <>
-*       <SoftrPwaHead />
-*       <Outlet />
-*     </>
-*   )
-* }
-*/
-function SoftrPwaHead() {
-	return createElement(Fragment, null, createElement("link", {
-		rel: "manifest",
-		href: MANIFEST_PATH
-	}), createElement("link", {
-		rel: "apple-touch-icon",
-		href: ICON_PATH
-	}));
-}
-const installSchema = pwaSchema.shape.install;
-/**
-* Whether to offer installing the app, and on which platform. Render an
-* install button only while this says `available`: it is unavailable while
-* loading, when the builder has not turned the PWA on, when Softr has switched
-* it off, and when the app already runs installed.
-*
-* @example
-* function InstallButton() {
-*   const install = usePwaInstall()
-*   if (!install.available) return null
-*   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
-* }
-*/
-function usePwaInstall() {
-	const [install, setInstall] = useState({ available: false });
-	useEffect(() => {
-		if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
-		let cancelled = false;
-		fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
-			if (!response.ok) return;
-			const parsed = installSchema.safeParse(await response.json());
-			if (!parsed.success || cancelled) return;
-			setInstall({
-				available: true,
-				platform: detectPlatform(),
-				...parsed.data
-			});
-		}).catch(() => {});
-		return () => {
-			cancelled = true;
-		};
-	}, []);
-	return install;
-}
-function detectPlatform() {
-	const userAgent = navigator.userAgent;
-	if (/iPhone|iPad|iPod/.test(userAgent) || /Macintosh/.test(userAgent) && navigator.maxTouchPoints > 1) return "ios";
-	if (/Android/.test(userAgent)) return "android";
-	return "desktop";
-}
-
-//#endregion
-export { SoftrPwaHead, pwaMiddleware, usePwaInstall };

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

@@ -1,163 +0,0 @@
----
-name: pwa
-description: >-
-  Let visitors install the app on their home screen: SoftrPwaHead for the
-  manifest and icon links, usePwaInstall to decide whether to show an install
-  button and which platform's steps to show, the PwaInstall and PwaPlatform
-  types, how to check that the app is installable, and the default install
-  button pattern. The manifest and icon are already served; never write them.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.47-alpha.0
----
-
-# Installing the app
-
-The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
-
-> **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
-> **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
-
-## Setup
-
-```ts
-import { SoftrPwaHead, usePwaInstall } from '@softr/sdk'
-import type { PwaInstall, PwaPlatform } from '@softr/sdk'
-```
-
-```ts
-type PwaPlatform = 'ios' | 'android' | 'desktop'
-
-type PwaInstall =
-  | { available: false }
-  | {
-      available: true
-      platform: PwaPlatform   // which steps install the app on this device
-      name: string            // what the home screen will show
-      iconUrl: string         // the icon the home screen will show
-    }
-```
-
-## Is the app installable?
-
-Ask the running app for `/_softr/pwa.json`. `200` means installable, and the body is the name and icon. `404` means the builder has not turned installing on, or has not uploaded an icon. Do not build an install button against a `404`: tell the builder what to turn on instead. A change in Studio can take a few minutes to reach the app.
-
-## Core Patterns
-
-### The links: `<SoftrPwaHead />`
-
-Render it once, in the root route's shell. React moves the links into `<head>`, so it can sit anywhere in the tree.
-
-```tsx
-function RootDocument({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head>
-        <HeadContent />
-      </head>
-      <body>
-        <SoftrPwaHead />
-        {children}
-        <Scripts />
-      </body>
-    </html>
-  )
-}
-```
-
-### Whether to show a button: `usePwaInstall()`
-
-It fetches after mount, so the first render, the server render included, always says `available: false`. It stays unavailable when the app is not installable, when the request fails, and when the app already runs installed from the home screen. Inside the Studio preview it says available, so the builder can see the button; installing itself only works on the published app.
-
-There is no `install()` to call. No browser opens its install dialog for this app on request, so the button opens instructions instead.
-
-### The default button pattern
-
-Start from this unless the builder asked for something else. A round floating button with a download icon, placed where it covers nothing else on screen, that opens a sheet with the steps for the visitor's platform.
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  const [open, setOpen] = useState(false)
-  if (!install.available) return null
-
-  return (
-    <>
-      <button
-        type="button"
-        aria-label={`Install ${install.name}`}
-        onClick={() => setOpen(true)}
-        className="fixed right-4 bottom-[calc(1rem+env(safe-area-inset-bottom))] z-40 size-12 rounded-full"
-      >
-        <DownloadIcon />
-      </button>
-      {open ? <InstallSteps install={install} onClose={() => setOpen(false)} /> : null}
-    </>
-  )
-}
-
-function InstallSteps({
-  install,
-  onClose,
-}: {
-  install: Extract<PwaInstall, { available: true }>
-  onClose: () => void
-}) {
-  return (
-    <dialog open onClose={onClose}>
-      <img src={install.iconUrl} alt="" width={64} height={64} />
-      <h2>Install {install.name}</h2>
-      {install.platform === 'ios' ? (
-        <ol>
-          <li>Tap the Share button in the browser's toolbar.</li>
-          <li>Choose Add to Home Screen.</li>
-          <li>Tap Add.</li>
-        </ol>
-      ) : (
-        <ol>
-          <li>Open the browser's menu.</li>
-          <li>Choose Install app, or Add to Home screen.</li>
-        </ol>
-      )}
-    </dialog>
-  )
-}
-```
-
-The markup is only the shape. Build it from the app's own components and design tokens so it looks like part of the app, and change its look, place or wording freely. What does not change is the `available` check that decides whether it renders at all.
-
-## Common Mistakes
-
-### Showing the button without the check
-
-Wrong:
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  return <button onClick={openSteps}>Install</button>
-}
-```
-
-Correct:
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  if (!install.available) return null
-  return <button onClick={openSteps}>Install {install.name}</button>
-}
-```
-
-A button that shows unconditionally stays up when installing is off, on a device that already has the app installed, and inside the installed app itself.
-
-### Adding a manifest file
-
-Wrong: creating `public/manifest.webmanifest`, `public/apple-touch-icon.png`, or a `head()` link to either.
-
-Correct: `<SoftrPwaHead />` once in the root. The builder changes the name and icon in Studio, and a file in the app would keep the old ones.
-
-## References
-
-- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on