@db3.ai/app 0.1.0-beta.1 → 0.1.0-beta.4

package/src/health/fastify.ts

@@ -0,0 +1,49 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import type * as health from './contracts';
+
+/**
+ * Registers the canonical application health endpoint on a Fastify server.
+ *
+ * Healthy and degraded reports return HTTP 200 so optional degradation does not
+ * remove the process from service. An unhealthy component returns HTTP 503.
+ * Compatibility aliases are useful while external monitors migrate to `/health`.
+ *
+ * @param server - Fastify server that owns the HTTP lifecycle.
+ * @param options - Application health service and route paths.
+ */
+export function registerHealthRoute(server: FastifyInstance, options: health.HealthRouteOptions): void {
+	const paths = uniquePaths(options.path ?? '/health', options.aliases ?? []);
+
+	for (const path of paths) {
+		server.get(path, async (_request, reply) => healthResponse(options.app.health, reply));
+	}
+}
+
+/**
+ * Builds one safe response from the shared health service.
+ *
+ * @param service - Application health registry.
+ * @param reply - Fastify response used to set status and cache policy.
+ * @returns Aggregate health report.
+ */
+async function healthResponse(service: health.HealthApplication['health'], reply: FastifyReply): Promise<health.HealthReport> {
+	const report = await service.report();
+	reply.header('cache-control', 'no-store');
+	reply.code(report.status === 'unhealthy' ? 503 : 200);
+	return report;
+}
+
+/**
+ * Validates and deduplicates canonical and compatibility route paths.
+ *
+ * @param canonical - Canonical health endpoint path.
+ * @param aliases - Optional compatibility paths.
+ * @returns Unique validated route paths in registration order.
+ */
+function uniquePaths(canonical: string, aliases: string[]): string[] {
+	return [...new Set([canonical, ...aliases].map(path => {
+		const normalized = path.trim();
+		if (!normalized.startsWith('/')) throw new TypeError(`Health route "${path}" must start with "/".`);
+		return normalized;
+	}))];
+}

package/src/health/index.ts

@@ -0,0 +1,3 @@
+export { Health } from './Health';
+export { databaseHealthCheck } from './databaseHealthCheck';
+export type * from './contracts';

package/src/in-app/InApp.ts

@@ -0,0 +1,173 @@
+import type { Knex } from 'knex';
+import { createHash } from 'node:crypto';
+import { ActiveRecord } from '../db';
+import { UserIdentity, type UserIdentityModel } from '../auth';
+import { app } from '../server/appContext';
+import { InAppRecord } from './InAppRecord';
+import { InAppError } from './InAppError';
+import { normalizeMessage, normalizeQuery, normalizeRecipients, normalizeScope, normalizeSend } from './validation';
+import type * as inbox from './contracts';
+
+/** Persistent in-app inbox independent of notification classes, email and live delivery. */
+export class InApp {
+	readonly #commits = new WeakMap<Knex.Transaction, Promise<boolean>>();
+	/** Creates the service; ordinary applications use app().inApp and App's configured Auth identity model. */
+	constructor(readonly options: inbox.InAppOptions = {}, readonly identityModel: UserIdentityModel = UserIdentity) {}
+
+	/**
+	 * Atomically accepts one message for up to 100 distinct recipients.
+	 * Trusted server code owns sender authorization. The service validates identities and receive-scope policy.
+	 * @param recipients - User ID or IDs; an empty list creates no work.
+	 * @param message - Inbox content with a required plain-text fallback and optional rich body.
+	 * @param options - Explicit scope, notification type and optional deduplication key.
+	 * @returns Per-recipient durable acceptance, never a claim of browser delivery.
+	 * @example await app().inApp.send(userId, { title: 'Ready', body: 'Your report is ready.' }, { scope: { type: 'account' }, type: 'report.ready' });
+	 */
+	async send(recipients: string | readonly string[], message: inbox.InAppMessage, options: inbox.InAppSendOptions): Promise<inbox.InAppAcceptance[]> {
+		const ids = normalizeRecipients(recipients);
+		const content = normalizeMessage(message);
+		const input = normalizeSend(options);
+		const contentHash = hash(content);
+		if (!ids.length) return [];
+		const connection = InAppRecord.getDb();
+		const committed = this.#committed(connection);
+		const accepted = await connection.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+			// Lock in stable order so concurrent batches and retries cannot deadlock by recipient order.
+			const canonicalIds = new Map<string, string>();
+			for (const userId of [...ids].sort((left, right) => left.toLowerCase().localeCompare(right.toLowerCase()))) {
+				const row = await this.identityModel.where(this.identityModel.primaryKey, userId).toKnex().forUpdate().first();
+				if (!row) throw new InAppError('forbidden', 'Notification recipient is unavailable.');
+				const canonicalId = String(this.identityModel.fromDb(row).get(this.identityModel.primaryKey));
+				canonicalIds.set(userId, canonicalId);
+				await this.#authorize(canonicalId, input.scope, 'receive');
+			}
+			const results: inbox.InAppAcceptance[] = [];
+			for (const userId of new Set(ids.map(id => canonicalIds.get(id)!))) {
+				const deduplicationHash = input.key === undefined ? null : hash([userId, input.scope.type, scopeId(input.scope), input.type, input.key]);
+				// Request a current read; stale outer snapshots may require a caller-owned transaction retry.
+				const existingRow = deduplicationHash ? await InAppRecord.where('deduplicationHash', deduplicationHash).toKnex().forUpdate().first() : null;
+				const existing = existingRow ? InAppRecord.fromDb(existingRow) : null;
+				if (existing) {
+					if (existing.contentHash !== contentHash) throw new InAppError('conflict', 'This notification key already has different content.');
+					results.push({ userId, id: existing.id, status: 'existing' });
+					continue;
+				}
+				const record = InAppRecord.create({ userId, scopeType: input.scope.type, scopeId: scopeId(input.scope), type: input.type, message: content, presentation: content.presentation, deduplicationHash, contentHash });
+				await record.save();
+				results.push({ userId, id: record.id, status: 'created' });
+			}
+			return results;
+		}));
+		await this.#changed(accepted.filter(item => item.status === 'created').map(item => item.userId), committed);
+		return accepted;
+	}
+
+	/**
+	 * Lists only the authenticated user's unarchived items in an authorized scope.
+	 * @param query - Scope, page size, optional position and inbox/banner view.
+	 * @returns Safe content, unread count and next-page position. Reading a page changes no state.
+	 */
+	async inbox(query: inbox.InAppInboxQuery): Promise<inbox.InAppInboxPage> {
+		const input = normalizeQuery(query);
+		const userId = await this.#reader(input.scope, 'read');
+		const rows = this.#query(userId, input.scope).whereNull('archivedAt');
+		if (input.view === 'banners') rows.where('presentation', 'banner').whereNull('dismissedAt');
+		if (input.before) rows.where('id', '<', input.before);
+		const records = await rows.orderBy('id', 'desc').limit(input.limit + 1).all();
+		const unreadCount = await this.#query(userId, input.scope).whereNull('archivedAt').whereNull('readAt').count();
+		const items = records.slice(0, input.limit).map(itemView);
+		return { items, unreadCount, nextBefore: records.length > input.limit ? items.at(-1)!.id : null };
+	}
+
+	/**
+	 * Changes one owned item's read, dismissal or archive state without coupling those states.
+	 * @param id - Inbox item ID; a foreign or missing ID returns the same not-found error.
+	 * @param transition - Explicit recipient action.
+	 * @param scope - Currently authorized scope, never inferred from the target item.
+	 */
+	async update(id: string, transition: inbox.InAppTransition, scope: inbox.InAppScope): Promise<void> {
+		const input = normalizeScope(scope);
+		if (!/^[0-9A-HJKMNP-TV-Z]{26}$/.test(id) || !['read', 'unread', 'dismiss', 'archive'].includes(transition)) throw new InAppError('invalid', 'Invalid inbox state change.');
+		const userId = await this.#reader(input, 'update');
+		const query = this.#query(userId, input).where('id', id);
+		if (!await query.first()) throw new InAppError('not_found', 'Inbox item not found.');
+		const field = transition === 'dismiss' ? 'dismissedAt' : transition === 'archive' ? 'archivedAt' : 'readAt';
+		const committed = this.#committed(InAppRecord.getDb());
+		const update = this.#query(userId, input).where('id', id);
+		if (transition !== 'unread') update.whereNull(field);
+		const count = await update.patch({ [field]: transition === 'unread' ? null : new Date() });
+		if (count) await this.#changed([userId], committed);
+	}
+
+	/** Observes all surrounding savepoints and the outer commit, including explicit rollback without an error. */
+	#committed(connection: Knex): Promise<boolean> | undefined {
+		if (!this.options.onChanged || !connection.isTransaction) return;
+		const transactions: Promise<boolean>[] = [];
+		let current: Knex.Transaction | undefined = connection as Knex.Transaction;
+		while (current) {
+			const transaction: Knex.Transaction = current;
+			let result = this.#commits.get(transaction);
+			if (!result) {
+				let rolledBack = false;
+				/** The final control statement distinguishes silent rollback from commit or savepoint release. */
+				const query = (event: { sql: string }): void => {
+					if (/^ROLLBACK/i.test(event.sql)) rolledBack = true;
+					else if (/^(COMMIT|RELEASE SAVEPOINT)/i.test(event.sql)) rolledBack = false;
+				};
+				transaction.on('query', query);
+				result = transaction.executionPromise.then(() => !rolledBack, () => false).finally(() => transaction.off('query', query));
+				this.#commits.set(transaction, result);
+			}
+			transactions.push(result);
+			current = transaction.parentTransaction;
+		}
+		return Promise.all(transactions).then(results => results.every(Boolean));
+	}
+
+	/** Publishes only committed recipient changes; nested transactions defer without blocking their own commit. */
+	async #changed(userIds: string[], committed?: Promise<boolean>): Promise<void> {
+		if (!this.options.onChanged || !userIds.length) return;
+		const connection = app().db.knex;
+		/** Contains push failures so retrying notification delivery cannot duplicate an accepted message. */
+		const deliver = async (): Promise<void> => ActiveRecord.withDb(connection, async () => {
+			await Promise.all([...new Set(userIds)].map(async userId => {
+				try { await this.options.onChanged!(userId); }
+				catch (error) { try { this.options.onDeliveryError?.(error); } catch { /* Reporting cannot undo the write. */ } }
+			}));
+		});
+		if (committed) { void committed.then(success => { if (success) return deliver(); }); }
+		else await deliver();
+	}
+
+	/** Builds an ownership-scoped query; callers never accept a reader ID from a browser. */
+	#query(userId: string, scope: inbox.InAppScope) {
+		return InAppRecord.where('userId', userId).where('scopeType', scope.type).where('scopeId', scopeId(scope));
+	}
+
+	/** Requires isolated request authentication and current scope authorization on every operation. */
+	async #reader(scope: inbox.InAppScope, operation: 'read' | 'update'): Promise<string> {
+		const application = app();
+		const user = application.requestContext.active ? application.auth.user : null;
+		if (!user) throw new InAppError('unauthenticated', 'Sign in to access your inbox.');
+		const userId = String(user.get(this.identityModel.primaryKey));
+		await this.#authorize(userId, scope, operation);
+		return userId;
+	}
+
+	/** Account ownership is built in; application scopes require an explicit policy. */
+	async #authorize(userId: string, scope: inbox.InAppScope, operation: 'receive' | 'read' | 'update'): Promise<void> {
+		if (scope.type === 'account' && !this.options.authorizeScope) return;
+		if (!await this.options.authorizeScope?.(userId, scope, operation)) throw new InAppError('forbidden', 'Notification scope is unavailable.');
+	}
+}
+
+/** Uses a nonempty sentinel only for the explicitly typed account scope. */
+function scopeId(scope: inbox.InAppScope): string { return scope.type === 'account' ? 'account' : scope.id!; }
+
+/** Hashes a normalized value; array envelopes avoid ambiguous delimiter concatenation. */
+function hash(value: unknown): string { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+
+/** Serializes only the public inbox contract, never routing or deduplication internals. */
+function itemView(record: InAppRecord): inbox.InAppItem {
+	return { id: record.id, type: record.type, message: record.message, createdAt: record.createdAt.toISOString(), readAt: record.readAt?.toISOString() ?? null, dismissedAt: record.dismissedAt?.toISOString() ?? null, archivedAt: record.archivedAt?.toISOString() ?? null };
+}

package/src/in-app/InAppError.ts

@@ -0,0 +1,8 @@
+/** Stable service errors that HTTP adapters may translate without exposing storage details. */
+export class InAppError extends Error {
+	/** Creates a validation, access, missing-item or conflicting-retry error. */
+	constructor(readonly code: 'invalid' | 'unauthenticated' | 'forbidden' | 'not_found' | 'conflict', message: string) {
+		super(message);
+		this.name = 'InAppError';
+	}
+}

package/src/in-app/InAppRecord.ts

@@ -0,0 +1,41 @@
+import { ActiveRecord, type FieldBuilder } from '../db';
+import type { InAppMessage } from './contracts';
+
+/** Durable inbox item and independent state for one recipient; install through app migrations. */
+export class InAppRecord extends ActiveRecord {
+	static override table = 'in_app_messages';
+	static override requestFillable: string[] = [];
+
+	/** Defines inbox ownership, deduplication and recipient-state storage. */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(),
+			userId: field.string({ column: 'user_id', required: true, length: 255, maxLength: 255, indexes: [{ name: 'in_app_recipient_scope', columns: ['user_id', 'scope_type', 'scope_id'] }] }),
+			scopeType: field.string({ column: 'scope_type', required: true, length: 80, maxLength: 80 }),
+			scopeId: field.string({ column: 'scope_id', required: true, length: 255, maxLength: 255 }),
+			type: field.string({ required: true, length: 120, maxLength: 120 }),
+			message: field.json<InAppMessage>({ required: true }),
+			deduplicationHash: field.string({ column: 'deduplication_hash', length: 64, maxLength: 64, unique: true, hidden: true }),
+			contentHash: field.string({ column: 'content_hash', required: true, length: 64, maxLength: 64, hidden: true }),
+			presentation: field.string({ required: true, length: 16, maxLength: 16 }),
+			readAt: field.timestamp({ column: 'read_at' }),
+			dismissedAt: field.timestamp({ column: 'dismissed_at' }),
+			archivedAt: field.timestamp({ column: 'archived_at' }),
+			createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+		};
+	}
+
+	declare id: string;
+	declare userId: string;
+	declare scopeType: string;
+	declare scopeId: string;
+	declare type: string;
+	declare message: InAppMessage;
+	declare deduplicationHash: string | null;
+	declare contentHash: string;
+	declare presentation: string;
+	declare readAt: Date | null;
+	declare dismissedAt: Date | null;
+	declare archivedAt: Date | null;
+	declare createdAt: Date;
+}

package/src/in-app/README.md

@@ -0,0 +1,193 @@
+# In-app messages
+
+`@db3.ai/app/in-app` provides `app().inApp`: a durable recipient inbox usable
+directly or through `app().notifications`. It accepts typed content with a required
+plain-text fallback and optional rich HTML body, persists one item per recipient and supports scoped inbox
+queries, unread counts, banner queries and independent read/dismiss/archive state.
+
+This first implementation is a server service. It does not yet include HTTP route
+registration, a packaged browser client, mark-all-read, preferences or push
+delivery. The notification coordinator supports application-owned `toInApp()` and
+`toMail()` renderers, but does not yet persist a generic channel outbox. `presentation` records UI intent;
+it does not display a banner or toast by itself.
+
+## Install storage
+
+Add `InAppRecord` to the application's existing `server/database/models.ts` registry:
+
+```ts
+import { InAppRecord } from '@db3.ai/app/in-app';
+
+// Include alongside the existing Auth and application models.
+export const notificationModels = [InAppRecord];
+```
+
+Generate/review a committed migration with `db3 db:make-migration add_in_app_messages`, then apply it
+with `db3 db:migrate`. The App service getter never creates tables. Tests may use
+`await application.db.install(UserIdentity, InAppRecord)` on a disposable database.
+The service uses ActiveRecord's active connection and joins an outer
+`application.db.transaction(...)` through a savepoint; outer rollback removes
+accepted inbox items too. No `db` argument is propagated through normal calls.
+
+## Send from trusted application code
+
+```ts
+import { app } from '@db3.ai/app/server';
+
+const results = await app().inApp.send(
+	userId, // Or an array of user IDs.
+	{
+		title: 'Your content plan is ready',
+		body: 'Open the planner to review your articles.',
+		bodyHtml: '<p>Open the planner to review your <strong>articles</strong>.</p>',
+		severity: 'success',
+		presentation: 'banner',
+		action: { label: 'View plan', href: '/app/planner' },
+	},
+	{
+		scope: { type: 'account' },
+		type: 'content-plan.ready',
+		key: completionId,
+	},
+);
+```
+
+See [sendReportReady.ts](./examples/sendReportReady.ts) for the executable
+code-owned example. No notification class or template database is needed.
+
+`send()` is a trusted producer API, usable by background jobs. Never expose it
+as an unrestricted browser send endpoint. Application code authorizes the producer
+and chooses recipients. The service verifies identities through the App's configured
+Auth identity model and checks recipient eligibility for the scope. It accepts at
+most 100 input IDs, deduplicates canonical recipient identities, returns an empty
+array for no recipients and accepts a batch atomically. Invalid or unavailable
+recipients cannot leave a partially accepted batch.
+
+Each result is `{ userId, id, status: 'created' | 'existing' }`. Acceptance means
+database persistence, not display. `key` identifies an occurrence within recipient,
+scope and `type`; retries return the existing ID without resetting read/dismissal
+state. Different content under the same key raises `InAppError` with code `conflict`.
+Omit the key for a new occurrence every time. Concurrent sends serialize by locking
+recipient identity rows in stable order; a unique stored hash backs deduplication.
+Applications sharing those rows in larger transactions must follow consistent lock
+ordering and retry the entire domain transaction on database deadlocks or stale-snapshot
+errors (including MariaDB ER_CHECKREAD). The service must not retry a fragment of an
+outer transaction or claim acceptance when that transaction failed.
+
+Content is copied and validated before writes. Titles, fallback bodies and labels are
+plain text. `bodyHtml` optionally carries richer application-authored content. The
+framework validates its length but does not sanitize it because each application owns
+its permitted markup; every renderer must sanitize it before interpreting HTML. The service allows root-relative or credential-free HTTP(S) actions
+and rejects unsafe schemes, protocol-relative URLs, whitespace and backslashes.
+Renderers must use text-safe bindings; action destinations enforce their own access.
+This is URL-scheme validation, not an application-specific trusted-host allowlist.
+
+## Authenticated inbox
+
+Authenticate the request using the existing framework Auth flow in an isolated
+`RequestContext`. Then call the service without a client-supplied reader ID:
+
+```ts
+const page = await app().inApp.inbox({
+	scope: { type: 'account' },
+	limit: 25,
+});
+
+await app().inApp.update(itemId, 'read', { type: 'account' });
+await app().inApp.update(itemId, 'unread', { type: 'account' });
+await app().inApp.update(itemId, 'dismiss', { type: 'account' });
+await app().inApp.update(itemId, 'archive', { type: 'account' });
+```
+
+`page` contains `items`, the whole scoped/unarchived `unreadCount` and `nextBefore`.
+Supply `before: page.nextBefore` for another page. Limits range from 1 to 100.
+The ordering uses descending ULIDs for stable pagination, not a commit-order
+event cursor or snapshot. Refresh the first page to discover new arrivals; counts
+and pages may change as concurrent actions occur.
+
+`view: 'banners'` returns only undismissed/unarchived banner items. All views keep
+the same inbox-wide unread count. Reading a page changes no state. Reading an item
+does not dismiss its banner; dismissal does not mark it read or archive it. Archive
+removes the item from active inbox/banner queries. Repeat state changes preserve the
+first timestamp, except explicitly marking unread clears `readAt`. Rendering clients
+must not replay stored toast items as fresh live alerts when loading an inbox.
+
+Inbox operations require active request authentication. Unknown and foreign item IDs
+produce the same `not_found` error. Hosts should map `InAppError.code` appropriately:
+`invalid` to 400, `unauthenticated` to 401, `forbidden` to 403, `not_found` to 404 and
+`conflict` to 409. Ordinary storage failures should remain server errors.
+
+## Organization and other application scopes
+
+Account ownership is built in. Other scopes fail closed unless configured:
+
+```ts
+const application = new App({
+	inApp: {
+		/** Checks current application membership and restrictions for every operation. */
+		async authorizeScope(userId, scope, operation) {
+			if (operation === 'update' && isReadOnlySession()) return false;
+			if (scope.type === 'account') return true;
+			return scope.type === 'organization' && await isMember(userId, scope.id);
+		},
+	},
+});
+```
+
+The policy functions above are application-owned. The framework invokes the policy
+for `receive`, `read` and `update`. When supplied it also governs account scopes,
+allowing read-only impersonation restrictions. Background producers must supply a
+policy that can check recipients without relying on a logged-in request. Checking
+scope identifiers from headers alone is not authorization.
+
+`InAppRecord` is a persistence model, not an authorized HTTP interface. Do not expose
+its unrestricted query/update APIs to clients. It uses opaque recipient identifiers
+rather than a foreign key to a hard-coded users table; application account-deletion
+and retention workflows must remove the corresponding records. Its table belongs in
+the same transactional database as the configured identity model.
+
+## Committed change notifications
+
+`InAppOptions.onChanged(userId)` is an optional application-owned invalidation
+hook. `send()` calls it for newly created recipients; `update()` calls it after a
+changed row. Reads and deduplicated sends do not trigger it. Surrounding Knex
+transactions/savepoints defer the callback until commit; rollback suppresses it.
+Use the service APIs: direct model writes do not invoke this hook.
+
+```ts
+const application = new App({
+	inApp: {
+		/** Sends an empty signal; the browser reloads its authorized HTTP inbox. */
+		async onChanged(userId) {
+			await application.webSockets.channel(`user:${userId}:notifications`).publish('changed', {});
+		},
+		/** A push failure cannot undo a committed notification. */
+		onDeliveryError() { reportNotificationPushFailure(); },
+	},
+});
+```
+
+`reportNotificationPushFailure` is application-owned logging. Configure the
+WebSocket HTTP receiver and worker publisher for cross-process delivery and register
+a recipient-only channel policy. No WebSocket dependency is enabled automatically.
+The hook is best effort and not a durable outbox. A crash between commit and the
+callback can lose a signal; initial load, reconnect and manual refresh retrieve
+saved inbox state. Callback errors do not reject durable message acceptance.
+
+## Ownership and verification
+
+This service depends on DB/ActiveRecord, Auth and the active App context. Public
+contracts are in `contracts/`; `@db3.ai/app/in-app/contracts` is type-only and can be
+used by browser TypeScript without importing server implementation.
+
+Run `npm run test:service --workspace @db3.ai/app -- in-app` with local test DB
+credentials configured as described in the package README. Tests create and remove
+real disposable databases; missing SQL is a failure, not a skipped pass. They cover
+concurrent retry acceptance, aliases, conflict rollback, outer transaction rollback,
+old transaction snapshots, recipient/scope isolation, state independence and pagination.
+Public changes also require `npm run check --workspace @db3.ai/app` and
+`npm run framework:package:test` for packed runtime and TypeScript consumer checks.
+
+The starter application includes app-owned authenticated HTTP routes, an unread badge,
+paginated inbox, persistent banners and a demo toast. Open the inbox or use Refresh
+to retrieve current state; websocket delivery is not connected to this demo yet.

package/src/in-app/contracts/InAppInbox.ts

@@ -0,0 +1,51 @@
+import type { InAppMessage } from './InAppMessage';
+import type { InAppScope } from './InAppScope';
+
+/** A safe recipient-facing view; internal deduplication hashes are never exposed. */
+export interface InAppItem {
+	id: string;
+	type: string;
+	message: InAppMessage;
+	createdAt: string;
+	readAt: string | null;
+	/** Dismissal hides a banner without removing its inbox item or implying it was read. */
+	dismissedAt: string | null;
+	archivedAt: string | null;
+}
+
+/** Trusted server dispatch metadata. Sending is not a public browser-authorized operation. */
+export interface InAppSendOptions {
+	scope: InAppScope;
+	/** Stable notification type, for example content-plan.ready. */
+	type: string;
+	/** Retry identity, unique within type, scope and recipient. Omit to create a new occurrence. */
+	key?: string;
+}
+
+/** One result per distinct recipient, in first-input order. Empty input returns an empty array. */
+export interface InAppAcceptance {
+	userId: string;
+	id: string;
+	status: 'created' | 'existing';
+}
+
+/** Query for the authenticated user's inbox in one explicit scope. */
+export interface InAppInboxQuery {
+	scope: InAppScope;
+	/** Defaults to 25; maximum 100. */
+	limit?: number;
+	/** ID from nextBefore. Pagination is an inbox position, not a realtime/replay cursor. */
+	before?: string;
+	/** Defaults to inbox; banners excludes dismissed items. All views exclude archived items. */
+	view?: 'inbox' | 'banners';
+}
+
+/** Paginated items and the unread count for the whole unarchived scoped inbox. */
+export interface InAppInboxPage {
+	items: InAppItem[];
+	unreadCount: number;
+	nextBefore: string | null;
+}
+
+/** Explicit independent recipient state transitions. */
+export type InAppTransition = 'read' | 'unread' | 'dismiss' | 'archive';

package/src/in-app/contracts/InAppMessage.ts

@@ -0,0 +1,19 @@
+/** Recipient-facing content stored in an inbox. */
+export interface InAppMessage {
+	title: string;
+	/** Plain-text fallback used by compact, accessibility and non-HTML renderers. */
+	body: string;
+	/**
+	 * Optional rich body authored by trusted application code.
+	 *
+	 * The framework validates and stores this value but does not sanitize it because
+	 * permitted markup is an application policy. Every HTML renderer must sanitize it.
+	 */
+	bodyHtml?: string;
+	/** Defaults to info. Severity does not determine persistence or prominence. */
+	severity?: 'info' | 'success' | 'warning' | 'error';
+	/** Defaults to toast. Every presentation remains in the durable inbox. */
+	presentation?: 'inbox' | 'toast' | 'banner';
+	/** Root-relative or HTTP(S) action; the destination must enforce its own authorization. */
+	action?: { label: string; href: string };
+}

package/src/in-app/contracts/InAppScope.ts

@@ -0,0 +1,12 @@
+/** Explicit account or application-owned scope; tenant scopes require an authorization policy. */
+export type InAppScope = { type: 'account'; id?: never } | { type: string; id: string };
+
+/** Scope policy invoked for recipients and authenticated readers, including state mutations. */
+export interface InAppOptions {
+	/** Best-effort invalidation after committed writes. Failures never undo durable acceptance. */
+	onChanged?: (userId: string) => void | Promise<void>;
+	/** Reports failed invalidations; inbox state remains authoritative. */
+	onDeliveryError?: (error: unknown) => void;
+	/** Non-account scopes fail closed when this policy is absent. Check current membership and write permissions. */
+	authorizeScope?: (userId: string, scope: InAppScope, operation: 'receive' | 'read' | 'update') => boolean | Promise<boolean>;
+}

package/src/in-app/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from './InAppMessage';
+export * from './InAppScope';
+export * from './InAppInbox';

package/src/in-app/examples/sendReportReady.ts

@@ -0,0 +1,14 @@
+import { app } from '@db3.ai/app/server';
+import type { InAppAcceptance, InAppMessage } from '@db3.ai/app/in-app';
+
+/** Sends a code-owned message without notification classes, providers or a template database. */
+export async function sendReportReady(userId: string, reportId: string): Promise<InAppAcceptance[]> {
+	const message: InAppMessage = {
+		title: 'Your report is ready',
+		body: 'Open the report to review your results.',
+		presentation: 'banner',
+		severity: 'success',
+		action: { label: 'View report', href: `/reports/${encodeURIComponent(reportId)}` },
+	};
+	return app().inApp.send(userId, message, { scope: { type: 'account' }, type: 'report.ready', key: reportId });
+}

package/src/in-app/index.ts

@@ -0,0 +1,4 @@
+export * from './contracts';
+export { InApp } from './InApp';
+export { InAppRecord } from './InAppRecord';
+export { InAppError } from './InAppError';

package/src/in-app/validation.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { InAppError } from './InAppError';
+import type * as inbox from './contracts';
+
+const identifier = z.string().min(1).max(255).regex(/^\S+$/u);
+const scopeSchema = z.union([
+	z.object({ type: z.literal('account') }).strict(),
+	z.object({ type: z.string().min(1).max(80).regex(/^[a-zA-Z][a-zA-Z0-9_.-]*$/).refine(value => value !== 'account'), id: identifier }).strict(),
+]);
+const messageSchema = z.object({
+	title: z.string().trim().min(1).max(255),
+	body: z.string().trim().min(1).max(10_000),
+	bodyHtml: z.string().trim().min(1).max(50_000).optional(),
+	severity: z.enum(['info', 'success', 'warning', 'error']).default('info'),
+	presentation: z.enum(['inbox', 'toast', 'banner']).default('toast'),
+	action: z.object({ label: z.string().trim().min(1).max(120), href: z.string().min(1).max(2048).refine(safeAction) }).strict().optional(),
+}).strict();
+const sendSchema = z.object({ scope: scopeSchema, type: z.string().min(1).max(120).regex(/^[a-zA-Z0-9_.-]+$/), key: z.string().min(1).max(255).optional() }).strict();
+const querySchema = z.object({ scope: scopeSchema, limit: z.number().int().min(1).max(100).default(25), before: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/).optional(), view: z.enum(['inbox', 'banners']).default('inbox') }).strict();
+
+/** Accepts local absolute paths and credential-free HTTP(S) URLs, rejecting executable and ambiguous forms. */
+function safeAction(value: string): boolean {
+	if (/[\s\\\u0000-\u001f\u007f]/u.test(value)) return false;
+	if (value.startsWith('/') && !value.startsWith('//')) return true;
+	try {
+		const url = new URL(value);
+		return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password;
+	} catch { return false; }
+}
+
+/** Parses public input without leaking database or recipient information. */
+function parse<T>(schema: z.ZodType<T>, value: unknown): T {
+	const result = schema.safeParse(value);
+	if (!result.success) throw new InAppError('invalid', 'Invalid in-app message input.');
+	return result.data;
+}
+
+/** Copies and validates content before it can be persisted. */
+export function normalizeMessage(value: inbox.InAppMessage): inbox.InAppMessage { return parse(messageSchema, value); }
+/** Validates the explicit dispatch scope, type and retry identity. */
+export function normalizeSend(value: inbox.InAppSendOptions): inbox.InAppSendOptions { return parse(sendSchema, value); }
+/** Validates a scoped inbox query and resolves pagination defaults. */
+export function normalizeQuery(value: inbox.InAppInboxQuery) { return parse(querySchema, value); }
+/** Validates a scope for state-changing operations. */
+export function normalizeScope(value: inbox.InAppScope): inbox.InAppScope { return parse(scopeSchema, value); }
+/** Validates the bounded recipient list and removes repeated identities. */
+export function normalizeRecipients(value: string | readonly string[]): string[] {
+	return [...new Set(parse(z.array(identifier).max(100), typeof value === 'string' ? [value] : value))];
+}