@protobase/server 0.45.13 → 0.45.15

package/dist/notifications/device-input.js

@@ -0,0 +1,80 @@
+import { badRequest } from "../problem.js";
+import { apnsEnvironments } from "./device.js";
+import { canonicalEndpoint, isPushEndpoint } from "./push-hosts.js";
+import { z } from "zod";
+//#region src/notifications/device-input.ts
+const text = (max) => z.string().min(1).max(max).regex(/^[^\u0000-\u001f\u007f]*$/);
+const base64url = (bytes) => z.string().max(200).regex(/^[A-Za-z0-9_-]+$/).refine((value) => Buffer.from(value, "base64url").length === bytes);
+const appId = z.string().regex(/^[A-Za-z0-9._-]{1,155}$/);
+const userAgent = text(512).optional();
+const web = z.strictObject({
+	kind: z.literal("web"),
+	endpoint: text(2048).refine(isPushEndpoint),
+	keys: z.strictObject({
+		p256dh: base64url(65),
+		auth: base64url(16)
+	}),
+	userAgent
+});
+const apns = z.strictObject({
+	kind: z.literal("apns"),
+	token: z.string().regex(/^[0-9a-f]{64,200}$/),
+	environment: z.enum(apnsEnvironments),
+	appId,
+	userAgent
+});
+const fcm = z.strictObject({
+	kind: z.literal("fcm"),
+	token: z.string().regex(/^[A-Za-z0-9_:-]{1,4096}$/),
+	appId: appId.optional(),
+	userAgent
+});
+const registration = z.discriminatedUnion("kind", [
+	web,
+	apns,
+	fcm
+]);
+/** The largest register body, in bytes. */
+const maxDeviceBodyBytes = 8192;
+/**
+* The device a register request's JSON body describes, or a 400 that names the first field at fault and never its
+* value: one kind's fields only, each within its format and length, and nothing else, such as a user.
+*/
+const deviceInput = (body) => {
+	const parsed = registration.safeParse(body);
+	if (!parsed.success) {
+		const field = parsed.error.issues[0].path.join(".") || "body";
+		throw badRequest("invalid-device", `The device is invalid: ${field}`);
+	}
+	const device = parsed.data;
+	const base = { userAgent: device.userAgent ?? null };
+	if (device.kind === "web") return {
+		...base,
+		kind: "web",
+		token: canonicalEndpoint(device.endpoint),
+		p256dh: device.keys.p256dh,
+		auth: device.keys.auth,
+		environment: null,
+		appId: null
+	};
+	if (device.kind === "apns") return {
+		...base,
+		kind: "apns",
+		token: device.token,
+		p256dh: null,
+		auth: null,
+		environment: device.environment,
+		appId: device.appId
+	};
+	return {
+		...base,
+		kind: "fcm",
+		token: device.token,
+		p256dh: null,
+		auth: null,
+		environment: null,
+		appId: device.appId ?? null
+	};
+};
+//#endregion
+export { deviceInput, maxDeviceBodyBytes };

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

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

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

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

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

@@ -0,0 +1,25 @@
+import { Device, NewDevice } from "./device.js";
+//#region src/notifications/device-store.d.ts
+/**
+ * Where each user's devices are kept: the Postgres default (`postgresDeviceStore`), or a store of the app's own passed
+ * as `notifications({ store })`. Plain data in and out, so any store can implement it. Every method throws on an empty
+ * user id, id or token, and none touches every device.
+ */
+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.
+   */
+  register: (userId: string, device: NewDevice) => Promise<Device>;
+  /** 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. */
+  listForUser: (userId: string) => Promise<Device[]>;
+  /** The devices with these ids, whoever holds them: for senders, never for ids a client sends. */
+  listByIds: (ids: readonly string[]) => Promise<Device[]>;
+  /** Removes the devices whose tokens a push service reports gone, whoever holds them: for senders only. */
+  removeGone: (tokens: readonly string[]) => Promise<void>;
+  /** Removes every device of the user, as when the user is deleted. */
+  removeAllForUser: (userId: string) => Promise<void>;
+};
+//#endregion

package/dist/notifications/device-store.js

@@ -0,0 +1,22 @@
+//#region src/notifications/device-store.ts
+const methods = [
+	"register",
+	"remove",
+	"listForUser",
+	"listByIds",
+	"removeGone",
+	"removeAllForUser"
+];
+/** The store, checked to have every method; a missing one is an error naming it. */
+const checkDeviceStore = (store) => {
+	const missing = methods.find((method) => typeof store[method] !== "function");
+	if (missing !== void 0) throw new Error(`notifications({ store }): the device store has no ${missing} method`);
+	return store;
+};
+/** The value, refused when empty: no store call may be read as "every device". */
+const required = (name, value) => {
+	if (typeof value !== "string" || value === "") throw new Error(`The device store needs a ${name}`);
+	return value;
+};
+//#endregion
+export { checkDeviceStore, required };

package/dist/notifications/device.d.ts

@@ -0,0 +1,30 @@
+//#region src/notifications/device.d.ts
+/** How a device receives push: a browser's Web Push subscription, an iOS app's APNs token or an Android app's FCM token. */
+export declare const deviceKinds: readonly ["web", "apns", "fcm"];
+export type DeviceKind = (typeof deviceKinds)[number];
+/** The APNs environment an iOS build's token belongs to. */
+export declare const apnsEnvironments: readonly ["sandbox", "production"];
+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.
+ */
+export type NewDevice = {
+  kind: DeviceKind;
+  token: string;
+  p256dh: string | null;
+  auth: string | null;
+  environment: ApnsEnvironment | null;
+  appId: string | null;
+  userAgent: 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 & {
+  id: string;
+  userId: string;
+  createdAt: Date;
+  lastSeenAt: Date;
+};
+//#endregion

package/dist/notifications/device.js

@@ -0,0 +1,5 @@
+//#region src/notifications/device.ts
+/** The APNs environment an iOS build's token belongs to. */
+const apnsEnvironments = ["sandbox", "production"];
+//#endregion
+export { apnsEnvironments };

package/dist/notifications/options.d.ts

@@ -0,0 +1,20 @@
+import { DeviceStore } from "./device-store.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];
+/** Notifications, turned on with `extends: [notifications()]`. */
+export type NotificationsOptions = {
+  /** The bell in the top bar; default true. `false` keeps only the backend. */
+  ui?: boolean;
+  /** The schema of the built-in tables; default `notifications`. */
+  schema?: string;
+  /** The devices table: its name, default `devices`, and its columns named otherwise than Protobase names them. */
+  devices?: {
+    table?: string;
+    columns?: Partial<Record<DeviceColumn, string>>;
+  };
+  /** Keeps the devices somewhere else than the devices table, which is then not needed. */
+  store?: DeviceStore;
+};
+//#endregion

package/dist/notifications/options.js

@@ -0,0 +1,43 @@
+import { checkDeviceStore } from "./device-store.js";
+//#region src/notifications/options.ts
+/** The columns of the devices table, by the name Protobase gives them. */
+const deviceColumns = [
+	"id",
+	"user_id",
+	"kind",
+	"token",
+	"p256dh",
+	"auth",
+	"environment",
+	"app_id",
+	"user_agent",
+	"created_at",
+	"last_seen_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
+	};
+};
+/** The options, checked as `notifications()` takes them: the names, and a given store's methods. */
+const checkNotificationsOptions = (options) => {
+	if (options.ui !== void 0 && typeof options.ui !== "boolean") throw new Error("notifications ui is true or false");
+	notificationsNames(options);
+	if (options.store !== void 0) checkDeviceStore(options.store);
+	return options;
+};
+//#endregion
+export { checkNotificationsOptions, deviceColumns, notificationsNames };

package/dist/notifications/paths.d.ts

@@ -0,0 +1,6 @@
+//#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;
+//#endregion

package/dist/notifications/paths.js

@@ -0,0 +1,7 @@
+//#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)}`}`;
+//#endregion
+export { deviceIdParam, devicesPath };

package/dist/notifications/plugin.d.ts

@@ -0,0 +1,10 @@
+import { NotificationsOptions } from "./options.js";
+import { ProjectConfig } from "../project-config.js";
+//#region src/notifications/plugin.d.ts
+/**
+ * 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`).
+ */
+export declare const notifications: (options?: NotificationsOptions) => ProjectConfig;
+//#endregion

package/dist/notifications/plugin.js

@@ -0,0 +1,13 @@
+import { checkNotificationsOptions } from "./options.js";
+//#region src/notifications/plugin.ts
+/**
+* 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`).
+*/
+const notifications = (options = {}) => ({
+	name: "protobase-notifications",
+	notifications: checkNotificationsOptions(options)
+});
+//#endregion
+export { notifications };

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

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

package/dist/notifications/postgres-store.js

@@ -0,0 +1,110 @@
+import { isDatabaseError } from "../error-handler.js";
+import { required } from "./device-store.js";
+import { deviceColumns, notificationsNames } from "./options.js";
+import { sql } from "kysely";
+//#region src/notifications/postgres-store.ts
+/**
+* A database error of the device store, holding its SQLSTATE alone: the driver's own carries the failing row in its
+* detail, tokens and keys included, which must never reach a log.
+*/
+var DeviceStoreError = class extends Error {
+	sqlState;
+	constructor(sqlState) {
+		super(`The device 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 deviceOf = (row) => ({
+	id: String(row.id),
+	userId: String(row.user_id),
+	kind: row.kind,
+	token: row.token,
+	p256dh: row.p256dh,
+	auth: row.auth,
+	environment: row.environment,
+	appId: row.app_id,
+	userAgent: row.user_agent,
+	createdAt: new Date(row.created_at),
+	lastSeenAt: new Date(row.last_seen_at)
+});
+/** The default device store: the devices table `protobase migration` writes, under the names the options give. */
+const postgresDeviceStore = (db, options = {}) => {
+	const { schema, table, columns } = notificationsNames(options);
+	const devices = sql.id(schema, table);
+	const column = (name) => sql.id(columns[name]);
+	const selected = sql.join(deviceColumns.map((name) => sql`${column(name)} as ${sql.id(name)}`));
+	const execute = (query) => query.execute(db).catch((error) => {
+		if (isDatabaseError(error)) throw new DeviceStoreError(error.code);
+		throw error;
+	});
+	const rows = async (query) => (await execute(query)).rows.map(deviceOf);
+	return {
+		register: async (userId, device) => {
+			required("user id", userId);
+			required("token", device.token);
+			const now = /* @__PURE__ */ new Date();
+			const values = {
+				id: crypto.randomUUID(),
+				user_id: userId,
+				kind: device.kind,
+				token: device.token,
+				p256dh: device.p256dh,
+				auth: device.auth,
+				environment: device.environment,
+				app_id: device.appId,
+				user_agent: device.userAgent,
+				created_at: now,
+				last_seen_at: now
+			};
+			const names = sql.join(deviceColumns.map(column));
+			const given = sql.join(deviceColumns.map((name) => sql`${values[name]}`));
+			const sameUser = sql`${sql.ref(`d.${columns.user_id}`)} = excluded.${column("user_id")}`;
+			const keep = (name) => sql`${column(name)} = case when ${sameUser} then ${sql.ref(`d.${columns[name]}`)} else excluded.${column(name)} end`;
+			const replaced = [
+				"user_id",
+				"kind",
+				"p256dh",
+				"auth",
+				"environment",
+				"app_id",
+				"user_agent",
+				"last_seen_at"
+			].map((name) => sql`${column(name)} = excluded.${column(name)}`);
+			const [stored] = await rows(sql`insert into ${devices} as d (${names}) values (${given})
+        on conflict (${column("token")}) do update set ${sql.join([
+				keep("id"),
+				keep("created_at"),
+				...replaced
+			])}
+        returning ${selected}`);
+			return stored;
+		},
+		remove: async (userId, id) => {
+			required("user id", userId);
+			required("device id", id);
+			if (!uuidPattern.test(id)) return;
+			await execute(sql`delete from ${devices} where ${column("user_id")} = ${userId} and ${column("id")} = ${id}`);
+		},
+		listForUser: async (userId) => {
+			required("user id", userId);
+			return rows(sql`select ${selected} from ${devices} where ${column("user_id")} = ${userId} order by ${column("last_seen_at")} desc`);
+		},
+		listByIds: async (ids) => {
+			const valid = ids.map((id) => required("device id", id)).filter((id) => uuidPattern.test(id));
+			if (valid.length === 0) return [];
+			return rows(sql`select ${selected} from ${devices} where ${column("id")} = any(${valid}::uuid[])`);
+		},
+		removeGone: async (tokens) => {
+			const given = tokens.map((token) => required("token", token));
+			if (given.length === 0) return;
+			await execute(sql`delete from ${devices} where ${column("token")} = any(${given}::text[])`);
+		},
+		removeAllForUser: async (userId) => {
+			required("user id", userId);
+			await execute(sql`delete from ${devices} where ${column("user_id")} = ${userId}`);
+		}
+	};
+};
+//#endregion
+export { DeviceStoreError, postgresDeviceStore };

package/dist/notifications/push-hosts.js

@@ -0,0 +1,18 @@
+//#region src/notifications/push-hosts.ts
+const exactHosts = [
+	"fcm.googleapis.com",
+	"updates.push.services.mozilla.com",
+	"web.push.apple.com"
+];
+const hostSuffixes = [".notify.windows.com"];
+/** Whether `endpoint`, as a browser's subscription gives it, is an https URL on a known push service, with no userinfo, port or fragment. */
+const isPushEndpoint = (endpoint) => {
+	if (!URL.canParse(endpoint) || endpoint.includes("#")) return false;
+	const url = new URL(endpoint);
+	if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "") return false;
+	return exactHosts.includes(url.hostname) || hostSuffixes.some((suffix) => url.hostname.endsWith(suffix) && url.hostname.length > suffix.length);
+};
+/** The endpoint as one spelling, so two spellings of one subscription are one device. */
+const canonicalEndpoint = (endpoint) => new URL(endpoint).href;
+//#endregion
+export { canonicalEndpoint, isPushEndpoint };

package/dist/notifications/routes.d.ts

@@ -0,0 +1,6 @@
+import "../types.js";
+import { Hono } from "hono";
+//#region src/notifications/routes.d.ts
+/** The most devices one user keeps: registering one more drops their least recently seen. */
+export declare const maxDevicesPerUser = 20;
+//#endregion

package/dist/notifications/routes.js

@@ -0,0 +1,57 @@
+import { HttpProblem } from "../problem.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";
+//#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", ownDeviceUser(c.get("session")));
+	await next();
+};
+const jsonOnly = async (c, next) => {
+	if (c.req.header("content-type")?.split(";")[0]?.trim().toLowerCase() !== "application/json") throw new HttpProblem(415, "json-only", "Unsupported Media Type", "Send the device as application/json");
+	await next();
+};
+const limited = bodyLimit({
+	maxSize: maxDeviceBodyBytes,
+	onError: () => {
+		throw new HttpProblem(413, "too-large", "Payload Too Large", `The device is larger than ${maxDeviceBodyBytes} bytes`);
+	}
+});
+const answer = (device) => ({
+	id: device.id,
+	kind: device.kind,
+	createdAt: device.createdAt.toISOString(),
+	lastSeenAt: device.lastSeenAt.toISOString()
+});
+const dropOldest = async (store, userId, kept) => {
+	const extra = (await store.listForUser(userId)).filter((device) => device.id !== kept.id).sort((a, b) => b.lastSeenAt.getTime() - a.lastSeenAt.getTime()).slice(19);
+	for (const device of extra) await store.remove(userId, device.id);
+};
+/**
+* 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.
+*/
+const deviceRoutes = (store) => {
+	const app = new Hono();
+	app.post("/", ownSignIn, jsonOnly, limited, async (c) => {
+		const userId = c.get("deviceUser");
+		const device = deviceInput(await c.req.json());
+		const stored = await store.register(userId, device);
+		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) => {
+		const userId = c.get("deviceUser");
+		const id = c.req.param("id");
+		if ((await store.listForUser(userId)).some((device) => device.id === id)) await store.remove(userId, id);
+		return c.body(null, 204);
+	});
+	return app;
+};
+//#endregion
+export { deviceRoutes, maxDevicesPerUser };

package/dist/notifications/schema-sql.js

@@ -0,0 +1,40 @@
+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 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.
+*/
+const devicesTableSql = ({ schema, table, columns }, user) => {
+	const c = Object.fromEntries(Object.entries(columns).map(([name, value]) => [name, quoteIdent(value)]));
+	const devices = qualified({
+		schema,
+		table
+	});
+	return [
+		`create schema if not exists ${quoteIdent(schema)}`,
+		`create table ${devices} (
+  ${c.id} uuid primary key,
+  ${c.user_id} ${user.type} not null${user.references ? ` references ${user.references} on delete cascade` : ""},
+  ${c.kind} text not null check (${c.kind} in ('web', 'apns', 'fcm')),
+  ${c.token} text not null,
+  ${c.p256dh} text,
+  ${c.auth} text,
+  ${c.environment} text check (${c.environment} in ('sandbox', 'production')),
+  ${c.app_id} text,
+  ${c.user_agent} text,
+  ${c.created_at} timestamptz not null,
+  ${c.last_seen_at} timestamptz not null,
+  check (
+    (${c.kind} = 'web' and ${c.p256dh} is not null and ${c.auth} is not null and ${c.environment} is null and ${c.app_id} is null)
+    or (${c.kind} = 'apns' and ${c.p256dh} is null and ${c.auth} is null and ${c.environment} is not null and ${c.app_id} is not null)
+    or (${c.kind} = 'fcm' and ${c.p256dh} is null and ${c.auth} is null and ${c.environment} is null)
+  )
+)`,
+		`create unique index on ${devices} (${c.token})`,
+		`create index on ${devices} (${c.user_id})`
+	];
+};
+//#endregion
+export { devicesTableSql, qualified };

package/dist/notifications/schema.d.ts

@@ -0,0 +1,17 @@
+import { AdminAuth } from "../better-auth/create-auth.js";
+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.
+ */
+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.
+ */
+export declare const checkNotificationsSchema: (db: Db, options?: NotificationsOptions, auth?: AdminAuth) => Promise<void>;
+//#endregion

package/dist/notifications/schema.js

@@ -0,0 +1,59 @@
+import { migrationCommand } from "../changes/capture-schema.js";
+import { notificationsNames } from "./options.js";
+import { storeSchema } from "../better-auth/auth-tables.js";
+import { devicesTableSql, qualified } from "./schema-sql.js";
+import { sql } from "kysely";
+//#region src/notifications/schema.ts
+/** Auth's users table, as the store names it: devices point at it. */
+const authUsersTable = (auth) => ({
+	schema: storeSchema(auth),
+	table: auth.options.user?.modelName ?? "user"
+});
+const regclass = async (db, name) => (await sql`select to_regclass(${name})::oid as oid`.execute(db)).rows[0].oid;
+const userIdType = async (db, users) => {
+	const oid = await regclass(db, qualified(users));
+	if (oid === null) throw new Error(`notifications(): auth's users table ${qualified(users)} is not in the app's database, so devices cannot point at it`);
+	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;
+};
+/**
+* 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.
+*/
+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 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 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;
+/**
+* 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) => {
+	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.`);
+	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`);
+};
+//#endregion
+export { authUsersTable, checkNotificationsSchema, notificationsMigration };

package/dist/package.js

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