@protobase/server 0.45.17 → 0.45.19

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,6 +1,6 @@
 import { HttpProblem } from "../problem.js";
+import { ownSignInUser } from "./caller.js";
 import "./paths.js";
-import { ownDeviceUser } from "./caller.js";
 import { deviceInput, maxDeviceBodyBytes } from "./device-input.js";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
@@ -8,7 +8,7 @@ import { bodyLimit } from "hono/body-limit";
 /** 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", ownDeviceUser(c.get("session")));
+	c.set("deviceUser", ownSignInUser(c.get("session")));
 	await next();
 };
 const jsonOnly = async (c, next) => {

package/dist/notifications/schema.d.ts

@@ -3,15 +3,11 @@ import { NotificationsOptions } from "./options.js";
 import { Db } from "@protobase/query";
 //#region src/notifications/schema.d.ts
 /**
- * The SQL that adds the devices table `notifications()` keeps devices in, under the names its options give; with
- * `auth`, its user column points at auth's users table. `undefined` when the table exists, and with a store of the
- * app's own, which needs none.
+ * 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.
  */
 export declare const notificationsMigration: (db: Db, options?: NotificationsOptions, auth?: AdminAuth) => Promise<string | undefined>;
-/**
- * Refuses to start while the devices table lacks what `notifications()` needs, naming it: the table, each column under
- * its configured name, a unique index on the token alone, which moving a device relies on, and with `auth` a foreign key
- * from the user column that deletes a user's devices with the user. Nothing to check with a store of the app's own.
- */
+/** Refuses to start while the devices or the history table lacks what `notifications()` needs, naming it. */
 export declare const checkNotificationsSchema: (db: Db, options?: NotificationsOptions, auth?: AdminAuth) => Promise<void>;
 //#endregion

package/dist/notifications/schema.js

@@ -1,7 +1,8 @@
 import { migrationCommand } from "../changes/capture-schema.js";
-import { notificationsNames } from "./options.js";
+import { historyNames, notificationsNames } from "./options.js";
 import { storeSchema } from "../better-auth/auth-tables.js";
 import { devicesTableSql, qualified } from "./schema-sql.js";
+import { historyTableSql } from "./history-sql.js";
 import { sql } from "kysely";
 //#region src/notifications/schema.ts
 /** Auth's users table, as the store names it: devices point at it. */
@@ -17,43 +18,65 @@ const userIdType = async (db, users) => {
 	return rows[0].type;
 };
 /**
-* The SQL that adds the devices table `notifications()` keeps devices in, under the names its options give; with
-* `auth`, its user column points at auth's users table. `undefined` when the table exists, and with a store of the
-* app's own, which needs none.
+* 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.
 */
 const notificationsMigration = async (db, options = {}, auth) => {
-	if (options.store) return void 0;
-	const names = notificationsNames(options);
-	if (await regclass(db, qualified(names)) !== null) return void 0;
+	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 users = auth && authUsersTable(auth);
 	const user = users ? {
 		type: await userIdType(db, users),
 		references: `${qualified(users)} (id)`
 	} : { type: "text" };
-	return `${devicesTableSql(names, user).join(";\n\n")};`;
+	const statements = [...needsDevices && devices ? devicesTableSql(devices, user) : [], ...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
 * its configured name, a unique index on the token alone, which moving a device relies on, and with `auth` a foreign key
 * from the user column that deletes a user's devices with the user. Nothing to check with a store of the app's own.
 */
-const checkNotificationsSchema = async (db, options = {}, auth) => {
+const checkDevicesTable = async (db, options, users) => {
 	if (options.store) return;
 	const names = notificationsNames(options);
 	const devices = qualified(names);
 	const oid = await regclass(db, devices);
-	if (oid === null) throw new Error(`The devices table ${devices} of notifications() is missing. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+	if (oid === null) throw missingTable("devices", devices);
 	const found = await columnsOf(db, oid);
 	const numOf = (column) => found.find((row) => row.name === names.columns[column])?.num;
 	const missing = Object.keys(names.columns).find((column) => numOf(column) === void 0);
 	if (missing !== void 0) throw new Error(`The devices table ${devices} has no column "${names.columns[missing]}": add it, or name the table's own with notifications({ devices: { columns: { ${missing}: ... } } })`);
 	if (!await uniqueOn(db, oid, numOf("token"))) throw new Error(`The devices table ${devices} needs a unique index on its token column "${names.columns.token}" alone, which moving a device to the user who registers it relies on`);
-	const users = auth && authUsersTable(auth);
 	if (users && !await cascadesFrom(db, oid, numOf("user_id"), users)) throw new Error(`The devices table ${devices} needs a foreign key from "${names.columns.user_id}" to ${qualified(users)} with on delete cascade, so a deleted user's devices go with them`);
 };
+/** Refuses to start while the history table lacks its table, a column or, with `auth`, the cascading foreign key. */
+const checkHistoryTable = async (db, options, users) => {
+	if (options.historyStore) return;
+	const names = historyNames(options);
+	const history = qualified(names);
+	const oid = await regclass(db, history);
+	if (oid === null) throw missingTable("history", history);
+	const found = await columnsOf(db, oid);
+	const numOf = (column) => found.find((row) => row.name === names.columns[column])?.num;
+	const missing = Object.keys(names.columns).find((column) => numOf(column) === void 0);
+	if (missing !== void 0) throw new Error(`The history table ${history} has no column "${names.columns[missing]}": add it, or name the table's own with notifications({ history: { columns: { ${missing}: ... } } })`);
+	if (users && !await cascadesFrom(db, oid, numOf("user_id"), users)) throw new Error(`The history table ${history} needs a foreign key from "${names.columns.user_id}" to ${qualified(users)} with on delete cascade, so a deleted user's history goes with them`);
+};
+/** Refuses to start while the devices or the history table lacks what `notifications()` needs, naming it. */
+const checkNotificationsSchema = async (db, options = {}, auth) => {
+	const users = auth && authUsersTable(auth);
+	await checkDevicesTable(db, options, users);
+	await checkHistoryTable(db, options, users);
+};
 //#endregion
 export { authUsersTable, checkNotificationsSchema, notificationsMigration };

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 };

package/dist/notifications/web-push/web-push-sender.d.ts

@@ -9,7 +9,7 @@ export type WebPushOptions = PostOptions & {
  * The built-in Web Push sender (RFC 8030, 8291, 8292): delivers to `web` devices, signed with the VAPID pair and
  * encrypted for each device's keys. It checks the message as `pushMessage` does and throws before any request when it
  * is not one. A device whose endpoint is not on a browser's push service, or whose keys are not a subscription's, is
- * answered `gone` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
+ * answered `refused` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
  */
 export declare const webPushSender: (settings: VapidSettings, options?: WebPushOptions) => PushSender;
 //#endregion

package/dist/notifications/web-push/web-push-sender.js

@@ -33,7 +33,7 @@ const headersOf = (message) => {
 * The built-in Web Push sender (RFC 8030, 8291, 8292): delivers to `web` devices, signed with the VAPID pair and
 * encrypted for each device's keys. It checks the message as `pushMessage` does and throws before any request when it
 * is not one. A device whose endpoint is not on a browser's push service, or whose keys are not a subscription's, is
-* answered `gone` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
+* answered `refused` with no request. It logs nothing, and its errors and answers carry no endpoint, key or token.
 */
 const webPushSender = (settings, options = {}) => {
 	const authorization = vapidAuthorizer(settings, options.now);
@@ -42,7 +42,7 @@ const webPushSender = (settings, options = {}) => {
 		const keys = keysOf(device);
 		if (!url || !keys) return {
 			id: device.id,
-			result: "gone"
+			result: "refused"
 		};
 		const body = encryptPayload(plaintext, keys);
 		const answer = await postPush(url, {

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.45.17";
+var version = "0.45.19";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.45.17",
+  "version": "0.45.19",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,9 +36,9 @@
     "@better-auth/passkey": "^1.7.12",
     "@better-auth/sso": "^1.7.12",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@protobase/layout": "0.45.17",
-    "@protobase/query": "0.45.17",
-    "@protobase/schema": "0.45.17",
+    "@protobase/layout": "0.45.19",
+    "@protobase/query": "0.45.19",
+    "@protobase/schema": "0.45.19",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",