@db3.ai/app 0.1.0-beta.1

package/dist/logging/contracts/LoggingOptions.d.ts

@@ -0,0 +1,49 @@
+import type { LoggerDriver } from './LoggerDriver.js';
+import type { LogBindings, LogLevel } from './Logger.js';
+/**
+ * HTTP delivery settings for the Platform development log transport.
+ */
+export interface DevtoolsLogOptions {
+    /** Explicit event ingestion endpoint, overriding devtools environment values. */
+    url?: string;
+    /** Maximum log records sent in one HTTP request. */
+    batchSize?: number;
+    /** Maximum delay before a partial log batch is sent. */
+    flushIntervalMs?: number;
+    /** Pause before later records are attempted after a failed request. */
+    retryAfterMs?: number;
+    /** Maximum duration allowed for one ingestion request. */
+    requestTimeoutMs?: number;
+    /** Maximum unsent records retained before the oldest record is discarded. */
+    maxPendingEvents?: number;
+    /** Additional ingestion headers, such as a future service token. */
+    headers?: Record<string, string>;
+}
+/**
+ * Application logging configuration.
+ */
+export interface LoggingOptions {
+    /** Injectable logging driver used by tests or alternate implementations. */
+    driver?: LoggerDriver;
+    /** Minimum emitted severity. Defaults to info, or silent in tests. */
+    level?: LogLevel;
+    /** Human-readable application or process name attached to every record. */
+    source?: string;
+    /** Runtime environment copied onto every record. */
+    environment?: string;
+    /** Disables all logging when false. */
+    enabled?: boolean;
+    /** Stable fields attached to every root logger record. */
+    bindings?: LogBindings;
+    /** Sensitive field paths removed before records reach any destination. */
+    redact?: false | string[];
+    /** Writes newline-delimited JSON to standard output. Defaults to true. */
+    console?: boolean;
+    /**
+     * Streams logs to Platform devtools.
+     *
+     * Interactive development enables this automatically. Pass false to opt out
+     * or an options object to configure delivery explicitly.
+     */
+    devtools?: boolean | DevtoolsLogOptions;
+}

package/dist/logging/contracts/LoggingOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/logging/contracts/index.d.ts

@@ -0,0 +1,4 @@
+export * from './HttpExchange.js';
+export * from './Logger.js';
+export * from './LoggerDriver.js';
+export * from './LoggingOptions.js';

package/dist/logging/contracts/index.js

@@ -0,0 +1,4 @@
+export * from './HttpExchange.js';
+export * from './Logger.js';
+export * from './LoggerDriver.js';
+export * from './LoggingOptions.js';

package/dist/logging/drivers/PinoLoggerDriver.d.ts

@@ -0,0 +1,24 @@
+import { type DestinationStream, type Logger as PinoLogger } from 'pino';
+import type * as logging from '../contracts/index.js';
+/**
+ * Pino-backed logger driver with optional worker-thread devtools delivery.
+ */
+export declare class PinoLoggerDriver implements logging.LoggerDriver {
+    #private;
+    readonly logger: PinoLogger;
+    /**
+     * Creates a Pino logger and its configured destinations.
+     *
+     * @param options - Framework logging configuration.
+     * @param destination - Optional direct destination used by focused tests.
+     */
+    constructor(options?: logging.LoggingOptions, destination?: DestinationStream);
+    /**
+     * Waits until Pino has handed accepted records to its destination.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes records and closes the worker transport when one is active.
+     */
+    close(): Promise<void>;
+}

package/dist/logging/drivers/PinoLoggerDriver.js

@@ -0,0 +1,291 @@
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { hostname } from 'node:os';
+import pino from 'pino';
+import { isInteractiveDevelopmentEnvironment } from '../../devtools/index.js';
+const defaultRedactions = [
+    'password',
+    '*.password',
+    'secret',
+    '*.secret',
+    'token',
+    '*.token',
+    'authorization',
+    'headers.authorization',
+    'headers.cookie',
+    'req.headers.authorization',
+    'req.headers.cookie',
+    'request.headers.authorization',
+    'request.headers.cookie',
+];
+/**
+ * Pino-backed logger driver with optional worker-thread devtools delivery.
+ */
+export class PinoLoggerDriver {
+    logger;
+    #transport;
+    #closed = false;
+    #closing = false;
+    #closePromise = null;
+    /**
+     * Creates a Pino logger and its configured destinations.
+     *
+     * @param options - Framework logging configuration.
+     * @param destination - Optional direct destination used by focused tests.
+     */
+    constructor(options = {}, destination) {
+        const environment = options.environment ?? process.env.NODE_ENV ?? 'development';
+        const level = resolveLogLevel(options, process.env);
+        const source = options.source
+            ?? process.env.PLATFORM_LOG_SOURCE
+            ?? process.env.npm_package_name
+            ?? 'app';
+        const pinoOptions = {
+            level,
+            base: {
+                pid: process.pid,
+                hostname: hostname(),
+                source,
+                environment,
+                ...options.bindings,
+            },
+            redact: options.redact === false
+                ? undefined
+                : {
+                    paths: [...defaultRedactions, ...(options.redact ?? [])],
+                    remove: true,
+                },
+        };
+        if (destination) {
+            this.#transport = null;
+            this.logger = pino(pinoOptions, destination);
+            return;
+        }
+        const targets = transportTargets(options, level, environment, process.env);
+        if (targets.length === 0) {
+            this.#transport = null;
+            this.logger = pino({
+                ...pinoOptions,
+                level: 'silent',
+            });
+            return;
+        }
+        if (targets.length === 1 && targets[0]?.target === 'pino/file') {
+            this.#transport = null;
+            this.logger = pino(pinoOptions);
+            return;
+        }
+        this.#transport = pino.transport({
+            targets,
+        });
+        this.#transport.on('error', reportTransportError);
+        this.logger = pino(pinoOptions, this.#transport);
+    }
+    /**
+     * Waits until Pino has handed accepted records to its destination.
+     */
+    async flush() {
+        if (this.#closed)
+            return;
+        this.#transport?.ref();
+        try {
+            if (this.#transport) {
+                await waitForTransportReady(this.#transport);
+                this.#transport.ref();
+            }
+            await new Promise((resolve, reject) => {
+                this.logger.flush((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        }
+        finally {
+            if (!this.#closing) {
+                this.#transport?.unref();
+            }
+        }
+    }
+    /**
+     * Flushes records and closes the worker transport when one is active.
+     */
+    async close() {
+        this.#closePromise ??= this.#close();
+        await this.#closePromise;
+    }
+    /**
+     * Performs the one-time driver shutdown.
+     */
+    async #close() {
+        if (this.#closed)
+            return;
+        this.#closing = true;
+        await this.flush();
+        this.#closed = true;
+        if (!this.#transport)
+            return;
+        const closed = once(this.#transport, 'close');
+        this.#transport.end();
+        await closed;
+    }
+}
+/**
+ * Resolves the configured standard Pino level.
+ *
+ * @param options - Explicit application logging options.
+ * @param env - Process environment values.
+ * @returns Valid standard logging level.
+ */
+function resolveLogLevel(options, env) {
+    if (options.enabled === false)
+        return 'silent';
+    const candidate = options.level
+        ?? env.PLATFORM_LOG_LEVEL
+        ?? ((options.environment ?? env.NODE_ENV) === 'test' ? 'silent' : 'info');
+    if (isLogLevel(candidate))
+        return candidate;
+    throw new Error(`Invalid PLATFORM_LOG_LEVEL value "${candidate}". Use trace, debug, info, warn, error, fatal, or silent.`);
+}
+/**
+ * Builds Pino transport targets for stdout and Platform devtools.
+ *
+ * @param options - Framework logging destination options.
+ * @param level - Minimum severity routed to each destination.
+ * @param environment - Current runtime environment.
+ * @param env - Process environment values.
+ * @returns Pino worker transport targets.
+ */
+function transportTargets(options, level, environment, env) {
+    if (level === 'silent')
+        return [];
+    const targets = [];
+    if (options.console !== false) {
+        targets.push({
+            target: 'pino/file',
+            level,
+            options: {
+                destination: 1,
+            },
+        });
+    }
+    if (devtoolsEnabled(options.devtools, environment, env)) {
+        targets.push({
+            target: devtoolsTransportTarget(),
+            level,
+            options: typeof options.devtools === 'object'
+                ? options.devtools
+                : {},
+        });
+    }
+    return targets;
+}
+/**
+ * Resolves whether the devtools transport is enabled.
+ *
+ * @param configured - Explicit transport setting.
+ * @param environment - Current runtime environment.
+ * @param env - Process environment values.
+ * @returns True when logs should stream to the development service.
+ */
+function devtoolsEnabled(configured, environment, env) {
+    if (configured === false)
+        return false;
+    if (configured === true || typeof configured === 'object')
+        return true;
+    const envValue = env.PLATFORM_LOG_DEVTOOLS?.toLowerCase().trim();
+    if (envValue) {
+        return envValue === '1'
+            || envValue === 'true'
+            || envValue === 'yes'
+            || envValue === 'on';
+    }
+    return isInteractiveDevelopmentEnvironment(environment);
+}
+/**
+ * Resolves the source or compiled transport module beside this driver.
+ *
+ * @returns Absolute module path suitable for Pino's worker loader.
+ */
+function devtoolsTransportTarget() {
+    const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    return fileURLToPath(new URL(`../transports/DevtoolsLogTransport.${extension}`, import.meta.url));
+}
+/**
+ * Narrows a value into one of the supported framework levels.
+ *
+ * @param input - Candidate log level.
+ * @returns True when the value is a standard level.
+ */
+function isLogLevel(input) {
+    return input === 'trace'
+        || input === 'debug'
+        || input === 'info'
+        || input === 'warn'
+        || input === 'error'
+        || input === 'fatal'
+        || input === 'silent';
+}
+/**
+ * Surfaces transport boot failures without recursively invoking the logger.
+ *
+ * @param error - Worker transport error.
+ */
+function reportTransportError(error) {
+    process.stderr.write(`[logging] Transport failed: ${error.message}\n`);
+}
+/**
+ * Waits for an asynchronous Pino worker to accept flush requests.
+ *
+ * The timeout also keeps short-lived command processes alive while the worker
+ * loads its transport module.
+ *
+ * @param transport - Pino worker transport.
+ */
+async function waitForTransportReady(transport) {
+    if (transport.ready)
+        return;
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error('Logging transport did not become ready within 5 seconds.'));
+        }, 5000);
+        /**
+         * Resolves after the worker has loaded its destination.
+         */
+        const onReady = () => {
+            cleanup();
+            resolve();
+        };
+        /**
+         * Rejects when the worker closes before initialization.
+         */
+        const onClose = () => {
+            cleanup();
+            reject(new Error('Logging transport closed before becoming ready.'));
+        };
+        /**
+         * Rejects when the worker cannot load its destination.
+         *
+         * @param error - Worker initialization error.
+         */
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        /**
+         * Removes readiness listeners after one terminal outcome.
+         */
+        const cleanup = () => {
+            clearTimeout(timeout);
+            transport.off('ready', onReady);
+            transport.off('close', onClose);
+            transport.off('error', onError);
+        };
+        transport.once('ready', onReady);
+        transport.once('close', onClose);
+        transport.once('error', onError);
+    });
+}

package/dist/logging/drivers/index.d.ts

@@ -0,0 +1 @@
+export * from './PinoLoggerDriver.js';

package/dist/logging/drivers/index.js

@@ -0,0 +1 @@
+export * from './PinoLoggerDriver.js';

package/dist/logging/index.d.ts

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

package/dist/logging/index.js

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

package/dist/logging/transports/DevtoolsLogTransport.d.ts

@@ -0,0 +1,35 @@
+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;
+}
+/**
+ * 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 function createDevtoolsLogTransport(options?: logging.DevtoolsLogOptions): Promise<Transform>;
+/**
+ * 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 declare function pinoRecordToDevtoolsEvent(record: PinoLogRecord): DevtoolsLogEvent;
+export {};

package/dist/logging/transports/DevtoolsLogTransport.js

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import build from 'pino-abstract-transport';
+const levelLabels = new Map([
+    [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 = {}) {
+    const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    const dispatcherModule = await import(`../../devtools/HttpEventDispatcher.${extension}`);
+    const { createHttpEventDispatcher } = dispatcherModule;
+    const dispatch = createHttpEventDispatcher(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) {
+    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) {
+    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, fallback) {
+    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, fallback) {
+    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) {
+    const milliseconds = numericValue(input, Date.now());
+    const date = new Date(milliseconds);
+    return Number.isNaN(date.getTime())
+        ? new Date().toISOString()
+        : date.toISOString();
+}

package/dist/mail/Mail.d.ts

@@ -0,0 +1,62 @@
+/** 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;
+}
+/** Normalizes messages and delegates immediate delivery to one transport. */
+export declare class Mail {
+    private readonly from;
+    private readonly transport;
+    /** Creates a mail service; absent transport selects local file previews. */
+    constructor(options?: MailOptions);
+    /** Validates message presence and sends once; apps own retries and recipient policy. */
+    send(message: MailMessage): Promise<MailDelivery>;
+    /** Resolves the sender and recipient list without changing application content. */
+    private resolveMessage;
+}
+/** Builds a shared Mail instance from an explicit environment or process.env. */
+export declare function createMailFromEnv(env?: NodeJS.ProcessEnv, options?: MailEnvOptions): Mail;
+/** Selects the transport; missing or unrecognized names currently fall back to file. */
+export declare function createMailTransportFromEnv(env?: NodeJS.ProcessEnv): MailTransport;
+/** Formats an address for transport use; this is not validation or header sanitization. */
+export declare function formatMailAddress(address: MailAddress): string;
+/** Extracts the address portion for acceptance metadata; does not validate deliverability. */
+export declare function mailAddressEmail(address: MailAddress): string;

package/dist/mail/Mail.js

@@ -0,0 +1,98 @@
+import { FileMailTransport, } from './transports/FileMailTransport.js';
+import { MailgunTransport, } from './transports/MailgunTransport.js';
+import { ResendTransport, } from './transports/ResendTransport.js';
+const defaultMailFrom = 'Platform <no-reply@platform.local>';
+/** Normalizes messages and delegates immediate delivery to one transport. */
+export class Mail {
+    from;
+    transport;
+    /** Creates a mail service; absent transport selects local file previews. */
+    constructor(options = {}) {
+        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) {
+        const resolved = this.resolveMessage(message);
+        return this.transport.send(resolved);
+    }
+    /** Resolves the sender and recipient list without changing application content. */
+    resolveMessage(message) {
+        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 = process.env, options = {}) {
+    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 = process.env) {
+    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) {
+    return {
+        directory: env.MAIL_FILE_DIRECTORY,
+    };
+}
+/** Requires both Mailgun credentials before constructing the HTTP transport. */
+function mailgunOptionsFromEnv(env) {
+    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) {
+    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) {
+    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) {
+    if (typeof address === 'string') {
+        const match = address.match(/<([^>]+)>/);
+        return (match?.[1] || address).trim();
+    }
+    return address.email;
+}