@protobase/server 0.45.18 → 0.45.20

package/dist/notifications/device-store.d.ts

@@ -7,10 +7,12 @@ import { Device, NewDevice } from "./device.js";
  */
 export type DeviceStore = {
   /**
-   * Registers the device for `userId`, or refreshes it when the user has it already. A token another user holds moves
-   * to `userId` as a new device: a new id, its fields as given, created and last seen now.
+   * Registers the device for `userId`, or refreshes it when the user has it already, its session included. An APNs or
+   * FCM token another user holds moves to `userId` as a new device: a new id, its fields as given, created and last
+   * seen now. A browser's endpoint another user holds stays theirs, unchanged, and the answer is `undefined`: a browser
+   * can always subscribe afresh, so an endpoint never changes hands.
    */
-  register: (userId: string, device: NewDevice) => Promise<Device>;
+  register: (userId: string, device: NewDevice) => Promise<Device | undefined>;
   /** Removes the device with this id when it is `userId`'s; another user's is left as it is. */
   remove: (userId: string, id: string) => Promise<void>;
   /** The user's devices. */

package/dist/notifications/device.d.ts

@@ -9,7 +9,8 @@ export type ApnsEnvironment = (typeof apnsEnvironments)[number];
  * A device as a signed-in user registers it. `token` is unique among all devices: the APNs or FCM token, or for `web`
  * the subscription's endpoint URL. A field that does not apply to the kind is `null`: the Web Push keys (`p256dh`,
  * `auth`) for web only, the APNs `environment` for apns only, the `appId` (the iOS bundle id or Android package) for
- * apns and fcm.
+ * apns and fcm. `sessionId` is the id of the sign-in session it was registered in, never its token, or `null` when the
+ * app's authenticator names none: with Protobase's auth, the device gets push only while that session stands.
  */
 export type NewDevice = {
   kind: DeviceKind;
@@ -19,6 +20,7 @@ export type NewDevice = {
   environment: ApnsEnvironment | null;
   appId: string | null;
   userAgent: string | null;
+  sessionId: string | null;
 };
 /** A stored device: whose it is, its own id, when it was registered by that user and when last seen. */
 export type Device = NewDevice & {

package/dist/notifications/guarded-sender.js

@@ -3,8 +3,17 @@ import { PushMessageError, pushMessage } from "./message.js";
 const results = /* @__PURE__ */ new Set([
 	"ok",
 	"gone",
-	"retry"
+	"retry",
+	"refused"
 ]);
+/** What a guarded sender throws for what its sender threw: it names the sender's index alone. */
+var PushSenderError = class extends Error {
+	index;
+	constructor(index) {
+		super(`notifications sender ${index} failed`);
+		this.index = index;
+	}
+};
 const deepFrozen = (value) => {
 	if (typeof value !== "object" || value === null) return value;
 	for (const item of Object.values(value)) deepFrozen(item);
@@ -34,7 +43,7 @@ const answersFor = (batch, given) => {
 /**
 * `sender` as the code that sends calls it, whether built in or the app's own: the message is checked as `pushMessage`
 * checks it, and refused before the sender sees it; the sender gets a frozen copy of it and of the devices of its kinds
-* only, and answers each of those once, as above. A sender that throws throws an error of its own naming its index,
+* only, and answers each of those once, as above. A sender that throws throws a `PushSenderError` naming its index,
 * never the sender's, which may carry an endpoint or a key, but for a `PushMessageError`, which names a field only.
 */
 const guardedSender = (sender, index) => {
@@ -47,7 +56,7 @@ const guardedSender = (sender, index) => {
 			answers = await sender.send(message, batch);
 		} catch (error) {
 			if (error instanceof PushMessageError) throw error;
-			throw new Error(`notifications sender ${index} failed`);
+			throw new PushSenderError(index);
 		}
 		return answersFor(batch, answers);
 	};
@@ -58,4 +67,4 @@ const guardedSender = (sender, index) => {
 	};
 };
 //#endregion
-export { guardedSender };
+export { PushSenderError, guardedSender };

package/dist/notifications/history.js

@@ -12,6 +12,7 @@ const historyLimits = {
 const noControls = /^[^\u0000-\u001f\u007f]*$/;
 const noControlsButLines = /^[^\u0000-\u0008\u000b-\u001f\u007f]*$/;
 const text = (value, max, pattern) => typeof value === "string" && value.length <= max && pattern.test(value);
+/** The first field of the notification that is not within its format, or `undefined`. */
 const notificationProblem = (notification) => {
 	if (typeof notification !== "object" || notification === null) return "notification";
 	if (!text(notification.title, historyLimits.title, noControls) || notification.title === "") return "title";
@@ -38,4 +39,4 @@ const checkedNotification = (notification) => {
 	};
 };
 //#endregion
-export { checkedNotification, historyIdPattern, historyLimits };
+export { checkedNotification, historyIdPattern, historyLimits, notificationProblem };

package/dist/notifications/options.d.ts

@@ -3,7 +3,7 @@ import { HistoryStore } from "./history-store.js";
 import { PushSender } from "./sender.js";
 //#region src/notifications/options.d.ts
 /** The columns of the devices table, by the name Protobase gives them. */
-export declare const deviceColumns: readonly ["id", "user_id", "kind", "token", "p256dh", "auth", "environment", "app_id", "user_agent", "created_at", "last_seen_at"];
+export declare const deviceColumns: readonly ["id", "user_id", "kind", "token", "p256dh", "auth", "environment", "app_id", "user_agent", "session_id", "created_at", "last_seen_at"];
 export type DeviceColumn = (typeof deviceColumns)[number];
 /** The columns of the history table, by the name Protobase gives them. */
 export declare const historyColumns: readonly ["id", "user_id", "title", "body", "url", "data", "created_at", "read_at"];

package/dist/notifications/options.js

@@ -13,6 +13,7 @@ const deviceColumns = [
 	"environment",
 	"app_id",
 	"user_agent",
+	"session_id",
 	"created_at",
 	"last_seen_at"
 ];

package/dist/notifications/paths.d.ts

@@ -1,8 +1,5 @@
+import { deviceIdParam, devicesPath } from "@protobase/schema/internal";
 //#region src/notifications/paths.d.ts
-/** The name of the device id in a device's path. */
-export declare const deviceIdParam = "id";
-/** The path of the caller's devices under the API's system path (`/api`), or of one of them by its id. */
-export declare const devicesPath: (systemPath: string, id?: string) => string;
 /** The name of the entry id in the path that marks one entry of the history read. */
 export declare const historyIdParam = "id";
 /**
@@ -13,4 +10,5 @@ export declare const historyIdParam = "id";
 export declare const historyPath: (systemPath: string, part?: "unread" | "read" | {
   read: string;
 }) => string;
-//#endregion
+//#endregion
+export { deviceIdParam, devicesPath };

package/dist/notifications/paths.js

@@ -1,9 +1,6 @@
 import { historyIdPattern } from "./history.js";
+import { deviceIdParam, devicesPath } from "@protobase/schema/internal";
 //#region src/notifications/paths.ts
-/** The name of the device id in a device's path. */
-const deviceIdParam = "id";
-/** The path of the caller's devices under the API's system path (`/api`), or of one of them by its id. */
-const devicesPath = (systemPath, id) => `${systemPath}/notifications/devices${id === void 0 ? "" : `/${encodeURIComponent(id)}`}`;
 /** The name of the entry id in the path that marks one entry of the history read. */
 const historyIdParam = "id";
 /**

package/dist/notifications/postgres-store.js

@@ -25,6 +25,7 @@ const deviceOf = (row) => ({
 	environment: row.environment,
 	appId: row.app_id,
 	userAgent: row.user_agent,
+	sessionId: row.session_id,
 	createdAt: new Date(row.created_at),
 	lastSeenAt: new Date(row.last_seen_at)
 });
@@ -54,6 +55,7 @@ const postgresDeviceStore = (db, options = {}) => {
 				environment: device.environment,
 				app_id: device.appId,
 				user_agent: device.userAgent,
+				session_id: device.sessionId,
 				created_at: now,
 				last_seen_at: now
 			};
@@ -69,6 +71,7 @@ const postgresDeviceStore = (db, options = {}) => {
 				"environment",
 				"app_id",
 				"user_agent",
+				"session_id",
 				"last_seen_at"
 			].map((name) => sql`${column(name)} = excluded.${column(name)}`);
 			const [stored] = await rows(sql`insert into ${devices} as d (${names}) values (${given})
@@ -77,6 +80,7 @@ const postgresDeviceStore = (db, options = {}) => {
 				keep("created_at"),
 				...replaced
 			])}
+        where ${sameUser} or (${sql.ref(`d.${columns.kind}`)} <> 'web' and excluded.${column("kind")} <> 'web')
         returning ${selected}`);
 			return stored;
 		},

package/dist/notifications/push-job-name.js

@@ -0,0 +1,5 @@
+//#region src/notifications/push-job-name.ts
+/** The job that delivers what `sendNotification` sends. */
+const pushJobName = "notifications.send";
+//#endregion
+export { pushJobName };

package/dist/notifications/push-job.js

@@ -0,0 +1,52 @@
+import { defineJob } from "../jobs/define-job.js";
+import { deviceStore } from "./device-store-of.js";
+import { HistoryStoreError } from "./postgres-history-store.js";
+import { historyStore } from "./history-store-of.js";
+import { holdJob, replaceJobData, saveJobProgress } from "../jobs/job-progress.js";
+import { deliver } from "./deliver.js";
+import { noProgress, pushPayload } from "./push-payload.js";
+import { pushJobName } from "./push-job-name.js";
+//#region src/notifications/push-job.ts
+const userGone = "23503";
+/**
+* Keeps the entry and the progress that marks it kept in one transaction, with the default store, so no try records
+* it twice. An app's own store records outside it. When the user was deleted since the send, the entry is not kept
+* and the user is marked all the same, after the transaction the failed insert ended.
+*/
+const recordOnce = (db, options, job) => async (userId, entry, progress) => {
+	try {
+		await db.transaction().execute(async (trx) => {
+			await historyStore(trx, options).record(userId, entry);
+			await saveJobProgress(trx, job, progress);
+		});
+	} catch (error) {
+		if (!(error instanceof HistoryStoreError && error.sqlState === userGone)) throw error;
+		await saveJobProgress(db, job, progress);
+	}
+};
+/**
+* The job that delivers what `sendNotification` sends, through `senders` (guarded, see `notificationSenders`) and the
+* stores `options` configure; with `liveSessions`, as with Protobase's auth, only to devices whose session stands. A
+* try resumes where the last one stopped (see `deliver`); once delivered, the job keeps no message. A few tries only: a
+* device that keeps asking for a retry is given up on the second time.
+*/
+const pushJob = (options, senders, liveSessions) => defineJob({
+	name: pushJobName,
+	payload: pushPayload,
+	maxAttempts: 5,
+	retryDelay: "1 minute",
+	run: async (payload, { db, job }) => {
+		if ("complete" in payload) return;
+		await deliver(payload, payload.progress ?? noProgress(), {
+			devices: deviceStore(db, options),
+			senders,
+			record: recordOnce(db, options, job),
+			save: (progress) => saveJobProgress(db, job, progress),
+			hold: () => holdJob(db, job),
+			complete: () => replaceJobData(db, job, { complete: true }),
+			...liveSessions && { liveSessions }
+		});
+	}
+});
+//#endregion
+export { pushJob };

package/dist/notifications/push-payload.js

@@ -0,0 +1,60 @@
+import { NotificationSendError, checkedSend, isPlainRecord, maxRecipients } from "./send-input.js";
+//#region src/notifications/push-payload.ts
+const noProgress = () => ({
+	recorded: [],
+	done: [],
+	retried: []
+});
+const maxProgressIds = maxRecipients * 64;
+const progressOf = (value) => {
+	if (!isPlainRecord(value)) return void 0;
+	const keys = Object.keys(value);
+	if (keys.length !== 3 || ![
+		"recorded",
+		"done",
+		"retried"
+	].every((key) => keys.includes(key))) return void 0;
+	if (![
+		value.recorded,
+		value.done,
+		value.retried
+	].every((list) => Array.isArray(list) && list.length <= maxProgressIds && list.every((id) => typeof id === "string"))) return void 0;
+	return {
+		recorded: [...value.recorded],
+		done: [...value.done],
+		retried: [...value.retried]
+	};
+};
+const invalid = (message) => ({ issues: [{ message }] });
+/**
+* The payload as the send job checks it when enqueued and before each try: the send checked again as `checkedSend`
+* checks it, so a job queued around `sendNotification` is refused the same way and runs nothing.
+*/
+const validate = (value) => {
+	if (!isPlainRecord(value)) return invalid("The notification send is not an object");
+	if (value.complete === true && Object.keys(value).length === 1) return { value: { complete: true } };
+	if (Object.keys(value).some((key) => ![
+		"to",
+		"message",
+		"progress"
+	].includes(key))) return invalid("The notification send has a field it does not take");
+	const progress = value.progress === void 0 ? void 0 : progressOf(value.progress);
+	if (value.progress !== void 0 && progress === void 0) return invalid("The notification send has an invalid progress");
+	let send;
+	try {
+		send = checkedSend(value.to, value.message);
+	} catch (error) {
+		if (!(error instanceof NotificationSendError)) throw error;
+		return invalid(error.message);
+	}
+	return { value: {
+		...send,
+		...progress && { progress }
+	} };
+};
+const pushPayload = { "~standard": {
+	version: 1,
+	validate
+} };
+//#endregion
+export { noProgress, pushPayload };

package/dist/notifications/routes.js

@@ -1,14 +1,16 @@
 import { HttpProblem } from "../problem.js";
-import { ownSignInUser } from "./caller.js";
-import "./paths.js";
+import { ownSignInDevice } from "./caller.js";
+import { deviceIdParam } from "./paths.js";
 import { deviceInput, maxDeviceBodyBytes } from "./device-input.js";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 //#region src/notifications/routes.ts
 /** The most devices one user keeps: registering one more drops their least recently seen. */
 const maxDevicesPerUser = 20;
-const ownSignIn = async (c, next) => {
-	c.set("deviceUser", ownSignInUser(c.get("session")));
+const ownSignIn = (sessionRequired) => async (c, next) => {
+	const { userId, sessionId } = ownSignInDevice(c.get("session"), sessionRequired);
+	c.set("deviceUser", userId);
+	c.set("deviceSession", sessionId);
 	await next();
 };
 const jsonOnly = async (c, next) => {
@@ -33,21 +35,31 @@ const dropOldest = async (store, userId, kept) => {
 };
 /**
 * The caller's own devices, mounted at `devicesPath` behind the API's authenticator: `POST` registers or refreshes the
-* device the request comes from, `DELETE` with its id removes it. Tokens travel in the body only, never the URL.
+* device the request comes from, in the caller's session, `DELETE` with its id removes it. Tokens travel in the body
+* only, never the URL. A register is a 409 that stores nothing when the body names a user other than the caller
+* (`other-user`), or when another user holds the browser's endpoint (`device-held`), which a browser answers by
+* subscribing afresh. With `sessionRequired`, a caller whose session has no id is refused.
 */
-const deviceRoutes = (store) => {
+const deviceRoutes = (store, { sessionRequired = false } = {}) => {
 	const app = new Hono();
-	app.post("/", ownSignIn, jsonOnly, limited, async (c) => {
+	const caller = ownSignIn(sessionRequired);
+	app.post("/", caller, jsonOnly, limited, async (c) => {
 		const userId = c.get("deviceUser");
-		const device = deviceInput(await c.req.json());
+		const given = deviceInput(await c.req.json());
+		if (given.userId !== void 0 && given.userId !== userId) throw new HttpProblem(409, "other-user", "Conflict", "The device is registered for the user signed in");
+		const device = {
+			...given.device,
+			sessionId: c.get("deviceSession")
+		};
 		const stored = await store.register(userId, device);
+		if (!stored) throw new HttpProblem(409, "device-held", "Conflict", "Another user holds this subscription: subscribe again");
 		if (stored.userId !== userId || stored.token !== device.token) throw new Error("The device store answered register with another device");
 		await dropOldest(store, userId, stored);
 		return c.json(answer(stored));
 	});
-	app.delete(`/:id`, ownSignIn, async (c) => {
+	app.delete(`/:${deviceIdParam}`, caller, async (c) => {
 		const userId = c.get("deviceUser");
-		const id = c.req.param("id");
+		const id = c.req.param(deviceIdParam);
 		if ((await store.listForUser(userId)).some((device) => device.id === id)) await store.remove(userId, id);
 		return c.body(null, 204);
 	});

package/dist/notifications/schema-sql.js

@@ -2,6 +2,11 @@ import { quoteIdent } from "../changes/capture-sql.js";
 //#region src/notifications/schema-sql.ts
 /** A table by its schema, when one is named, and its name, quoted. */
 const qualified = ({ schema, table }) => schema ? `${quoteIdent(schema)}.${quoteIdent(table)}` : quoteIdent(table);
+/** The session column, added to a devices table written before devices kept the session they were registered in. */
+const deviceSessionColumnSql = ({ schema, table, columns }) => `alter table ${qualified({
+	schema,
+	table
+})} add column ${quoteIdent(columns.session_id)} text`;
 /**
 * The devices table: the token unique, so registering one moves it; with auth, its user column points at auth's users
 * table and goes with the user. A field that does not apply to the kind must be NULL, and nothing has a default.
@@ -24,6 +29,7 @@ const devicesTableSql = ({ schema, table, columns }, user) => {
   ${c.environment} text check (${c.environment} in ('sandbox', 'production')),
   ${c.app_id} text,
   ${c.user_agent} text,
+  ${c.session_id} text,
   ${c.created_at} timestamptz not null,
   ${c.last_seen_at} timestamptz not null,
   check (
@@ -37,4 +43,4 @@ const devicesTableSql = ({ schema, table, columns }, user) => {
 	];
 };
 //#endregion
-export { devicesTableSql, qualified };
+export { deviceSessionColumnSql, devicesTableSql, qualified };

package/dist/notifications/schema.d.ts

@@ -5,7 +5,8 @@ import { Db } from "@protobase/query";
 /**
  * The SQL that adds the tables `notifications()` keeps devices and each user's history in, under the names its options
  * give; with `auth`, their user columns point at auth's users table. Each table is left out when it exists or a store
- * of the app's own replaces it; `undefined` when none is left.
+ * of the app's own replaces it, and an existing devices table without its session column gets that column;
+ * `undefined` when nothing is left.
  */
 export declare const notificationsMigration: (db: Db, options?: NotificationsOptions, auth?: AdminAuth) => Promise<string | undefined>;
 /** Refuses to start while the devices or the history table lacks what `notifications()` needs, naming it. */

package/dist/notifications/schema.js

@@ -1,7 +1,7 @@
 import { migrationCommand } from "../changes/capture-schema.js";
 import { historyNames, notificationsNames } from "./options.js";
 import { storeSchema } from "../better-auth/auth-tables.js";
-import { devicesTableSql, qualified } from "./schema-sql.js";
+import { deviceSessionColumnSql, devicesTableSql, qualified } from "./schema-sql.js";
 import { historyTableSql } from "./history-sql.js";
 import { sql } from "kysely";
 //#region src/notifications/schema.ts
@@ -17,29 +17,39 @@ const userIdType = async (db, users) => {
 	const { rows } = await sql`select format_type(atttypid, atttypmod) as type from pg_attribute where attrelid = ${oid} and attname = 'id'`.execute(db);
 	return rows[0].type;
 };
+const columnsOf = async (db, oid) => (await sql`select attname as name, attnum as num from pg_attribute where attrelid = ${oid} and attnum > 0 and not attisdropped`.execute(db)).rows;
+const uniqueOn = async (db, oid, num) => (await sql`select exists (select from pg_index where indrelid = ${oid} and indisunique and indpred is null and indexprs is null and indnatts = 1 and indkey[0] = ${num}) as found`.execute(db)).rows[0].found;
+const cascadesFrom = async (db, oid, num, users) => (await sql`select exists (select from pg_constraint where conrelid = ${oid} and contype = 'f' and confdeltype = 'c'
+    and conkey = array[${num}]::int2[] and confrelid = to_regclass(${qualified(users)})) as found`.execute(db)).rows[0].found;
+const lacksSessionColumn = async (db, names) => {
+	const oid = await regclass(db, qualified(names));
+	return oid !== null && !(await columnsOf(db, oid)).some((row) => row.name === names.columns.session_id);
+};
 /**
 * The SQL that adds the tables `notifications()` keeps devices and each user's history in, under the names its options
 * give; with `auth`, their user columns point at auth's users table. Each table is left out when it exists or a store
-* of the app's own replaces it; `undefined` when none is left.
+* of the app's own replaces it, and an existing devices table without its session column gets that column;
+* `undefined` when nothing is left.
 */
 const notificationsMigration = async (db, options = {}, auth) => {
 	const devices = !options.store && notificationsNames(options);
 	const history = !options.historyStore && historyNames(options);
 	const missing = async (names) => names && await regclass(db, qualified(names)) === null;
 	const [needsDevices, needsHistory] = [await missing(devices), await missing(history)];
-	if (!needsDevices && !needsHistory) return void 0;
+	const needsSession = devices && !needsDevices && await lacksSessionColumn(db, devices);
+	if (!needsDevices && !needsHistory && !needsSession) return void 0;
 	const users = auth && authUsersTable(auth);
-	const user = users ? {
+	const user = users && (needsDevices || needsHistory) ? {
 		type: await userIdType(db, users),
 		references: `${qualified(users)} (id)`
 	} : { type: "text" };
-	const statements = [...needsDevices && devices ? devicesTableSql(devices, user) : [], ...needsHistory && history ? historyTableSql(history, user) : []];
+	const statements = [
+		...needsDevices && devices ? devicesTableSql(devices, user) : [],
+		...needsSession && devices ? [deviceSessionColumnSql(devices)] : [],
+		...needsHistory && history ? historyTableSql(history, user) : []
+	];
 	return `${[...new Set(statements)].join(";\n\n")};`;
 };
-const columnsOf = async (db, oid) => (await sql`select attname as name, attnum as num from pg_attribute where attrelid = ${oid} and attnum > 0 and not attisdropped`.execute(db)).rows;
-const uniqueOn = async (db, oid, num) => (await sql`select exists (select from pg_index where indrelid = ${oid} and indisunique and indpred is null and indexprs is null and indnatts = 1 and indkey[0] = ${num}) as found`.execute(db)).rows[0].found;
-const cascadesFrom = async (db, oid, num, users) => (await sql`select exists (select from pg_constraint where conrelid = ${oid} and contype = 'f' and confdeltype = 'c'
-    and conkey = array[${num}]::int2[] and confrelid = to_regclass(${qualified(users)})) as found`.execute(db)).rows[0].found;
 const missingTable = (what, table) => /* @__PURE__ */ new Error(`The ${what} table ${table} of notifications() is missing. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
 /**
 * Refuses to start while the devices table lacks what `notifications()` needs, naming it: the table, each column under

package/dist/notifications/send-input.d.ts

@@ -0,0 +1,28 @@
+import { PushMessage } from "./message.js";
+import { Db } from "@protobase/query";
+//#region src/notifications/send-input.d.ts
+/** The most users or devices one send reaches. */
+export declare const maxRecipients = 1000;
+/** The most bytes a checked message takes as JSON. */
+export declare const maxMessageBytes = 16384;
+/**
+ * Who a send reaches: users, saying whether it shows in their inbox, or devices by id, which it is only pushed to.
+ * `inbox` is required on a user send and refused on a device send.
+ */
+export type NotificationRecipients = {
+  userIds: readonly string[];
+  inbox: boolean;
+  deviceIds?: never;
+} | {
+  deviceIds: readonly string[];
+  userIds?: never;
+  inbox?: never;
+};
+/** Sends a notification as `sendNotification` does. */
+export type SendNotification = (db: Db, to: NotificationRecipients, message: PushMessage) => Promise<void>;
+/** A send that is not one `checkedSend` accepts: `field` names the part at fault, never its value. */
+export declare class NotificationSendError extends Error {
+  readonly field: string;
+  constructor(field: string);
+}
+//#endregion

package/dist/notifications/send-input.js

@@ -0,0 +1,80 @@
+import { notificationProblem } from "./history.js";
+import { PushMessageError, pushMessage } from "./message.js";
+//#region src/notifications/send-input.ts
+/** The most users or devices one send reaches. */
+const maxRecipients = 1e3;
+/** The most bytes a checked message takes as JSON. */
+const maxMessageBytes = 16384;
+/** A send that is not one `checkedSend` accepts: `field` names the part at fault, never its value. */
+var NotificationSendError = class extends Error {
+	field;
+	constructor(field) {
+		super(`The notification cannot be sent: its ${field} is invalid`);
+		this.field = field;
+	}
+};
+const idPattern = /^[^\u0000-\u001f\u007f]{1,256}$/;
+/** Whether `value` is an object literal, so its keys are all it holds. */
+const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const checkedIds = (value, field) => {
+	if (!Array.isArray(value) || value.length === 0 || value.length > 1e3) throw new NotificationSendError(field);
+	if (!value.every((id) => typeof id === "string" && idPattern.test(id))) throw new NotificationSendError(field);
+	return [...new Set(value)];
+};
+const checkedKeys = (to, allowed) => {
+	const unknown = Object.keys(to).find((key) => !allowed.includes(key));
+	if (unknown !== void 0) throw new NotificationSendError(`to.${unknown}`);
+};
+const checkedRecipients = (to) => {
+	if (!isPlainRecord(to)) throw new NotificationSendError("to");
+	if (Object.hasOwn(to, "userIds") && Object.hasOwn(to, "deviceIds")) throw new NotificationSendError("to");
+	if (Object.hasOwn(to, "deviceIds")) {
+		checkedKeys(to, ["deviceIds"]);
+		return { deviceIds: checkedIds(to.deviceIds, "to.deviceIds") };
+	}
+	if (!Object.hasOwn(to, "userIds")) throw new NotificationSendError("to");
+	checkedKeys(to, ["userIds", "inbox"]);
+	if (typeof to.inbox !== "boolean") throw new NotificationSendError("to.inbox");
+	return {
+		userIds: checkedIds(to.userIds, "to.userIds"),
+		inbox: to.inbox
+	};
+};
+const checkedMessage = (message) => {
+	let checked;
+	try {
+		checked = pushMessage(message);
+	} catch (error) {
+		if (!(error instanceof PushMessageError)) throw error;
+		throw new NotificationSendError(error.field === "message" ? "message" : `message.${error.field}`);
+	}
+	if (Buffer.byteLength(JSON.stringify(checked)) > 16384) throw new NotificationSendError("message");
+	return checked;
+};
+/** The entry a user's history keeps of a checked message. */
+const historyEntry = (message) => ({
+	title: message.title,
+	body: message.body ?? null,
+	url: message.url ?? null,
+	data: message.data ?? null
+});
+/**
+* The send, checked, or a `NotificationSendError` naming the first field at fault: recipients of one kind, 1 to
+* `maxRecipients` ids, a user send's `inbox` a boolean, and a message `pushMessage` accepts, its url an absolute `http`
+* or `https` URL written as the parser writes it, of at most `maxMessageBytes`. For the inbox, the message must also be
+* one the history keeps.
+*/
+const checkedSend = (to, message) => {
+	const recipients = checkedRecipients(to);
+	const checked = checkedMessage(message);
+	if ("userIds" in recipients && recipients.inbox) {
+		const problem = notificationProblem(historyEntry(checked));
+		if (problem !== void 0) throw new NotificationSendError(`message.${problem}`);
+	}
+	return {
+		to: recipients,
+		message: checked
+	};
+};
+//#endregion
+export { NotificationSendError, checkedSend, historyEntry, isPlainRecord, maxMessageBytes, maxRecipients };

package/dist/notifications/send-notification.d.ts

@@ -0,0 +1,11 @@
+import { SendNotification } from "./send-input.js";
+//#region src/notifications/send-notification.d.ts
+/**
+ * Sends `message` to users or to devices as a background job, enqueued in `db`'s transaction when it is one, so it
+ * goes out only once that commits. A user send says whether it shows in the users' inbox: then each user's history
+ * keeps it, and either way it is pushed to their devices as they are when the job runs; a device send is only pushed.
+ * The send is checked before anything is enqueued (see `checkedSend`), and authorizes nothing: who gets what is the
+ * caller's to decide.
+ */
+export declare const sendNotification: SendNotification;
+//#endregion

package/dist/notifications/send-notification.js

@@ -0,0 +1,19 @@
+import { currentJobs } from "../jobs/current.js";
+import { checkedSend } from "./send-input.js";
+import { pushJobName } from "./push-job-name.js";
+//#region src/notifications/send-notification.ts
+/**
+* Sends `message` to users or to devices as a background job, enqueued in `db`'s transaction when it is one, so it
+* goes out only once that commits. A user send says whether it shows in the users' inbox: then each user's history
+* keeps it, and either way it is pushed to their devices as they are when the job runs; a device send is only pushed.
+* The send is checked before anything is enqueued (see `checkedSend`), and authorizes nothing: who gets what is the
+* caller's to decide.
+*/
+const sendNotification = async (db, to, message) => {
+	const send = checkedSend(to, message);
+	const job = currentJobs().definition(pushJobName);
+	if (!job) throw new Error("Notifications are off: add extends: [notifications()] to protobase.config.ts to send them");
+	await job.enqueue(db, send);
+};
+//#endregion
+export { sendNotification };

package/dist/notifications/sender.d.ts

@@ -1,14 +1,15 @@
-import { Device, DeviceKind } from "./device.js";
 import { PushMessage } from "./message.js";
+import { Device, DeviceKind } from "./device.js";
 //#region src/notifications/sender.d.ts
 /**
  * What a sender answers for one device: `ok` when the push service took the message, `gone` when the device no longer
  * exists there and should be removed, `retry` when it may take the message later, after `retryAfterSeconds` when the
- * push service says.
+ * push service says, and `refused` when the sender never delivers to the device as it is stored, such as one whose
+ * endpoint is on no known push service: it is neither retried nor removed.
  */
 export type PushAnswer = {
   id: string;
-  result: 'ok' | 'gone' | 'retry';
+  result: 'ok' | 'gone' | 'retry' | 'refused';
   retryAfterSeconds?: number;
 };
 /**

package/dist/notifications/store-call.js

@@ -0,0 +1,32 @@
+import { StaleJobError } from "../jobs/job-progress.js";
+//#region src/notifications/store-call.ts
+/** A device or history store method that failed while sending: it names the method and at most a SQLSTATE. */
+var NotificationStoreError = class extends Error {
+	method;
+	code;
+	constructor(method, code) {
+		super(`The notifications store's ${method} failed${code ? ` (${code})` : ""}`);
+		this.method = method;
+		this.code = code;
+	}
+};
+const sqlStatePattern = /^[0-9A-Z]{5}$/;
+const codeOf = (error) => {
+	const { sqlState, code } = typeof error === "object" && error !== null ? error : {};
+	return [sqlState, code].find((value) => typeof value === "string" && sqlStatePattern.test(value));
+};
+/**
+* Calls a store method for the send job. Whatever it throws becomes a `NotificationStoreError` with no cause: an app's
+* own store may throw a driver error whose message or detail holds a token or key, and the job keeps its error. A try
+* that no longer holds its job stops as it is.
+*/
+const storeCall = async (method, call) => {
+	try {
+		return await call();
+	} catch (error) {
+		if (error instanceof StaleJobError) throw error;
+		throw new NotificationStoreError(method, codeOf(error));
+	}
+};
+//#endregion
+export { NotificationStoreError, storeCall };