@db3.ai/app 0.1.0-beta.1

package/src/logging/examples/runNoteLogs.ts

@@ -0,0 +1,38 @@
+import { Writable } from 'node:stream';
+import { pathToFileURL } from 'node:url';
+import { Log, PinoLoggerDriver } from '@db3.ai/app/logging';
+
+/**
+ * Captures real structured logs and demonstrates child context and redaction.
+ *
+ * @returns Parsed records without unstable process/time fields for readable output.
+ */
+export async function runNoteLogs() {
+	const chunks: string[] = [];
+	const destination = new Writable({
+		/** Captures complete Pino output using a real writable stream. */
+		write(chunk, _encoding, callback) { chunks.push(chunk.toString()); callback(); },
+	});
+	const log = new Log({ driver: new PinoLoggerDriver({ level: 'info', environment: 'test', source: 'notes', console: false, devtools: false, redact: ['integration.apiKey'] }, destination) });
+	try {
+		const request = log.child({ requestId: 'request-1', ownerId: 'ada' });
+		request.debug('Filtered diagnostic');
+		request.info({ noteId: 'one', password: 'test-password', integration: { apiKey: 'test-provider-key' } }, 'Note saved');
+		request.error({ err: new Error('Summary unavailable'), token: 'test-token' }, 'Summary failed');
+		log.level = 'debug';
+		log.debug({ component: 'notes' }, 'Diagnostics enabled');
+		log.level = 'silent';
+		log.error('Filtered after disabling');
+		await log.flush();
+		return chunks.join('').trim().split('\n').map(line => {
+			const { time, pid, hostname, ...record } = JSON.parse(line);
+			if (record.err) delete record.err.stack;
+			return record;
+		});
+	} finally {
+		await log.close();
+		destination.end();
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runNoteLogs(), null, 2));

package/src/logging/index.ts

@@ -0,0 +1,3 @@
+export * from './contracts';
+export * from './drivers';
+export * from './Log';

package/src/logging/transports/DevtoolsLogTransport.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import build from 'pino-abstract-transport';
+import type { Transform } from 'node:stream';
+
+import type * as logging from '../contracts/index.js';
+
+interface PinoLogRecord extends Record<string, unknown> {
+	level?: unknown;
+	msg?: unknown;
+	source?: unknown;
+	time?: unknown;
+}
+
+/**
+ * Log event accepted by the Platform development event service.
+ */
+export interface DevtoolsLogEvent extends Record<string, unknown> {
+	type: 'log';
+	id: string;
+	source: string;
+	timestamp: string;
+	level: Exclude<logging.LogLevel, 'silent'>;
+	numericLevel: number;
+	message: string;
+}
+
+const levelLabels = new Map<number, DevtoolsLogEvent['level']>([
+	[10, 'trace'],
+	[20, 'debug'],
+	[30, 'info'],
+	[40, 'warn'],
+	[50, 'error'],
+	[60, 'fatal'],
+]);
+
+/**
+ * Creates the worker-thread transport that streams Pino records to devtools.
+ *
+ * @param options - Structured-clone-safe HTTP transport configuration.
+ * @returns Writable Pino transport stream.
+ */
+export default async function createDevtoolsLogTransport(
+	options: logging.DevtoolsLogOptions = {},
+): Promise<Transform> {
+	const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+	const dispatcherModule = await import(
+		`../../devtools/HttpEventDispatcher.${extension}`
+	) as typeof import('../../devtools/HttpEventDispatcher');
+	const { createHttpEventDispatcher } = dispatcherModule;
+	const dispatch = createHttpEventDispatcher<DevtoolsLogEvent>(options);
+
+	return build(async (source) => {
+		for await (const input of source) {
+			if (!isRecord(input)) continue;
+
+			dispatch(pinoRecordToDevtoolsEvent(input));
+		}
+	}, {
+		close: async () => {
+			await dispatch.close();
+		},
+	});
+}
+
+/**
+ * Converts one Pino JSON object into the shared development event envelope.
+ *
+ * @param record - Structured record parsed by the Pino transport.
+ * @returns Normalized log event for storage and live streaming.
+ */
+export function pinoRecordToDevtoolsEvent(
+	record: PinoLogRecord,
+): DevtoolsLogEvent {
+	const numericLevel = numericValue(record.level, 30);
+	const {
+		level: _level,
+		msg: _message,
+		source: _source,
+		time: _time,
+		...context
+	} = record;
+
+	return {
+		...context,
+		type: 'log',
+		id: randomUUID(),
+		source: stringValue(record.source, 'app'),
+		timestamp: timestampValue(record.time),
+		level: levelLabels.get(numericLevel) ?? 'info',
+		numericLevel,
+		message: stringValue(record.msg, ''),
+	};
+}
+
+/**
+ * Checks whether an unknown transport value is an object record.
+ *
+ * @param input - Parsed transport value.
+ * @returns True when the value can be normalized as a log record.
+ */
+function isRecord(input: unknown): input is PinoLogRecord {
+	return Boolean(input) && typeof input === 'object' && !Array.isArray(input);
+}
+
+/**
+ * Returns a finite number or a fallback.
+ *
+ * @param input - Candidate numeric field.
+ * @param fallback - Value used when conversion fails.
+ * @returns Finite numeric value.
+ */
+function numericValue(input: unknown, fallback: number): number {
+	const value = Number(input);
+
+	return Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * Returns a non-empty string or a fallback.
+ *
+ * @param input - Candidate string field.
+ * @param fallback - Value used when the field is empty.
+ * @returns Normalized string.
+ */
+function stringValue(input: unknown, fallback: string): string {
+	return typeof input === 'string' && input.trim() ? input : fallback;
+}
+
+/**
+ * Converts a Pino epoch timestamp into the panel's ISO representation.
+ *
+ * @param input - Pino time field.
+ * @returns Valid ISO timestamp.
+ */
+function timestampValue(input: unknown): string {
+	const milliseconds = numericValue(input, Date.now());
+	const date = new Date(milliseconds);
+
+	return Number.isNaN(date.getTime())
+		? new Date().toISOString()
+		: date.toISOString();
+}

package/src/mail/Mail.ts

@@ -0,0 +1,188 @@
+import {
+	FileMailTransport,
+	type FileMailTransportOptions,
+} from './transports/FileMailTransport.js';
+import {
+	MailgunTransport,
+	type MailgunTransportOptions,
+} from './transports/MailgunTransport.js';
+import {
+	ResendTransport,
+	type ResendTransportOptions,
+} from './transports/ResendTransport.js';
+
+/** Recipient or sender as an address string or an email plus display name. */
+export type MailAddress = string | {
+	email: string;
+	name?: string;
+};
+
+/** Application-owned message; templates and recipient authorization stay in the app. */
+export interface MailMessage {
+	to: MailAddress | MailAddress[];
+	from?: MailAddress;
+	subject: string;
+	text?: string;
+	html?: string;
+	/** Extra message headers; File and Resend preserve them, Mailgun currently does not. */
+	headers?: Record<string, string>;
+}
+
+/** Transport input with a default sender resolved and recipients normalized to an array. */
+export interface ResolvedMailMessage extends Omit<MailMessage, 'from' | 'to'> {
+	from: MailAddress;
+	to: MailAddress[];
+}
+
+/** Provider acceptance or a local file write, not proof of inbox delivery. */
+export interface MailDelivery {
+	id: string;
+	transport: string;
+	accepted: string[];
+	rejected: string[];
+	/** Local JSON preview path when using the file transport. */
+	path?: string;
+}
+
+/** Provider boundary; sending rejects on transport failure and never retries automatically. */
+export interface MailTransport {
+	/** Submits one normalized message to the selected transport. */
+	send(message: ResolvedMailMessage): Promise<MailDelivery>;
+}
+
+/** Sender defaults and the explicitly selected transport for one Mail instance. */
+export interface MailOptions {
+	from?: MailAddress;
+	transport?: MailTransport;
+}
+
+/** Application fallback sender, overridden by MAIL_FROM when present. */
+export interface MailEnvOptions {
+	from?: MailAddress;
+}
+
+const defaultMailFrom = 'Platform <no-reply@platform.local>';
+
+/** Normalizes messages and delegates immediate delivery to one transport. */
+export class Mail {
+	private readonly from: MailAddress;
+	private readonly transport: MailTransport;
+
+	/** Creates a mail service; absent transport selects local file previews. */
+	constructor(options: MailOptions = {}) {
+		this.from = options.from ?? defaultMailFrom;
+		this.transport = options.transport ?? new FileMailTransport();
+	}
+
+	/** Validates message presence and sends once; apps own retries and recipient policy. */
+	async send(message: MailMessage): Promise<MailDelivery> {
+		const resolved = this.resolveMessage(message);
+
+		return this.transport.send(resolved);
+	}
+
+	/** Resolves the sender and recipient list without changing application content. */
+	private resolveMessage(message: MailMessage): ResolvedMailMessage {
+		const to = Array.isArray(message.to) ? message.to : [message.to];
+
+		if (to.length === 0) {
+			throw new Error('Mail requires at least one recipient.');
+		}
+
+		if (!message.text && !message.html) {
+			throw new Error('Mail requires text or html content.');
+		}
+
+		return {
+			...message,
+			from: message.from ?? this.from,
+			to,
+		};
+	}
+}
+
+/** Builds a shared Mail instance from an explicit environment or process.env. */
+export function createMailFromEnv(
+	env: NodeJS.ProcessEnv = process.env,
+	options: MailEnvOptions = {},
+): Mail {
+	return new Mail({
+		from: env.MAIL_FROM || options.from || defaultMailFrom,
+		transport: createMailTransportFromEnv(env),
+	});
+}
+
+/** Selects the transport; missing or unrecognized names currently fall back to file. */
+export function createMailTransportFromEnv(
+	env: NodeJS.ProcessEnv = process.env,
+): MailTransport {
+	const transport = (env.MAIL_TRANSPORT || env.MAIL_MAILER || 'file').toLowerCase();
+
+	if (transport === 'mailgun') {
+		return new MailgunTransport(mailgunOptionsFromEnv(env));
+	}
+
+	if (transport === 'resend') {
+		return new ResendTransport(resendOptionsFromEnv(env));
+	}
+
+	return new FileMailTransport(fileOptionsFromEnv(env));
+}
+
+/** Reads the application-owned directory for plaintext development previews. */
+function fileOptionsFromEnv(env: NodeJS.ProcessEnv): FileMailTransportOptions {
+	return {
+		directory: env.MAIL_FILE_DIRECTORY,
+	};
+}
+
+/** Requires both Mailgun credentials before constructing the HTTP transport. */
+function mailgunOptionsFromEnv(env: NodeJS.ProcessEnv): MailgunTransportOptions {
+	if (!env.MAILGUN_API_KEY || !env.MAILGUN_DOMAIN) {
+		throw new Error('MAILGUN_API_KEY and MAILGUN_DOMAIN are required for mailgun transport.');
+	}
+
+	return {
+		apiKey: env.MAILGUN_API_KEY,
+		domain: env.MAILGUN_DOMAIN,
+		baseUrl: env.MAILGUN_BASE_URL,
+	};
+}
+
+/** Requires Resend credentials before constructing the HTTP transport. */
+function resendOptionsFromEnv(env: NodeJS.ProcessEnv): ResendTransportOptions {
+	if (!env.RESEND_API_KEY) {
+		throw new Error('RESEND_API_KEY is required for resend transport.');
+	}
+
+	return {
+		apiKey: env.RESEND_API_KEY,
+		baseUrl: env.RESEND_BASE_URL,
+	};
+}
+
+/** Formats an address for transport use; this is not validation or header sanitization. */
+export function formatMailAddress(address: MailAddress): string {
+	if (typeof address === 'string') {
+		return address;
+	}
+
+	if (!address.name) {
+		return address.email;
+	}
+
+	const escapedName = address.name.replace(/"/g, '\\"');
+
+	return `"${escapedName}" <${address.email}>`;
+}
+
+/** Extracts the address portion for acceptance metadata; does not validate deliverability. */
+export function mailAddressEmail(address: MailAddress): string {
+	if (typeof address === 'string') {
+		const match = address.match(/<([^>]+)>/);
+
+		return (match?.[1] || address).trim();
+	}
+
+	return address.email;
+}

package/src/mail/README.md

@@ -0,0 +1,206 @@
+# Mail
+
+`@db3.ai/app/mail` provides a small provider-independent boundary for
+outbound application email. It checks that recipients and body content are present, resolves
+a default sender, and delegates delivery to an injectable `MailTransport`.
+
+The service owns message normalization and the built-in file, Mailgun, and
+Resend transports. Applications own templates, localization, recipient policy,
+queueing, and deciding which business event should send a message. Sending is
+immediate; use the Queue service when delivery must be durable or retried.
+
+## Run a welcome email without sending it
+
+Install the package using the [installation guide](https://db3.ai/docs/installation). During the unpublished preview, use matching App and Pure tarballs. Then copy the installed examples:
+
+```sh
+npm install --save-dev tsx typescript @types/node vitest
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/mail/examples/. examples/
+npx tsx examples/runMailPreview.ts
+```
+
+The command uses a real `FileMailTransport` in its own temporary directory. It rejects an empty recipient list, writes one welcome message for `ada@example.test`, reads it back and removes only that directory in `finally`. It makes no network requests, even if provider credentials exist in your environment.
+
+Expect `transport: "file"`, `files: 1`, `rejectedEmptyRecipients: true` and the subject `Welcome to your notes`. The HTML body contains `Ada & team`; the text body keeps `Ada & team`.
+
+[`welcomeMessage.ts`](./examples/welcomeMessage.ts) owns application input validation and HTML text escaping. `Mail` does not validate email addresses, sanitize headers, or escape your HTML. Escape values for the context where they are inserted; HTML text escaping is not URL validation or a general HTML sanitizer. Do not expose an unrestricted public send-mail endpoint.
+
+The complete [Mail walkthrough](https://db3.ai/docs/mail) includes both source files and the copyable consumer test. Copy its test into `tests/mail/runMailPreview.test.ts`, then run:
+
+```sh
+npx vitest run tests/mail/runMailPreview.test.ts
+npx tsc --noEmit --module ESNext --moduleResolution Bundler --target es2022 --types node --skipLibCheck examples/*.ts
+```
+
+Those tests use real file delivery and real Mail/Resend components with only the external `fetch` boundary replaced. They cover template validation, missing credentials, rejection before sending, provider failure and explicit retry. No live email delivery is claimed.
+
+## Module Ownership
+
+Mail is a service-owned module inside `packages/app`:
+
+```text
+mail/
+	Mail.ts
+	transports/
+	tests/
+	index.ts
+	README.md
+```
+
+The module has no dependency on the framework `App`. Applications may construct
+one `Mail` instance directly or expose it from their own `App` subclass through
+the normal `service(...)` cache. The HTTP transports depend only on the runtime
+`fetch` API, while the file transport uses the local filesystem.
+
+## Public API
+
+Import supported APIs from the package subpath:
+
+```ts
+import { Mail, createMailFromEnv, type MailDelivery, type MailMessage, type MailTransport } from '@db3.ai/app/mail';
+```
+
+The public surface includes:
+
+- `Mail`, which resolves and sends `MailMessage` values.
+- `MailAddress`, accepting either an address string or an `{ email, name }`
+  object.
+- `MailTransport`, the provider boundary applications can implement.
+- `MailDelivery`, the normalized result returned after a successful send.
+- `createMailFromEnv(...)` and `createMailTransportFromEnv(...)`, which apply
+  the framework environment-variable convention.
+- `FileMailTransport`, `MailgunTransport`, and `ResendTransport`.
+- `formatMailAddress(...)` and `mailAddressEmail(...)` for transport authors.
+
+`ResolvedMailMessage` is the transport-facing shape. It always contains a
+resolved sender and an array of recipients, so custom transports do not need to
+repeat that normalization.
+
+## Configuration
+
+`createMailFromEnv()` recognizes these common variables:
+
+```env
+MAIL_TRANSPORT=file
+MAIL_FROM="Example App <no-reply@example.com>"
+MAIL_FILE_DIRECTORY=storage/mail
+```
+
+`MAIL_TRANSPORT` supports `file`, `mailgun`, or `resend`. `MAIL_MAILER` is
+accepted as a legacy fallback when `MAIL_TRANSPORT` is absent. An absent or
+unrecognized value selects the file transport, keeping local development from
+accidentally sending external email.
+
+In production, validate `MAIL_TRANSPORT` against an explicit allowlist before constructing Mail. A typo otherwise selects file delivery and can look like a successful send. File messages are plaintext: keep the directory outside public storage, restrict access and set your own retention policy.
+
+Mailgun requires:
+
+```env
+MAIL_TRANSPORT=mailgun
+MAILGUN_API_KEY=key-example
+MAILGUN_DOMAIN=mg.example.com
+MAILGUN_BASE_URL=https://api.mailgun.net/v3
+```
+
+Resend requires:
+
+```env
+MAIL_TRANSPORT=resend
+RESEND_API_KEY=re_example
+RESEND_BASE_URL=https://api.resend.com
+```
+
+The base URL variables are optional and primarily useful for compatible
+gateways and controlled tests. Credentials belong in the application's secret
+store or deployment environment, never in committed configuration.
+
+## Normal Workflows
+
+Create one shared mail service during application boot:
+
+```ts
+import { createMailFromEnv } from '@db3.ai/app/mail';
+
+const mail = createMailFromEnv(process.env, {
+	from: 'Example App <no-reply@example.com>',
+});
+```
+
+Send text, HTML, or both:
+
+```ts
+const delivery = await mail.send({
+	to: {
+		email: user.email,
+		name: user.name,
+	},
+	subject: 'Reset your password',
+	text: `Open ${resetUrl} to reset your password.`,
+	html: `<p>Open <a href="${resetUrl}">this reset link</a>.</p>`,
+});
+```
+
+The returned `MailDelivery` contains the provider message id, transport name,
+normalized accepted and rejected address lists, and the written path for file
+deliveries.
+
+Applications can inject a transport explicitly. This is the preferred seam for
+application tests and provider extensions:
+
+```ts
+const mail = new Mail({
+	from: 'Example App <no-reply@example.com>',
+	transport: new ApplicationMailTransport(),
+});
+```
+
+The file transport writes one readable JSON record per message. It is the
+default transport and is suitable for local inspection without contacting an
+external provider.
+
+## Errors And Failure Behaviour
+
+`Mail.send(...)` rejects before invoking the transport when the recipient array
+is empty or when neither `text` nor `html` content is present. A message-level
+`from` value overrides the service default.
+
+Environment construction fails immediately when the selected provider is
+missing required credentials. Mailgun and Resend reject non-successful HTTP
+responses with a provider-specific error message, while network failures
+propagate to the caller. Invalid JSON falls back to the HTTP status text for a
+rejection and an empty provider id for a successful response. A successful HTTP
+response currently reports all submitted recipients as accepted because the
+provider APIs used here do not return per-recipient status in this boundary.
+
+The framework does not retry a failed send or persist an outbox. Dispatch a
+dedicated queued job when the application needs retry policy, idempotency, or
+delivery that survives process shutdown.
+
+Queue retry alone does not prevent duplicate email. A timeout can follow provider acceptance. These built-in HTTP transports do not expose provider idempotency keys or an outbox transaction; a message header is not an API idempotency key. Make that business decision explicitly.
+
+`accepted` means transport/provider acceptance, not inbox delivery. The built-ins have no attachments, CC/BCC, delivery tracking, scheduled sending or explicit request timeout. File and Resend preserve custom `headers`; Mailgun currently does not forward them. `App` has no built-in `mail` getter, and Mail has no close method. Own any resources introduced by your custom transport.
+
+The [full API reference](https://db3.ai/docs/mail-api) is generated from the shipped declarations for Mail and all three transports.
+
+## Testing And Verification
+
+The service-owned behaviour tests exercise file output, message validation,
+environment selection, Resend request formatting, and provider rejection:
+
+```sh
+npm run test:service --workspace packages/app -- mail
+```
+
+Run the complete framework suite and source checks before publishing a change:
+
+```sh
+npm test --workspace packages/app
+npm run check --workspace packages/app
+```
+
+External mail APIs are controlled through the injectable transport or a stubbed
+`fetch` boundary. Tests must not send live email. Relevant implementation lives
+in [`Mail.ts`](./Mail.ts) and [`transports/`](./transports). Behavioural tests
+live at `packages/app/src/mail/tests/` in the source repository and are not
+included in the installed runtime package.

package/src/mail/examples/runMailPreview.ts

@@ -0,0 +1,44 @@
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { FileMailTransport, Mail } from '@db3.ai/app/mail';
+import { welcomeMessage } from './welcomeMessage';
+
+/**
+ * Writes, reads and removes a local welcome-email preview without sending email.
+ *
+ * @returns Selected message contents and the observed validation/recovery outcome.
+ */
+export async function runMailPreview() {
+	const directory = await mkdtemp(join(tmpdir(), 'db3-mail-guide-'));
+	try {
+		const mail = new Mail({ from: 'Notes <hello@example.test>', transport: new FileMailTransport({ directory }) });
+		let rejectedEmptyRecipients = false;
+		try {
+			await mail.send({ to: [], subject: 'Invalid', text: 'This should not be written.' });
+		} catch (error) {
+			if (!(error instanceof Error) || error.message !== 'Mail requires at least one recipient.') throw error;
+			rejectedEmptyRecipients = true;
+		}
+		const delivery = await mail.send(welcomeMessage('ada@example.test', 'Ada & team'));
+		if (!delivery.path) throw new Error('The file transport did not return a preview path.');
+		const preview = JSON.parse(await readFile(delivery.path, 'utf8'));
+		return {
+			transport: delivery.transport,
+			accepted: delivery.accepted,
+			rejectedEmptyRecipients,
+			files: (await readdir(directory)).length,
+			from: preview.from,
+			subject: preview.subject,
+			text: preview.text,
+			html: preview.html,
+		};
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	console.log(JSON.stringify(await runMailPreview(), null, 2));
+}

package/src/mail/examples/welcomeMessage.ts

@@ -0,0 +1,26 @@
+import type { MailMessage } from '@db3.ai/app/mail';
+import { isEmail } from '@db3.ai/app/validation';
+
+/**
+ * Builds an application-owned welcome message with safe plain text and HTML.
+ *
+ * @param email - Recipient selected by the application, not an arbitrary send API.
+ * @param name - Display name rendered as text, never trusted HTML.
+ * @returns Message ready for any supported mail transport.
+ */
+export function welcomeMessage(email: string, name: string): MailMessage {
+	if (!isEmail(email)) throw new Error('A valid recipient email is required.');
+	const displayName = name.trim();
+	if (!displayName || displayName.length > 80 || /[\r\n]/.test(displayName)) throw new Error('Name must be 1–80 characters without line breaks.');
+	return {
+		to: { email, name: displayName },
+		subject: 'Welcome to your notes',
+		text: `Hello ${displayName}, your notebook is ready.`,
+		html: `<p>Hello ${escapeHtml(displayName)}, your notebook is ready.</p>`,
+	};
+}
+
+/** Escapes user-controlled text for an HTML text node, not a URL or script. */
+function escapeHtml(value: string): string {
+	return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+}

package/src/mail/index.ts

@@ -0,0 +1,4 @@
+export * from './Mail.js';
+export * from './transports/FileMailTransport.js';
+export * from './transports/MailgunTransport.js';
+export * from './transports/ResendTransport.js';