@protobase/server 0.45.17 → 0.45.19

package/dist/notifications/history-routes.js

@@ -0,0 +1,84 @@
+import { badRequest } from "../problem.js";
+import "./history-store.js";
+import { historyIdPattern } from "./history.js";
+import { ownSignInUser } from "./caller.js";
+import { historyCursor, historyPosition } from "./history-cursor.js";
+import { jsonBody, jsonOnly, limitedBody, queryOf } from "./history-request.js";
+import { historyUrl } from "./history-url.js";
+import "./paths.js";
+import { Hono } from "hono";
+import { z } from "zod";
+//#region src/notifications/history-routes.ts
+/** How many entries a page of the history holds when the request names no `limit`. */
+const defaultHistoryPage = 20;
+const ownSignIn = async (c, next) => {
+	c.set("historyUser", ownSignInUser(c.get("session")));
+	await next();
+};
+const noStore = { "Cache-Control": "no-store" };
+const pageLimit = (limit) => {
+	if (limit === void 0) return 20;
+	const value = /^[1-9][0-9]{0,2}$/.test(limit) ? Number(limit) : 0;
+	if (value < 1 || value > 50) throw badRequest("invalid-limit", `The limit is a whole number from 1 to 50`);
+	return value;
+};
+const markAll = z.strictObject({ upTo: z.iso.datetime({ offset: true }) });
+/**
+* The caller's own notification history, mounted at `historyPath` behind the API's authenticator: `GET /` a page of
+* it, newest first, `GET /unread` how many are unread, `POST /read` marks all read up to the newest the caller was
+* shown, `POST /<id>/read` one. No request names a user: each reaches the signed-in user's own entries alone. `origins`
+* are the app's own, which an absolute url may lead to.
+*/
+const historyRoutes = (store, origins) => {
+	const app = new Hono();
+	const answer = (entry) => ({
+		id: entry.id,
+		title: entry.title,
+		body: entry.body,
+		url: historyUrl(entry.url, origins),
+		data: entry.data,
+		createdAt: entry.createdAt.toISOString(),
+		readAt: entry.readAt === null ? null : entry.readAt.toISOString()
+	});
+	app.get("/", ownSignIn, async (c) => {
+		const userId = c.get("historyUser");
+		const query = queryOf(c, ["cursor", "limit"]);
+		const limit = pageLimit(query.limit);
+		const before = query.cursor === void 0 ? void 0 : historyPosition(query.cursor);
+		const entries = await store.list(userId, {
+			...before && { before },
+			limit
+		});
+		if (entries.length > limit || entries.some((entry) => entry.userId !== userId || !historyIdPattern.test(entry.id))) throw new Error("The history store answered list with entries that are not the caller's");
+		const last = entries.at(-1);
+		const next = last && entries.length === limit ? historyCursor(last) : null;
+		return c.json({
+			items: entries.map(answer),
+			next
+		}, 200, noStore);
+	});
+	app.get("/unread", ownSignIn, async (c) => {
+		queryOf(c, []);
+		const count = await store.countUnread(c.get("historyUser"));
+		if (!Number.isSafeInteger(count) || count < 0 || count > 100) throw new Error("The history store answered countUnread with no count");
+		return c.json({ count }, 200, noStore);
+	});
+	app.post("/read", ownSignIn, jsonOnly, limitedBody, async (c) => {
+		queryOf(c, []);
+		const parsed = markAll.safeParse(await jsonBody(c));
+		if (!parsed.success) throw badRequest("invalid-mark", "Send { \"upTo\": <createdAt of the newest notification shown> }");
+		await store.markAllRead(c.get("historyUser"), new Date(parsed.data.upTo));
+		return c.body(null, 204);
+	});
+	app.post(`/:id/read`, ownSignIn, jsonOnly, limitedBody, async (c) => {
+		queryOf(c, []);
+		const body = await jsonBody(c);
+		if (body !== void 0 && (typeof body !== "object" || body === null || Array.isArray(body) || Object.keys(body).length > 0)) throw badRequest("invalid-mark", "Marking one read takes no body");
+		const id = c.req.param("id");
+		if (historyIdPattern.test(id)) await store.markRead(c.get("historyUser"), id);
+		return c.body(null, 204);
+	});
+	return app;
+};
+//#endregion
+export { defaultHistoryPage, historyRoutes };

package/dist/notifications/history-sql.js

@@ -0,0 +1,31 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+import { qualified } from "./schema-sql.js";
+//#region src/notifications/history-sql.ts
+/**
+* The history table: with auth, its user column points at auth's users table and goes with the user. `read_at` is NULL
+* while unread and nothing has a default. One index serves a user's newest-first pages, another their unread ones.
+*/
+const historyTableSql = ({ schema, table, columns }, user) => {
+	const c = Object.fromEntries(Object.entries(columns).map(([name, value]) => [name, quoteIdent(value)]));
+	const history = qualified({
+		schema,
+		table
+	});
+	return [
+		`create schema if not exists ${quoteIdent(schema)}`,
+		`create table ${history} (
+  ${c.id} uuid primary key,
+  ${c.user_id} ${user.type} not null${user.references ? ` references ${user.references} on delete cascade` : ""},
+  ${c.title} text not null,
+  ${c.body} text,
+  ${c.url} text,
+  ${c.data} jsonb,
+  ${c.created_at} timestamptz not null,
+  ${c.read_at} timestamptz
+)`,
+		`create index on ${history} (${c.user_id}, ${c.created_at} desc, ${c.id} desc)`,
+		`create index on ${history} (${c.user_id}, ${c.created_at}) where ${c.read_at} is null`
+	];
+};
+//#endregion
+export { historyTableSql };

package/dist/notifications/history-store-of.d.ts

@@ -0,0 +1,13 @@
+import { AdminAuth } from "../better-auth/create-auth.js";
+import { HistoryStore } from "./history-store.js";
+import { NotificationsOptions } from "./options.js";
+import { Db } from "@protobase/query";
+//#region src/notifications/history-store-of.d.ts
+/**
+ * The history's store `notifications()` configures: the app's own `historyStore`, or the history table in `db`. An app
+ * that deletes users without Protobase's auth calls its `removeAllForUser` as it deletes one.
+ */
+export declare const historyStore: (db: Db, options?: NotificationsOptions) => HistoryStore;
+/** Has `auth` remove a user's history from `store` when it deletes the user, before and once more after. */
+export declare const removeHistoryWithUsers: (auth: AdminAuth, store: HistoryStore) => void;
+//#endregion

package/dist/notifications/history-store-of.js

@@ -0,0 +1,13 @@
+import { postgresHistoryStore } from "./postgres-history-store.js";
+//#region src/notifications/history-store-of.ts
+/**
+* The history's store `notifications()` configures: the app's own `historyStore`, or the history table in `db`. An app
+* that deletes users without Protobase's auth calls its `removeAllForUser` as it deletes one.
+*/
+const historyStore = (db, options = {}) => options.historyStore ?? postgresHistoryStore(db, options);
+/** Has `auth` remove a user's history from `store` when it deletes the user, before and once more after. */
+const removeHistoryWithUsers = (auth, store) => {
+	auth.userDeletion.set("notifications-history", (userId) => store.removeAllForUser(userId));
+};
+//#endregion
+export { historyStore, removeHistoryWithUsers };

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

@@ -0,0 +1,29 @@
+import { HistoryPosition, NewNotification, StoredNotification } from "./history.js";
+//#region src/notifications/history-store.d.ts
+/** The most unread notifications `countUnread` counts: a bell shows "99+" past it. */
+export declare const maxUnreadCount = 100;
+/**
+ * Where each user's inbox notifications are kept: the Postgres default (`postgresHistoryStore`), or a store of the
+ * app's own passed as `notifications({ historyStore })`. Plain data in and out, so any store can implement it. Every
+ * method takes the user and touches that user's entries alone; each throws on an empty user id or id.
+ */
+export type HistoryStore = {
+  /** Keeps the notification for `userId`, unread, created now, under a new id matching `historyIdPattern`. */
+  record: (userId: string, notification: NewNotification) => Promise<StoredNotification>;
+  /** At most `limit` of the user's entries, newest first by creation time then id, starting after `before`. */
+  list: (userId: string, page: {
+    before?: HistoryPosition;
+    limit: number;
+  }) => Promise<StoredNotification[]>;
+  /** How many of the user's entries are unread, counting up to `maxUnreadCount` at most. */
+  countUnread: (userId: string) => Promise<number>;
+  /** Marks the user's entry with this id read now, unless it was read already; false when the user has none such. */
+  markRead: (userId: string, id: string) => Promise<boolean>;
+  /** Marks the user's unread entries created at or before `upTo` read now; entries read already keep their time. */
+  markAllRead: (userId: string, upTo: Date) => Promise<void>;
+  /** Removes every entry of the user, as when the user is deleted. */
+  removeAllForUser: (userId: string) => Promise<void>;
+};
+/** The most entries `list` gives at once. */
+export declare const maxHistoryPage = 50;
+//#endregion

package/dist/notifications/history-store.js

@@ -0,0 +1,39 @@
+//#region src/notifications/history-store.ts
+/** The most unread notifications `countUnread` counts: a bell shows "99+" past it. */
+const maxUnreadCount = 100;
+const methods = [
+	"record",
+	"list",
+	"countUnread",
+	"markRead",
+	"markAllRead",
+	"removeAllForUser"
+];
+/** The store, checked to have every method; a missing one is an error naming it. */
+const checkHistoryStore = (store) => {
+	const missing = methods.find((method) => typeof store[method] !== "function");
+	if (missing !== void 0) throw new Error(`notifications({ historyStore }): the history store has no ${missing} method`);
+	return store;
+};
+/** The most entries `list` gives at once. */
+const maxHistoryPage = 50;
+/** The value, refused when empty: no store call may be read as "every user". */
+const requiredText = (name, value) => {
+	if (typeof value !== "string" || value === "") throw new Error(`The history store needs a ${name}`);
+	return value;
+};
+/** The time, refused when it is no valid `Date`. */
+const requiredTime = (name, value) => {
+	if (!(value instanceof Date) || Number.isNaN(value.getTime())) throw new Error(`The history store needs a ${name}`);
+	return value;
+};
+/** The page asked for, refused unless its limit is a whole number from 1 to `maxHistoryPage` and its position whole. */
+const requiredPage = (page) => {
+	if (typeof page !== "object" || page === null || !Number.isInteger(page.limit) || page.limit < 1 || page.limit > 50) throw new Error(`The history store needs a page limit from 1 to 50`);
+	if (page.before === void 0) return page;
+	requiredTime("position time", page.before.createdAt);
+	requiredText("position id", page.before.id);
+	return page;
+};
+//#endregion
+export { checkHistoryStore, maxHistoryPage, maxUnreadCount, requiredPage, requiredText, requiredTime };

package/dist/notifications/history-url.js

@@ -0,0 +1,18 @@
+//#region src/notifications/history-url.ts
+const ownPath = /^\/(?![/\\])[^\s\u0000-\u001f\u007f-\u009f]*$/;
+const absolute = /^https?:\/\//i;
+/**
+* The url an entry of the history may lead to, as an answer shows it, or `null`: a path on the app, or an absolute
+* `http` or `https` URL without user info whose origin is exactly one of `origins`, the app's own, written as the URL
+* parser writes it. Anything else, another site, `javascript:`, `data:` or a scheme-relative URL, is `null`.
+*/
+const historyUrl = (url, origins) => {
+	if (url === null || url.length > 2048) return null;
+	if (ownPath.test(url)) return url;
+	if (!absolute.test(url) || !URL.canParse(url) || /[\s\u0000-\u001f\u007f-\u009f]/.test(url)) return null;
+	const parsed = new URL(url);
+	if (parsed.username !== "" || parsed.password !== "") return null;
+	return origins.some((origin) => URL.canParse(origin) && new URL(origin).origin === parsed.origin) ? parsed.href : null;
+};
+//#endregion
+export { historyUrl };

package/dist/notifications/history.d.ts

@@ -0,0 +1,34 @@
+import { JsonObject } from "./json-value.js";
+//#region src/notifications/history.d.ts
+/**
+ * A notification as the history keeps it for its user's inbox: what a panel shows of it. `title` and `body` are plain
+ * text; `url` is where it leads; `data` is the app's own JSON.
+ */
+export type NewNotification = {
+  title: string;
+  body: string | null;
+  url: string | null;
+  data: JsonObject | null;
+};
+/** A kept notification: whose it is, its id, when it was recorded and when its user read it, `null` while unread. */
+export type StoredNotification = NewNotification & {
+  id: string;
+  userId: string;
+  createdAt: Date;
+  readAt: Date | null;
+};
+/** Where a page of the history ends: the last entry's creation time and id. The next page starts after it. */
+export type HistoryPosition = {
+  createdAt: Date;
+  id: string;
+};
+/** What an entry id looks like in every history store: it goes into a path, so no `/`, `.`, `?`, `#` or `%`. */
+export declare const historyIdPattern: RegExp;
+/** The longest title, body and url, as a push message takes them, and the most bytes of `data` as JSON. */
+export declare const historyLimits: {
+  readonly title: 256;
+  readonly body: 2048;
+  readonly url: 2048;
+  readonly dataBytes: 4096;
+};
+//#endregion

package/dist/notifications/history.js

@@ -0,0 +1,42 @@
+import { isJsonObject, jsonProblem } from "./json-value.js";
+//#region src/notifications/history.ts
+/** What an entry id looks like in every history store: it goes into a path, so no `/`, `.`, `?`, `#` or `%`. */
+const historyIdPattern = /^[A-Za-z0-9_-]{1,64}$/;
+/** The longest title, body and url, as a push message takes them, and the most bytes of `data` as JSON. */
+const historyLimits = {
+	title: 256,
+	body: 2048,
+	url: 2048,
+	dataBytes: 4096
+};
+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";
+	if (notification.body !== null && !text(notification.body, historyLimits.body, noControlsButLines)) return "body";
+	if (notification.url !== null && !text(notification.url, historyLimits.url, noControls)) return "url";
+	if (notification.data === null) return void 0;
+	if (!isJsonObject(notification.data) || jsonProblem(notification.data, "") !== void 0) return "data";
+	if (Buffer.byteLength(JSON.stringify(notification.data)) > historyLimits.dataBytes) return "data";
+};
+/**
+* The notification as a new object with its four fields alone, or an error naming the first field at fault, never its
+* value: a title of 1 to 256 characters, a body and a url of at most 2048, without control characters, and `data`
+* plain JSON of at most 4096 bytes. Every history store records only what this accepts.
+*/
+const checkedNotification = (notification) => {
+	const problem = notificationProblem(notification);
+	if (problem !== void 0) throw new Error(`The history cannot keep this notification: its ${problem} is invalid`);
+	const { title, body, url, data } = notification;
+	return {
+		title,
+		body,
+		url,
+		data: data === null ? null : structuredClone(data)
+	};
+};
+//#endregion
+export { checkedNotification, historyIdPattern, historyLimits, notificationProblem };

package/dist/notifications/options.d.ts

@@ -1,9 +1,13 @@
 import { DeviceStore } from "./device-store.js";
+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 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"];
+export type HistoryColumn = (typeof historyColumns)[number];
 /** Notifications, turned on with `extends: [notifications()]`. */
 export type NotificationsOptions = {
   /** The bell in the top bar; default true. `false` keeps only the backend. */
@@ -17,6 +21,13 @@ export type NotificationsOptions = {
   };
   /** Keeps the devices somewhere else than the devices table, which is then not needed. */
   store?: DeviceStore;
+  /** The history table: its name, default `history`, and its columns named otherwise than Protobase names them. */
+  history?: {
+    table?: string;
+    columns?: Partial<Record<HistoryColumn, string>>;
+  };
+  /** Keeps each user's notification history somewhere else than the history table, which is then not needed. */
+  historyStore?: HistoryStore;
   /**
    * Deliver notifications in place of the built-in senders, such as senders from a package; at most one for each kind
    * of device. By default the built-in ones whose environment is set: Web Push with the `PROTOBASE_VAPID_*` variables.

package/dist/notifications/options.js

@@ -1,4 +1,5 @@
 import { checkDeviceStore } from "./device-store.js";
+import { checkHistoryStore } from "./history-store.js";
 import { checkSenders } from "./sender.js";
 //#region src/notifications/options.ts
 /** The columns of the devices table, by the name Protobase gives them. */
@@ -15,31 +16,49 @@ const deviceColumns = [
 	"created_at",
 	"last_seen_at"
 ];
+/** The columns of the history table, by the name Protobase gives them. */
+const historyColumns = [
+	"id",
+	"user_id",
+	"title",
+	"body",
+	"url",
+	"data",
+	"created_at",
+	"read_at"
+];
 const namePattern = /^[a-z_][a-z0-9_]*$/;
 const maxNameBytes = 63;
 const checkedName = (option, name) => {
 	if (typeof name !== "string" || !namePattern.test(name) || Buffer.byteLength(name) > maxNameBytes) throw new Error(`notifications ${option} is not a valid name: use lowercase letters, digits and "_", at most ${maxNameBytes} characters`);
 	return name;
 };
-/** The built-in tables' names, checked: a bad or unknown name is an error naming its option. */
-const notificationsNames = (options = {}) => {
-	const given = options.devices?.columns ?? {};
-	const unknown = Object.keys(given).find((name) => !deviceColumns.includes(name));
-	if (unknown !== void 0) throw new Error(`notifications devices.columns names "${unknown}", which is not a column of the devices table: ${deviceColumns.join(", ")}`);
-	const columns = Object.fromEntries(deviceColumns.map((column) => [column, checkedName(`devices.columns.${column}`, given[column] ?? column)]));
-	return {
-		schema: checkedName("schema", options.schema ?? "notifications"),
-		table: checkedName("devices.table", options.devices?.table ?? "devices"),
-		columns
-	};
+const columnNames = (table, all, given = {}) => {
+	const unknown = Object.keys(given).find((name) => !all.includes(name));
+	if (unknown !== void 0) throw new Error(`notifications ${table}.columns names "${unknown}", which is not a column of the ${table} table: ${all.join(", ")}`);
+	return Object.fromEntries(all.map((column) => [column, checkedName(`${table}.columns.${column}`, given[column] ?? column)]));
 };
-/** The options, checked as `notifications()` takes them: the names, a given store's methods and the senders given. */
+/** The devices table's names, checked: a bad or unknown name is an error naming its option. */
+const notificationsNames = (options = {}) => ({
+	schema: checkedName("schema", options.schema ?? "notifications"),
+	table: checkedName("devices.table", options.devices?.table ?? "devices"),
+	columns: columnNames("devices", deviceColumns, options.devices?.columns)
+});
+/** The history table's names, checked as the devices table's are. */
+const historyNames = (options = {}) => ({
+	schema: checkedName("schema", options.schema ?? "notifications"),
+	table: checkedName("history.table", options.history?.table ?? "history"),
+	columns: columnNames("history", historyColumns, options.history?.columns)
+});
+/** The options, checked as `notifications()` takes them: the names, given stores' methods and the senders given. */
 const checkNotificationsOptions = (options) => {
 	if (options.ui !== void 0 && typeof options.ui !== "boolean") throw new Error("notifications ui is true or false");
 	notificationsNames(options);
+	historyNames(options);
 	if (options.store !== void 0) checkDeviceStore(options.store);
+	if (options.historyStore !== void 0) checkHistoryStore(options.historyStore);
 	if (options.senders !== void 0) checkSenders(options.senders);
 	return options;
 };
 //#endregion
-export { checkNotificationsOptions, deviceColumns, notificationsNames };
+export { checkNotificationsOptions, deviceColumns, historyColumns, historyNames, notificationsNames };

package/dist/notifications/paths.d.ts

@@ -3,4 +3,14 @@
 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";
+/**
+ * The path of the caller's notification history under the API's system path (`/api`): the list itself, `unread` its
+ * unread count, `read` marking all read, or `{ read: id }` marking one entry read. An id that could leave the history's
+ * path, any but letters, digits, `_` and `-`, is refused.
+ */
+export declare const historyPath: (systemPath: string, part?: "unread" | "read" | {
+  read: string;
+}) => string;
 //#endregion

package/dist/notifications/paths.js

@@ -1,7 +1,22 @@
+import { historyIdPattern } from "./history.js";
 //#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";
+/**
+* The path of the caller's notification history under the API's system path (`/api`): the list itself, `unread` its
+* unread count, `read` marking all read, or `{ read: id }` marking one entry read. An id that could leave the history's
+* path, any but letters, digits, `_` and `-`, is refused.
+*/
+const historyPath = (systemPath, part) => {
+	const base = `${systemPath}/notifications/history`;
+	if (part === void 0) return base;
+	if (typeof part === "string") return `${base}/${part}`;
+	if (!historyIdPattern.test(part.read)) throw new Error("A history entry id is letters, digits, \"_\" and \"-\" only");
+	return `${base}/${part.read}/read`;
+};
 //#endregion
-export { deviceIdParam, devicesPath };
+export { deviceIdParam, devicesPath, historyIdParam, historyPath };

package/dist/notifications/plugin.d.ts

@@ -4,8 +4,10 @@ import { ProjectConfig } from "../project-config.js";
 /**
  * Notifications: `extends: [notifications()]` in `protobase.config.ts`. It keeps each user's devices, in the
  * `notifications.devices` table that `protobase migration` writes or in the `store` given, and serves the endpoints
- * through which a signed-in user registers and removes their own (`devicesPath`). It delivers through `senders`, by
- * default the built-in ones whose environment is set (see `notificationSenders`).
+ * through which a signed-in user registers and removes their own (`devicesPath`). It keeps each user's inbox
+ * notifications in the `notifications.history` table or the `historyStore` given, and serves the endpoints through which
+ * a signed-in user lists theirs and marks them read (`historyPath`). It delivers through `senders`, by default the
+ * built-in ones whose environment is set (see `notificationSenders`).
  */
 export declare const notifications: (options?: NotificationsOptions) => ProjectConfig;
 //#endregion

package/dist/notifications/plugin.js

@@ -3,8 +3,10 @@ import { checkNotificationsOptions } from "./options.js";
 /**
 * Notifications: `extends: [notifications()]` in `protobase.config.ts`. It keeps each user's devices, in the
 * `notifications.devices` table that `protobase migration` writes or in the `store` given, and serves the endpoints
-* through which a signed-in user registers and removes their own (`devicesPath`). It delivers through `senders`, by
-* default the built-in ones whose environment is set (see `notificationSenders`).
+* through which a signed-in user registers and removes their own (`devicesPath`). It keeps each user's inbox
+* notifications in the `notifications.history` table or the `historyStore` given, and serves the endpoints through which
+* a signed-in user lists theirs and marks them read (`historyPath`). It delivers through `senders`, by default the
+* built-in ones whose environment is set (see `notificationSenders`).
 */
 const notifications = (options = {}) => ({
 	name: "protobase-notifications",

package/dist/notifications/postgres-history-store.d.ts

@@ -0,0 +1,15 @@
+import { HistoryStore } from "./history-store.js";
+import { NotificationsOptions } from "./options.js";
+import { Db } from "@protobase/query";
+//#region src/notifications/postgres-history-store.d.ts
+/**
+ * A database error of the history store, holding its SQLSTATE alone: the driver's own carries the failing row in its
+ * detail, which must never reach a log.
+ */
+export declare class HistoryStoreError extends Error {
+  readonly sqlState: string;
+  constructor(sqlState: string);
+}
+/** The default history store: the history table `protobase migration` writes, under the names the options give. */
+export declare const postgresHistoryStore: (db: Db, options?: NotificationsOptions) => HistoryStore;
+//#endregion

package/dist/notifications/postgres-history-store.js

@@ -0,0 +1,91 @@
+import { isDatabaseError } from "../error-handler.js";
+import { requiredPage, requiredText, requiredTime } from "./history-store.js";
+import { historyColumns, historyNames } from "./options.js";
+import { checkedNotification } from "./history.js";
+import { sql } from "kysely";
+//#region src/notifications/postgres-history-store.ts
+/**
+* A database error of the history store, holding its SQLSTATE alone: the driver's own carries the failing row in its
+* detail, which must never reach a log.
+*/
+var HistoryStoreError = class extends Error {
+	sqlState;
+	constructor(sqlState) {
+		super(`The history store's query failed (SQLSTATE ${sqlState})`);
+		this.sqlState = sqlState;
+	}
+};
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const entryOf = (row) => ({
+	id: String(row.id),
+	userId: String(row.user_id),
+	title: row.title,
+	body: row.body,
+	url: row.url,
+	data: row.data,
+	createdAt: new Date(row.created_at),
+	readAt: row.read_at === null ? null : new Date(row.read_at)
+});
+/** The default history store: the history table `protobase migration` writes, under the names the options give. */
+const postgresHistoryStore = (db, options = {}) => {
+	const { schema, table, columns } = historyNames(options);
+	const history = sql.id(schema, table);
+	const column = (name) => sql.id(columns[name]);
+	const selected = sql.join(historyColumns.map((name) => sql`${column(name)} as ${sql.id(name)}`));
+	const execute = (query) => query.execute(db).catch((error) => {
+		if (isDatabaseError(error)) throw new HistoryStoreError(error.code);
+		throw error;
+	});
+	const rows = async (query) => (await execute(query)).rows.map(entryOf);
+	const unread = (userId) => sql`${column("user_id")} = ${userId} and ${column("read_at")} is null`;
+	return {
+		record: async (userId, notification) => {
+			requiredText("user id", userId);
+			const { title, body, url, data } = checkedNotification(notification);
+			const values = {
+				id: crypto.randomUUID(),
+				user_id: userId,
+				title,
+				body,
+				url,
+				data: data === null ? null : JSON.stringify(data),
+				created_at: /* @__PURE__ */ new Date(),
+				read_at: null
+			};
+			const names = sql.join(historyColumns.map(column));
+			const given = sql.join(historyColumns.map((name) => name === "data" ? sql`${values.data}::jsonb` : sql`${values[name]}`));
+			const [stored] = await rows(sql`insert into ${history} (${names}) values (${given}) returning ${selected}`);
+			return stored;
+		},
+		list: async (userId, page) => {
+			requiredText("user id", userId);
+			const { before, limit } = requiredPage(page);
+			const after = before && uuidPattern.test(before.id) ? sql`and (${column("created_at")}, ${column("id")}) < (${before.createdAt}, ${before.id}::uuid)` : before ? sql`and ${column("created_at")} < ${before.createdAt}` : sql``;
+			return rows(sql`select ${selected} from ${history} where ${column("user_id")} = ${userId} ${after}
+        order by ${column("created_at")} desc, ${column("id")} desc limit ${limit}`);
+		},
+		countUnread: async (userId) => {
+			requiredText("user id", userId);
+			return (await execute(sql`select count(*)::int as count from (select from ${history} where ${unread(userId)} limit ${100}) as unread`)).rows[0].count;
+		},
+		markRead: async (userId, id) => {
+			requiredText("user id", userId);
+			requiredText("id", id);
+			if (!uuidPattern.test(id)) return false;
+			return (await execute(sql`with found as (select ${column("id")} from ${history} where ${column("user_id")} = ${userId} and ${column("id")} = ${id}::uuid),
+        marked as (update ${history} set ${column("read_at")} = ${/* @__PURE__ */ new Date()} where ${column("id")} in (select ${column("id")} from found) and ${column("read_at")} is null)
+        select exists (select from found) as found`)).rows[0].found;
+		},
+		markAllRead: async (userId, upTo) => {
+			requiredText("user id", userId);
+			requiredTime("time", upTo);
+			await execute(sql`update ${history} set ${column("read_at")} = ${/* @__PURE__ */ new Date()} where ${unread(userId)} and ${column("created_at")} <= ${upTo}`);
+		},
+		removeAllForUser: async (userId) => {
+			requiredText("user id", userId);
+			await execute(sql`delete from ${history} where ${column("user_id")} = ${userId}`);
+		}
+	};
+};
+//#endregion
+export { HistoryStoreError, postgresHistoryStore };

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,50 @@
+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. 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) => 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 })
+		});
+	}
+});
+//#endregion
+export { pushJob };