@softr/sdk 0.0.98 → 0.0.99-alpha.1

package/dist/auth/isomorphic.d.ts

@@ -21,7 +21,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  *   requestMiddleware: [softrAuthMiddleware()],
  * }))
  */
-declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: {
     datasources: {};

package/dist/auth/isomorphic.js

@@ -8,6 +8,7 @@ import { makePlatform } from "./platform.js";
 import { settings } from "./methods/settings.js";
 import { bootErrorMiddleware } from "../boot-error.js";
 import { pwaMiddleware } from "../pwa.js";
+import { pushMiddleware } from "../push.js";
 import { faviconMiddleware } from "../favicon.js";
 import { embeddingMiddleware } from "../embedding.js";
 import { appIdentityMiddleware } from "../app-identity.js";
@@ -38,6 +39,7 @@ function softrAuthMiddleware() {
 		appIdentityMiddleware(),
 		bootErrorMiddleware(),
 		pwaMiddleware(),
+		pushMiddleware(),
 		faviconMiddleware()
 	]).server(async ({ next }) => {
 		async function getSession() {

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { FieldShape, SoftrFieldRegistry, fieldShape, formatDuration, formatField
 import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
+import { PushNotifications, PushPrompt, usePushNotifications } from "./push.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PushNotifications, type PushPrompt, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePushNotifications, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -6,6 +6,7 @@ import { definePage, pageHead } from "./route/page.js";
 import { toReturnPath } from "./auth/returnPath.js";
 import { FormattedDate, FormattingScope, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
+import { usePushNotifications } from "./push.js";
 import { AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
 import { fieldShape, formatDuration, formatField, formatValue, registerSoftrFields } from "./fields/format.js";
@@ -14,4 +15,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineAiAction, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePushNotifications, usePwaInstall, useUserTimezone };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start7 from "@tanstack/react-start";
+import * as _tanstack_react_start8 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start7.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start8.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/dist/push.d.ts

@@ -0,0 +1,52 @@
+import "@tanstack/react-start";
+
+//#region src/push.d.ts
+
+/** What the builder wrote in Studio for the prompt. Any of it may be missing. */
+type PushPrompt = {
+  title: string | null;
+  message: string | null;
+  enableButtonLabel: string | null;
+};
+type PushNotifications = /** Loading, signed out, push off for this app or device, or a browser without push. */
+{
+  status: "unavailable";
+}
+/** iPhone and iPad offer push only inside the installed app. */ | {
+  status: "install-first";
+  prompt: PushPrompt;
+} | {
+  status: "ask";
+  prompt: PushPrompt;
+  /** The visitor skipped the prompt recently, within the builder's skip days. Hide the prompt. */
+  dismissed: boolean;
+  /** Asks the browser for permission and subscribes. Call it from a click. */
+  subscribe: () => Promise<void>;
+  /** Hides the prompt for as long as the builder set in Studio. */
+  dismiss: () => void;
+} | {
+  status: "subscribed";
+  unsubscribe: () => Promise<void>;
+}
+/** The visitor blocked notifications in the browser. Only they can undo it, in the browser's settings. */ | {
+  status: "blocked";
+};
+/**
+ * Push notifications for the signed-in visitor. Call it once, in the one
+ * component that shows the prompt, rendered once in the root route's
+ * `RootDocument`, so this browser stays registered and is unsubscribed on
+ * sign-out. Each call keeps state of its own, so a second call does not see a
+ * subscribe made through the first. Show a prompt only while `status` is `ask`
+ * and the prompt is not `dismissed`.
+ *
+ * @example
+ * function EnableNotifications() {
+ *   const push = usePushNotifications()
+ *   if (push.status !== "ask" || push.dismissed) return null
+ *   const turnOn = () => push.subscribe().catch(() => toast.error("Notifications could not be turned on."))
+ *   return <button onClick={turnOn}>{push.prompt.enableButtonLabel ?? "Turn on"}</button>
+ * }
+ */
+declare function usePushNotifications(): PushNotifications;
+//#endregion
+export { PushNotifications, PushPrompt, usePushNotifications };

package/dist/push.js

@@ -0,0 +1,309 @@
+import { logger } from "./logger.js";
+import { softrApiUrl } from "./softr-api.js";
+import { fetch } from "./fetch.js";
+import { sessionConfig } from "./auth/config.js";
+import { readSessionToken } from "./auth/session.js";
+import { detectPlatform } from "./pwa.js";
+import { z } from "zod";
+import { useCallback, useEffect, useState } from "react";
+import { createMiddleware } from "@tanstack/react-start";
+import { rootRouteId, useRouteContext } from "@tanstack/react-router";
+
+//#region src/push.ts
+const WORKER_PATH = "/_softr/sw.js";
+const SETTINGS_PATH = "/_softr/push.json";
+const SUBSCRIPTION_PATH = "/_softr/push";
+const TTL_MS = 6e4;
+const promptSchema = z.object({
+	title: z.string().nullable(),
+	message: z.string().nullable(),
+	enableButtonLabel: z.string().nullable(),
+	skipDays: z.number().nullable()
+});
+const settingsSchema = z.object({
+	vapidPublicKey: z.string(),
+	desktopEnabled: z.boolean(),
+	mobileEnabled: z.boolean(),
+	permissionPrompt: promptSchema.nullable()
+});
+const browserSubscriptionSchema = z.object({
+	endpoint: z.string(),
+	keys: z.object({
+		p256dh: z.string(),
+		auth: z.string()
+	})
+});
+let cachedSettings;
+let cachedWorker;
+/**
+* Reads through a one-minute cache. Never rejects: a failure reads as `null`
+* and is not remembered, so the next request tries again.
+*/
+function readCached(current, store, load) {
+	const now = Date.now();
+	const cached = current();
+	if (cached !== void 0 && cached.expires > now) return cached.value;
+	const entry = {
+		expires: now + TTL_MS,
+		value: load().catch((error) => {
+			logger.warn("Could not read push notifications from Softr:", error);
+			if (current() === entry) store(void 0);
+			return null;
+		})
+	};
+	store(entry);
+	return entry.value;
+}
+function platformPushUrl() {
+	const { applicationId } = sessionConfig();
+	return `${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${applicationId}/push`;
+}
+function readSettings() {
+	return readCached(() => cachedSettings, (entry) => cachedSettings = entry, async () => {
+		const response = await fetch(platformPushUrl(), { headers: { accept: "application/json" } });
+		if (response.status === 404) return null;
+		if (!response.ok) throw new Error(`The platform answered ${response.status}`);
+		return settingsSchema.parse(await response.json());
+	});
+}
+function readWorker() {
+	return readCached(() => cachedWorker, (entry) => cachedWorker = entry, async () => {
+		const response = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/pwa/sw.js`);
+		if (!response.ok) throw new Error(`The platform answered ${response.status}`);
+		return response.text();
+	});
+}
+/**
+* Serves push notifications from the app's own origin: the service worker, the
+* app's push settings, and saving or removing this browser's subscription for
+* the signed-in visitor. Every other request passes through untouched.
+*/
+function pushMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next, pathname, request }) => {
+		if (pathname === WORKER_PATH && request.method === "GET") {
+			const worker = await readWorker();
+			if (worker === null) return new Response(null, {
+				status: 503,
+				headers: { "cache-control": "no-store" }
+			});
+			return new Response(worker, { headers: {
+				"content-type": "text/javascript; charset=utf-8",
+				"cache-control": "no-cache",
+				"service-worker-allowed": "/"
+			} });
+		}
+		if (pathname === SETTINGS_PATH && request.method === "GET") {
+			const settings = await readSettings();
+			if (settings === null) return new Response(null, { status: 404 });
+			return Response.json(settings, { headers: { "cache-control": "no-store" } });
+		}
+		if (pathname === SUBSCRIPTION_PATH && (request.method === "POST" || request.method === "DELETE")) {
+			if (!request.headers.get("content-type")?.startsWith("application/json")) return new Response(null, { status: 415 });
+			const token = readSessionToken();
+			if (token === null) return new Response(null, { status: 401 });
+			const body = z.object({ subscription: browserSubscriptionSchema }).safeParse(await request.json().catch(() => null));
+			if (!body.success) return new Response(null, { status: 400 });
+			const response = request.method === "POST" ? await fetch(platformPushUrl(), {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${token}`
+				},
+				body: JSON.stringify({
+					origin: new URL(request.url).origin,
+					userAgent: request.headers.get("user-agent"),
+					subscription: body.data.subscription
+				})
+			}) : await fetch(`${platformPushUrl()}?${new URLSearchParams({ endpoint: body.data.subscription.endpoint })}`, {
+				method: "DELETE",
+				headers: { authorization: `Bearer ${token}` }
+			});
+			return new Response(null, { status: response.ok ? 204 : response.status });
+		}
+		return next();
+	});
+}
+const DISMISSED_AT_KEY = "softr-push-dismissed-at";
+/**
+* Push notifications for the signed-in visitor. Call it once, in the one
+* component that shows the prompt, rendered once in the root route's
+* `RootDocument`, so this browser stays registered and is unsubscribed on
+* sign-out. Each call keeps state of its own, so a second call does not see a
+* subscribe made through the first. Show a prompt only while `status` is `ask`
+* and the prompt is not `dismissed`.
+*
+* @example
+* function EnableNotifications() {
+*   const push = usePushNotifications()
+*   if (push.status !== "ask" || push.dismissed) return null
+*   const turnOn = () => push.subscribe().catch(() => toast.error("Notifications could not be turned on."))
+*   return <button onClick={turnOn}>{push.prompt.enableButtonLabel ?? "Turn on"}</button>
+* }
+*/
+function usePushNotifications() {
+	const signedIn = useRouteContext({
+		from: rootRouteId,
+		select: (context) => context.user !== null
+	});
+	const [settings, setSettings] = useState(null);
+	const [registration, setRegistration] = useState(null);
+	const [subscribed, setSubscribed] = useState(false);
+	const [permission, setPermission] = useState("default");
+	const [dismissedAt, setDismissedAt] = useState(null);
+	useEffect(() => {
+		if (process.env.NODE_ENV !== "production" || !("serviceWorker" in navigator)) return;
+		if (!signedIn) {
+			navigator.serviceWorker.getRegistration("/").then((existing) => existing?.pushManager.getSubscription()).then((subscription) => subscription?.unsubscribe()).catch(() => {});
+			try {
+				localStorage.removeItem(DISMISSED_AT_KEY);
+			} catch {}
+			setDismissedAt(null);
+			setSettings(null);
+			setSubscribed(false);
+			return;
+		}
+		let cancelled = false;
+		(async () => {
+			const response = await globalThis.fetch(SETTINGS_PATH, { headers: { accept: "application/json" } });
+			if (!response.ok) return;
+			const parsed = settingsSchema.safeParse(await response.json());
+			if (!parsed.success || cancelled) return;
+			setDismissedAt(readDismissedAt());
+			setSettings(parsed.data);
+			if (!("PushManager" in window) || !("Notification" in window)) return;
+			setPermission(Notification.permission);
+			const registered = await navigator.serviceWorker.register(WORKER_PATH, { scope: "/" });
+			if (cancelled) return;
+			setRegistration(registered);
+			const existing = await registered.pushManager.getSubscription();
+			if (existing !== null && Notification.permission === "granted") setSubscribed(await sendSubscription("POST", existing));
+		})().catch((error) => logger.warn("Could not set up push notifications:", error));
+		return () => {
+			cancelled = true;
+		};
+	}, [signedIn]);
+	useEffect(() => {
+		if (registration === null) return;
+		return listenToWorker();
+	}, [registration]);
+	const subscribe = useCallback(async () => {
+		if (registration === null || settings === null) return;
+		const granted = await Notification.requestPermission();
+		setPermission(granted);
+		if (granted !== "granted") return;
+		const subscription = await registration.pushManager.subscribe({
+			userVisibleOnly: true,
+			applicationServerKey: decodeBase64Url(settings.vapidPublicKey)
+		});
+		if (!await sendSubscription("POST", subscription)) {
+			await subscription.unsubscribe();
+			throw new Error("Could not turn on push notifications");
+		}
+		setSubscribed(true);
+	}, [registration, settings]);
+	const unsubscribe = useCallback(async () => {
+		const subscription = await registration?.pushManager.getSubscription();
+		if (!subscription) return;
+		await sendSubscription("DELETE", subscription);
+		await subscription.unsubscribe();
+		setSubscribed(false);
+	}, [registration]);
+	const dismiss = useCallback(() => {
+		const now = Date.now();
+		try {
+			localStorage.setItem(DISMISSED_AT_KEY, String(now));
+		} catch {}
+		setDismissedAt(now);
+	}, []);
+	if (settings === null) return { status: "unavailable" };
+	const platform = detectPlatform();
+	if (platform !== "desktop" ? !settings.mobileEnabled : !settings.desktopEnabled) return { status: "unavailable" };
+	const prompt = {
+		title: settings.permissionPrompt?.title ?? null,
+		message: settings.permissionPrompt?.message ?? null,
+		enableButtonLabel: settings.permissionPrompt?.enableButtonLabel ?? null
+	};
+	if (platform === "ios" && !isStandalone()) return {
+		status: "install-first",
+		prompt
+	};
+	if (registration === null) return { status: "unavailable" };
+	if (subscribed) return {
+		status: "subscribed",
+		unsubscribe
+	};
+	if (permission === "denied") return { status: "blocked" };
+	return {
+		status: "ask",
+		prompt,
+		dismissed: isDismissed(dismissedAt, settings.permissionPrompt?.skipDays ?? null),
+		subscribe,
+		dismiss
+	};
+}
+async function sendSubscription(method, subscription) {
+	return (await globalThis.fetch(SUBSCRIPTION_PATH, {
+		method,
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ subscription: subscription.toJSON() })
+	})).ok;
+}
+/** A missing skip-days setting means a skipped prompt never comes back on its own. */
+function isDismissed(dismissedAt, skipDays) {
+	if (dismissedAt === null) return false;
+	if (skipDays === null) return true;
+	return Date.now() - dismissedAt < skipDays * 24 * 60 * 60 * 1e3;
+}
+function readDismissedAt() {
+	try {
+		const stored = Number(localStorage.getItem(DISMISSED_AT_KEY));
+		return Number.isFinite(stored) && stored > 0 ? stored : null;
+	} catch {
+		return null;
+	}
+}
+function isStandalone() {
+	return window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true;
+}
+/**
+* Answers the service worker, which routes a notification click to the
+* installed app when it is open, and keeps the app icon's badge right.
+*/
+function listenToWorker() {
+	const worker = navigator.serviceWorker;
+	const standalone = isStandalone();
+	if (standalone) worker.controller?.postMessage({ type: "pwa-standalone-opened" });
+	const onMessage = (event) => {
+		if (event.data === "is-this-standalone") {
+			event.ports[0]?.postMessage(standalone ? "yes" : "no");
+			return;
+		}
+		if (event.data?.type === "softr-pwa-redirect" && typeof event.data.url === "string") {
+			const target = new URL(event.data.url, window.location.href);
+			if (target.origin === window.location.origin) window.location.assign(target.href);
+		}
+	};
+	const onVisible = () => {
+		if (document.visibilityState === "visible") worker.controller?.postMessage("reset-badge-count");
+	};
+	const onInstallOffered = () => worker.controller?.postMessage({ type: "pwa-uninstalled" });
+	worker.addEventListener("message", onMessage);
+	document.addEventListener("visibilitychange", onVisible);
+	window.addEventListener("beforeinstallprompt", onInstallOffered);
+	onVisible();
+	return () => {
+		worker.removeEventListener("message", onMessage);
+		document.removeEventListener("visibilitychange", onVisible);
+		window.removeEventListener("beforeinstallprompt", onInstallOffered);
+	};
+}
+function decodeBase64Url(value) {
+	const base64 = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+
+//#endregion
+export { pushMiddleware, usePushNotifications };

package/dist/pwa.js

@@ -149,4 +149,4 @@ function detectPlatform() {
 }
 
 //#endregion
-export { SoftrPwaHead, pwaMiddleware, usePwaInstall };
+export { SoftrPwaHead, detectPlatform, pwaMiddleware, usePwaInstall };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -32,7 +32,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `usePushNotifications`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration`, `ai` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -53,6 +53,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Call a connected third-party API (Slack, Stripe, Gmail, …), or an AI model on the user's own provider account | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
+| Let visitors turn on push notifications | [push-notifications/SKILL.md](./push-notifications/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
 
 ## Quick Decision Tree
@@ -97,6 +98,9 @@ Opening the app to an AI assistant over MCP?
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 
+Letting visitors turn on push notifications, or "notify users when …"?
+  load softr-sdk/push-notifications
+
 Showing a date, a time or a number on a page?
   load softr-sdk/formatting
 

package/skills/softr-sdk/push-notifications/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: push-notifications
+description: >-
+  Let signed-in visitors turn on push notifications: usePushNotifications for
+  the prompt, its states and the Studio texts, the PushNotifications and
+  PushPrompt types, and how to check that push is on for the app. Notifications
+  are sent by Softr Workflows, never by app code; the service worker is already
+  served, never write one.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.97
+---
+
+# Push notifications
+
+The builder turns push on in Studio, under Users → Notifications, for desktop, mobile or both, and writes the prompt's texts there. Notifications are sent by a Softr Workflow's "Send notification" action, which the builder sets up in Studio. What the app adds is one thing: a prompt that lets the signed-in visitor turn notifications on in this browser.
+
+> **CRITICAL**: Never write a service worker, a `public/sw.js`, or any `navigator.serviceWorker`, `PushManager` or `Notification` code of your own. The app already serves its service worker, and `usePushNotifications()` registers it, subscribes and unsubscribes.
+>
+> **CRITICAL**: Never send a push from app code. Sending is a Softr Workflow's "Send notification" action. When the builder asks for "notify X when Y", point them to that workflow; when Y is something the app does, the app triggers the workflow (load the Softr SDK `workflows` guidance). The app itself adds only the prompt.
+
+## Setup
+
+```ts
+import { usePushNotifications } from '@softr/sdk'
+import type { PushNotifications, PushPrompt } from '@softr/sdk'
+```
+
+```ts
+type PushPrompt = {
+  title: string | null              // what the builder wrote in Studio; any of these may be missing
+  message: string | null
+  enableButtonLabel: string | null
+}
+
+type PushNotifications =
+  | { status: 'unavailable' }       // loading, signed out, push off, this device type off, or no browser support
+  | { status: 'install-first'; prompt: PushPrompt }   // iPhone and iPad: push works only in the installed app
+  | {
+      status: 'ask'
+      prompt: PushPrompt
+      dismissed: boolean            // skipped recently, within the builder's skip days; hide the prompt
+      subscribe: () => Promise<void>  // call from a click
+      dismiss: () => void
+    }
+  | { status: 'subscribed'; unsubscribe: () => Promise<void> }
+  | { status: 'blocked' }           // blocked in the browser; only the visitor can undo it there
+```
+
+## Is push on for the app?
+
+Ask the running app for `/_softr/push.json`: `200` means push is on, `404` means it is off in Studio or the plan does not include it. Do not build a prompt against a `404`: push has to be turned on first. A change in Studio can take up to two minutes to reach the app.
+
+Push works only on the published app. Inside the Studio preview the hook always says `unavailable`, so the prompt never shows there. That is expected, not a bug to fix.
+
+## Core Patterns
+
+### The prompt
+
+Render it once, in `RootDocument` in `src/routes/__root.tsx`, so it shows on every page and the browser stays registered for the visitor. Use the prompt component the template ships when it has one. It already handles each status.
+
+Call `usePushNotifications()` in that one component only. Each call keeps state of its own: a second call, in a header or on a settings page, does not see a subscribe made through the first, so the prompt would stay on screen after the visitor said yes.
+
+`subscribe()` rejects when the browser or Softr refuses. Catch it and tell the visitor, so the button never fails in silence.
+
+```tsx
+function EnableNotifications() {
+  const push = usePushNotifications()
+  if (push.status !== 'ask' || push.dismissed) return null
+  return (
+    <div role="dialog">
+      <p>{push.prompt.title ?? 'Turn on notifications'}</p>
+      <p>{push.prompt.message ?? 'Get notified about updates.'}</p>
+      <button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
+        {push.prompt.enableButtonLabel ?? 'Turn on'}
+      </button>
+      <button onClick={push.dismiss}>Not now</button>
+    </div>
+  )
+}
+```
+
+Fall back to your own wording only where the builder left a text empty. On `install-first`, point the visitor to installing the app (load the Softr SDK `pwa` guidance); do not ask for permission.
+
+### Signing out
+
+Nothing to add. The browser is unsubscribed when the visitor signs out, so the next person on the device gets nothing meant for them.
+
+## Common Mistakes
+
+### CRITICAL Asking for permission on page load
+
+Wrong:
+
+```tsx
+useEffect(() => { push.status === 'ask' && push.subscribe() }, [push.status])
+```
+
+Correct:
+
+```tsx
+<button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
+  {push.prompt.enableButtonLabel ?? 'Turn on'}
+</button>
+```
+
+Browsers ignore or block a permission request that no click started, and a visitor who blocks it can only undo that in the browser's settings.
+
+Source: packages/sdk/src/push.ts
+
+### HIGH Showing the prompt whatever the status
+
+Wrong:
+
+```tsx
+const push = usePushNotifications()
+return <button onClick={() => push.subscribe()}>Turn on notifications</button>
+```
+
+Correct:
+
+```tsx
+const push = usePushNotifications()
+if (push.status !== 'ask' || push.dismissed) return null
+return (
+  <button onClick={() => push.subscribe().catch(() => toast.error('Notifications could not be turned on.'))}>
+    {push.prompt.enableButtonLabel ?? 'Turn on'}
+  </button>
+)
+```
+
+The hook says `unavailable` when push is off in Studio, for this device type, or for a signed-out visitor. A prompt that skips the check shows in all of those, and on iPhone it asks for something the browser cannot give.
+
+Source: packages/sdk/src/push.ts
+
+## References
+
+- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on
+- [pwa/SKILL.md](../pwa/SKILL.md): installing the app, which iPhone and iPad need before push