@db3.ai/app 0.1.0-beta.1

package/src/mail/transports/FileMailTransport.ts

@@ -0,0 +1,58 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import {
+	formatMailAddress,
+	mailAddressEmail,
+	type MailDelivery,
+	type MailTransport,
+	type ResolvedMailMessage,
+} from '../Mail.js';
+
+export interface FileMailTransportOptions {
+	directory?: string;
+}
+
+/**
+ * Development mail transport that writes each message to disk.
+ */
+export class FileMailTransport implements MailTransport {
+	private readonly directory: string;
+
+	constructor(options: FileMailTransportOptions = {}) {
+		this.directory = options.directory || join(process.cwd(), 'storage', 'mail');
+	}
+
+	async send(message: ResolvedMailMessage): Promise<MailDelivery> {
+		await mkdir(this.directory, {
+			recursive: true,
+		});
+
+		const id = randomUUID();
+		const createdAt = new Date().toISOString();
+		const fileName = `${createdAt.replace(/[:.]/g, '-')}-${id}.json`;
+		const path = join(this.directory, fileName);
+		const accepted = message.to.map(mailAddressEmail);
+		const payload = {
+			id,
+			createdAt,
+			from: formatMailAddress(message.from),
+			to: message.to.map(formatMailAddress),
+			subject: message.subject,
+			text: message.text ?? null,
+			html: message.html ?? null,
+			headers: message.headers ?? {},
+		};
+
+		await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+
+		return {
+			id,
+			transport: 'file',
+			accepted,
+			rejected: [],
+			path,
+		};
+	}
+}

package/src/mail/transports/MailgunTransport.ts

@@ -0,0 +1,85 @@
+import {
+	formatMailAddress,
+	mailAddressEmail,
+	type MailDelivery,
+	type MailTransport,
+	type ResolvedMailMessage,
+} from '../Mail.js';
+
+export interface MailgunTransportOptions {
+	apiKey: string;
+	domain: string;
+	baseUrl?: string;
+}
+
+export class MailTransportError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'MailTransportError';
+	}
+}
+
+/**
+ * Mailgun API transport.
+ *
+ * This keeps the app-level mail contract separate from the provider-specific
+ * HTTP call, so production can swap providers without touching auth flows.
+ */
+export class MailgunTransport implements MailTransport {
+	private readonly apiKey: string;
+	private readonly domain: string;
+	private readonly baseUrl: string;
+
+	constructor(options: MailgunTransportOptions) {
+		this.apiKey = options.apiKey;
+		this.domain = options.domain;
+		this.baseUrl = options.baseUrl || 'https://api.mailgun.net/v3';
+	}
+
+	async send(message: ResolvedMailMessage): Promise<MailDelivery> {
+		const form = new URLSearchParams();
+
+		form.set('from', formatMailAddress(message.from));
+
+		for (const recipient of message.to) {
+			form.append('to', formatMailAddress(recipient));
+		}
+
+		form.set('subject', message.subject);
+
+		if (message.text) {
+			form.set('text', message.text);
+		}
+
+		if (message.html) {
+			form.set('html', message.html);
+		}
+
+		const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
+			method: 'POST',
+			headers: {
+				authorization: `Basic ${Buffer.from(`api:${this.apiKey}`).toString('base64')}`,
+			},
+			body: form,
+		});
+		const result = await response.json().catch(() => null) as {
+			id?: unknown;
+			message?: unknown;
+		} | null;
+
+		if (!response.ok) {
+			const detail = typeof result?.message === 'string'
+				? result.message
+				: response.statusText;
+
+			throw new MailTransportError(`Mailgun rejected the message: ${detail}`);
+		}
+
+		return {
+			id: typeof result?.id === 'string' ? result.id : '',
+			transport: 'mailgun',
+			accepted: message.to.map(mailAddressEmail),
+			rejected: [],
+		};
+	}
+}

package/src/mail/transports/ResendTransport.ts

@@ -0,0 +1,80 @@
+import {
+	formatMailAddress,
+	mailAddressEmail,
+	type MailDelivery,
+	type MailTransport,
+	type ResolvedMailMessage,
+} from '../Mail.js';
+
+export interface ResendTransportOptions {
+	apiKey: string;
+	baseUrl?: string;
+}
+
+class ResendTransportError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'ResendTransportError';
+	}
+}
+
+/**
+ * Resend API transport.
+ */
+export class ResendTransport implements MailTransport {
+	private readonly apiKey: string;
+	private readonly baseUrl: string;
+
+	constructor(options: ResendTransportOptions) {
+		this.apiKey = options.apiKey;
+		this.baseUrl = (options.baseUrl || 'https://api.resend.com').replace(/\/+$/, '');
+	}
+
+	async send(message: ResolvedMailMessage): Promise<MailDelivery> {
+		const payload: Record<string, unknown> = {
+			from: formatMailAddress(message.from),
+			to: message.to.map(formatMailAddress),
+			subject: message.subject,
+		};
+
+		if (message.text) {
+			payload.text = message.text;
+		}
+
+		if (message.html) {
+			payload.html = message.html;
+		}
+
+		if (message.headers) {
+			payload.headers = message.headers;
+		}
+
+		const response = await fetch(`${this.baseUrl}/emails`, {
+			method: 'POST',
+			headers: {
+				authorization: `Bearer ${this.apiKey}`,
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify(payload),
+		});
+		const result = await response.json().catch(() => null) as {
+			id?: unknown;
+			message?: unknown;
+		} | null;
+
+		if (!response.ok) {
+			const detail = typeof result?.message === 'string'
+				? result.message
+				: response.statusText;
+
+			throw new ResendTransportError(`Resend rejected the message: ${detail}`);
+		}
+
+		return {
+			id: typeof result?.id === 'string' ? result.id : '',
+			transport: 'resend',
+			accepted: message.to.map(mailAddressEmail),
+			rejected: [],
+		};
+	}
+}

package/src/media/MediaFile.ts

@@ -0,0 +1,132 @@
+import { ActiveRecord, type FieldBuilder } from '../db';
+import type { EntityRef } from '../db/fields/LinkField';
+import { MEDIA_FILE_VISIBILITY } from './constants';
+import { MediaLibrary } from './MediaLibrary';
+
+const MEDIA_FILES_LIBRARY_SOURCE_INDEX = 'media_files_library_source_index';
+const MEDIA_FILES_LIBRARY_MIME_INDEX = 'media_files_library_mime_index';
+
+/**
+ * Managed file record for bytes stored through the framework storage service.
+ *
+ * A file can be managed without appearing in a media browser. Browser placement
+ * is represented separately by `MediaItem` rows that point to this file.
+ */
+export class MediaFile extends ActiveRecord {
+	static override table = 'media_files';
+	static override primaryKey = 'id';
+	static override labelFields = ['name', 'mimeType'];
+	static override comment = 'Framework-managed storage file, optionally attached to one or more media browser items.';
+
+	/**
+	 * Defines managed file metadata and storage location fields.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Field definitions for schema generation and value conversion.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable managed file id used by apps and media browser selections.',
+			}),
+
+			library: field.link(() => MediaLibrary, {
+				column: 'library_id',
+				required: true,
+				onDelete: 'CASCADE',
+				index: true,
+				indexes: [
+					{
+						name: MEDIA_FILES_LIBRARY_SOURCE_INDEX,
+						columns: ['library_id', 'source'],
+					},
+					{
+						name: MEDIA_FILES_LIBRARY_MIME_INDEX,
+						columns: ['library_id', 'mime_type'],
+					},
+				],
+				comment: 'Media library that owns this file.',
+			}),
+
+			disk: field.string({
+				required: true,
+				length: 120,
+				maxLength: 120,
+				index: true,
+				comment: 'Configured storage disk that contains the file bytes.',
+			}),
+
+			path: field.string({
+				required: true,
+				length: 2048,
+				maxLength: 2048,
+				comment: 'Storage path relative to the configured disk root.',
+			}),
+
+			name: field.string({
+				required: true,
+				length: 255,
+				maxLength: 255,
+				comment: 'Display filename used by browser rows and downloads.',
+			}),
+
+			mimeType: field.string({
+				column: 'mime_type',
+				required: true,
+				length: 120,
+				maxLength: 120,
+				index: true,
+				comment: 'MIME type recorded when the file was written.',
+			}),
+
+			size: field.integer({
+				required: true,
+				unsigned: true,
+				big: true,
+				comment: 'File size in bytes.',
+			}),
+
+			visibility: field.choice({
+				required: true,
+				choices: Object.values(MEDIA_FILE_VISIBILITY),
+				default: MEDIA_FILE_VISIBILITY.private,
+				comment: 'Storage visibility used when the file was written.',
+			}),
+
+			source: field.string({
+				length: 120,
+				maxLength: 120,
+				index: true,
+				comment: 'Optional app-owned source label such as generated-image, upload, or export.',
+			}),
+
+			meta: field.json<Record<string, unknown>>({
+				column: 'meta_json',
+				comment: 'App-owned non-indexed file metadata such as dimensions, prompts, or provider ids.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				auto: 'update',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare library: EntityRef<MediaLibrary>;
+	declare disk: string | null;
+	declare path: string | null;
+	declare name: string | null;
+	declare mimeType: string | null;
+	declare size: number | null;
+	declare visibility: typeof MEDIA_FILE_VISIBILITY[keyof typeof MEDIA_FILE_VISIBILITY] | null;
+	declare source: string | null;
+	declare meta: Record<string, unknown> | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}

package/src/media/MediaItem.ts

@@ -0,0 +1,132 @@
+import { ActiveRecord, type FieldBuilder } from '../db';
+import type { EntityRef } from '../db/fields/LinkField';
+import { MEDIA_ITEM_TYPE, type MediaItemType } from './constants';
+import { MediaFile } from './MediaFile';
+import { MediaLibrary } from './MediaLibrary';
+
+const MEDIA_ITEMS_LIBRARY_PATH_UNIQUE = 'media_items_library_path_unique';
+const MEDIA_ITEMS_LIBRARY_PARENT_INDEX = 'media_items_library_parent_index';
+const MEDIA_ITEMS_LIBRARY_TYPE_INDEX = 'media_items_library_type_index';
+
+/**
+ * Folder-tree row used by media browser surfaces.
+ *
+ * Files can exist without media items. A `file` media item is only created when
+ * the managed file should be visible inside a library browser.
+ */
+export class MediaItem extends ActiveRecord {
+	static override table = 'media_items';
+	static override primaryKey = 'id';
+	static override labelFields = ['name', 'type'];
+	static override comment = 'Browser-visible media folder or file placement inside a scoped media library.';
+
+	/**
+	 * Defines media browser tree fields and library-scoped path indexes.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Field definitions for schema generation and value conversion.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable media browser item id.',
+			}),
+
+			library: field.link(() => MediaLibrary, {
+				column: 'library_id',
+				required: true,
+				onDelete: 'CASCADE',
+				index: true,
+				indexes: [
+					{
+						name: MEDIA_ITEMS_LIBRARY_PATH_UNIQUE,
+						columns: ['library_id', 'path'],
+						unique: true,
+					},
+					{
+						name: MEDIA_ITEMS_LIBRARY_PARENT_INDEX,
+						columns: ['library_id', 'parent_id'],
+					},
+					{
+						name: MEDIA_ITEMS_LIBRARY_TYPE_INDEX,
+						columns: ['library_id', 'type'],
+					},
+				],
+				comment: 'Media library that owns this browser item.',
+			}),
+
+			type: field.choice({
+				required: true,
+				choices: Object.values(MEDIA_ITEM_TYPE),
+				length: 20,
+				maxLength: 20,
+				comment: 'Browser item type: root, dir, or file.',
+			}),
+
+			root: field.link(() => MediaItem, {
+				column: 'root_id',
+				required: false,
+				onDelete: 'CASCADE',
+				index: true,
+				comment: 'Root item for this tree. Root rows leave this empty.',
+			}),
+
+			parent: field.link(() => MediaItem, {
+				column: 'parent_id',
+				required: false,
+				onDelete: 'CASCADE',
+				index: true,
+				comment: 'Parent folder item. Root rows leave this empty.',
+			}),
+
+			file: field.link(() => MediaFile, {
+				column: 'file_id',
+				required: false,
+				onDelete: 'CASCADE',
+				index: true,
+				comment: 'Managed file shown by this item when type is file.',
+			}),
+
+			name: field.string({
+				required: true,
+				length: 255,
+				maxLength: 255,
+				comment: 'Display name rendered in media browser rows.',
+			}),
+
+			path: field.string({
+				required: true,
+				length: 2048,
+				maxLength: 2048,
+				comment: 'Slash-prefixed browser path unique within the media library.',
+			}),
+
+			meta: field.json<Record<string, unknown>>({
+				column: 'meta_json',
+				comment: 'App-owned non-indexed browser item metadata.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				auto: 'update',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare library: EntityRef<MediaLibrary>;
+	declare type: MediaItemType | null;
+	declare root: EntityRef<MediaItem> | null;
+	declare parent: EntityRef<MediaItem> | null;
+	declare file: EntityRef<MediaFile> | null;
+	declare name: string | null;
+	declare path: string | null;
+	declare meta: Record<string, unknown> | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}

package/src/media/MediaLibrary.ts

@@ -0,0 +1,117 @@
+import { ActiveRecord, type FieldBuilder } from '../db';
+import { MEDIA_LIBRARY_DEFAULT_KEY } from './constants';
+
+const MEDIA_LIBRARY_SCOPE_KEY_UNIQUE = 'media_libraries_scope_key_unique';
+const MEDIA_LIBRARY_SCOPE_INDEX = 'media_libraries_scope_index';
+
+/**
+ * Scoped namespace for managed files and browser-visible media items.
+ *
+ * Apps use `scopeType`, `scopeId`, and `key` to map their own ownership model
+ * onto the framework media tables without adding app-specific columns such as
+ * `website_id` or `organization_id`.
+ */
+export class MediaLibrary extends ActiveRecord {
+	static override table = 'media_libraries';
+	static override primaryKey = 'id';
+	static override labelFields = ['name', 'key'];
+	static override comment = 'Scoped namespace for framework-managed files and optional media-browser trees.';
+
+	/**
+	 * Defines the media library schema and scope identity indexes.
+	 *
+	 * @param field - ActiveRecord field builder.
+	 * @returns Field definitions for schema generation and value conversion.
+	 */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid({
+				comment: 'Stable media library id.',
+			}),
+
+			scopeType: field.string({
+				column: 'scope_type',
+				required: true,
+				length: 120,
+				maxLength: 120,
+				index: true,
+				indexes: [
+					{
+						name: MEDIA_LIBRARY_SCOPE_KEY_UNIQUE,
+						columns: ['scope_type', 'scope_id', 'library_key'],
+						unique: true,
+					},
+					{
+						name: MEDIA_LIBRARY_SCOPE_INDEX,
+						columns: ['scope_type', 'scope_id'],
+					},
+				],
+				comment: 'Application-owned scope type, for example app.website or app.organization.',
+			}),
+
+			scopeId: field.string({
+				column: 'scope_id',
+				required: true,
+				length: 120,
+				maxLength: 120,
+				comment: 'Application-owned scope id. The media package treats this as an opaque string.',
+			}),
+
+			key: field.string({
+				column: 'library_key',
+				required: true,
+				default: MEDIA_LIBRARY_DEFAULT_KEY,
+				length: 80,
+				maxLength: 80,
+				comment: 'Scope-local library key, such as default, generated-images, or reference-material.',
+			}),
+
+			name: field.string({
+				required: true,
+				length: 255,
+				maxLength: 255,
+				comment: 'Human-readable library name for administration and browser headings.',
+			}),
+
+			defaultDisk: field.string({
+				column: 'default_disk',
+				length: 120,
+				maxLength: 120,
+				comment: 'Optional storage disk used when callers do not choose a disk for new files.',
+			}),
+
+			pathPrefix: field.string({
+				column: 'path_prefix',
+				length: 1024,
+				maxLength: 1024,
+				comment: 'Optional storage path prefix used for files written into this library.',
+			}),
+
+			meta: field.json<Record<string, unknown>>({
+				column: 'meta_json',
+				comment: 'App-owned non-indexed library metadata.',
+			}),
+
+			createdAt: field.timestamp({
+				column: 'created_at',
+				auto: 'create',
+			}),
+
+			updatedAt: field.timestamp({
+				column: 'updated_at',
+				auto: 'update',
+			}),
+		};
+	}
+
+	declare id: string | null;
+	declare scopeType: string | null;
+	declare scopeId: string | null;
+	declare key: string | null;
+	declare name: string | null;
+	declare defaultDisk: string | null;
+	declare pathPrefix: string | null;
+	declare meta: Record<string, unknown> | null;
+	declare createdAt: Date | null;
+	declare updatedAt: Date | null;
+}