@db3.ai/app 0.1.0-beta.1

package/dist/flows/models/FlowRunEvent.d.ts

@@ -0,0 +1,41 @@
+import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
+import type { EntityRef } from '../../db/fields/LinkField.js';
+import { type FlowRunEventType } from '../constants.js';
+import type { FlowLogLevel, FlowValue } from '../contracts/index.js';
+import { FlowRun } from './FlowRun.js';
+import { FlowStepRun } from './FlowStepRun.js';
+/**
+ * Ordered durable lifecycle or log event emitted during a flow run.
+ */
+export declare class FlowRunEvent extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static labelFields: string[];
+    static comment: string;
+    /**
+     * Defines ordered flow event fields and run-local sequence constraints.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow run event field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../../db/index.js").UlidField;
+        run: import("../../db/index.js").LinkField<FlowRun>;
+        stepRun: import("../../db/index.js").LinkField<FlowStepRun>;
+        sequence: import("../../db/index.js").IntegerField;
+        type: import("../../db/index.js").ChoiceStringField;
+        level: import("../../db/index.js").ChoiceStringField;
+        message: import("../../db/index.js").StringField;
+        data: import("../../db/index.js").JsonStringField<FlowValue>;
+        createdAt: import("../../db/index.js").TimestampField;
+    };
+    id: string | null;
+    run: EntityRef<FlowRun>;
+    stepRun: EntityRef<FlowStepRun> | null;
+    sequence: number | null;
+    type: FlowRunEventType | null;
+    level: FlowLogLevel | null;
+    message: string | null;
+    data: FlowValue | null;
+    createdAt: Date | null;
+}

package/dist/flows/models/FlowRunEvent.js

@@ -0,0 +1,85 @@
+import { ActiveRecord } from '../../db/index.js';
+import { FLOW_RUN_EVENT_TYPE } from '../constants.js';
+import { FlowRun } from './FlowRun.js';
+import { FlowStepRun } from './FlowStepRun.js';
+const FLOW_RUN_EVENTS_SEQUENCE_UNIQUE = 'flow_run_events_run_sequence_unique';
+/**
+ * Ordered durable lifecycle or log event emitted during a flow run.
+ */
+export class FlowRunEvent extends ActiveRecord {
+    static table = 'flow_run_events';
+    static primaryKey = 'id';
+    static labelFields = ['type', 'message'];
+    static comment = 'Ordered flow lifecycle and block log entries used by run timelines.';
+    /**
+     * Defines ordered flow event fields and run-local sequence constraints.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow run event field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.ulid({
+                comment: 'Stable flow run event ULID.',
+            }),
+            run: field.link(() => FlowRun, {
+                column: 'run_id',
+                required: true,
+                onDelete: 'CASCADE',
+                index: true,
+                indexes: [
+                    {
+                        name: FLOW_RUN_EVENTS_SEQUENCE_UNIQUE,
+                        columns: ['run_id', 'sequence'],
+                        unique: true,
+                    },
+                ],
+                comment: 'Flow run that owns this event.',
+            }),
+            stepRun: field.link(() => FlowStepRun, {
+                column: 'step_run_id',
+                required: false,
+                onDelete: 'CASCADE',
+                index: true,
+                comment: 'Block step associated with this event, when applicable.',
+            }),
+            sequence: field.integer({
+                required: true,
+                unsigned: true,
+                min: 0,
+                comment: 'Monotonic zero-based ordering within the flow run.',
+            }),
+            type: field.choice({
+                required: true,
+                choices: Object.values(FLOW_RUN_EVENT_TYPE),
+                length: 40,
+                maxLength: 40,
+                index: true,
+                comment: 'Lifecycle or log event type.',
+            }),
+            level: field.choice({
+                required: false,
+                choices: ['debug', 'info', 'warning', 'error'],
+                length: 20,
+                maxLength: 20,
+                comment: 'Optional block log severity.',
+            }),
+            message: field.string({
+                required: true,
+                length: 1024,
+                maxLength: 1024,
+                comment: 'Human-readable timeline or diagnostic message.',
+            }),
+            data: field.jsonLongText({
+                required: false,
+                comment: 'Optional structured event or diagnostic data.',
+            }),
+            createdAt: field.timestamp({
+                column: 'created_at',
+                precision: 3,
+                auto: 'create',
+                index: true,
+            }),
+        };
+    }
+}

package/dist/flows/models/FlowStepRun.d.ts

@@ -0,0 +1,56 @@
+import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
+import type { EntityRef } from '../../db/fields/LinkField.js';
+import { type FlowStepStatus } from '../constants.js';
+import type { FlowErrorSnapshot, FlowValues } from '../contracts/index.js';
+import { FlowRun } from './FlowRun.js';
+/**
+ * Durable execution state for one block occurrence within a flow run.
+ */
+export declare class FlowStepRun extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static labelFields: string[];
+    static comment: string;
+    /**
+     * Defines the durable per-block execution schema.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow step-run field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../../db/index.js").UlidField;
+        run: import("../../db/index.js").LinkField<FlowRun>;
+        blockId: import("../../db/index.js").StringField;
+        blockType: import("../../db/index.js").StringField;
+        blockName: import("../../db/index.js").StringField;
+        sequence: import("../../db/index.js").IntegerField;
+        status: import("../../db/index.js").ChoiceStringField;
+        attempt: import("../../db/index.js").IntegerField;
+        queueJobId: import("../../db/index.js").StringField;
+        nestedRun: import("../../db/index.js").LinkField<FlowRun>;
+        input: import("../../db/index.js").JsonStringField<FlowValues>;
+        output: import("../../db/index.js").JsonStringField<FlowValues>;
+        error: import("../../db/index.js").JsonStringField<FlowErrorSnapshot>;
+        startedAt: import("../../db/index.js").TimestampField;
+        completedAt: import("../../db/index.js").TimestampField;
+        createdAt: import("../../db/index.js").TimestampField;
+        updatedAt: import("../../db/index.js").TimestampField;
+    };
+    id: string | null;
+    run: EntityRef<FlowRun>;
+    blockId: string | null;
+    blockType: string | null;
+    blockName: string | null;
+    sequence: number | null;
+    status: FlowStepStatus | null;
+    attempt: number | null;
+    queueJobId: string | null;
+    nestedRun: EntityRef<FlowRun> | null;
+    input: FlowValues | null;
+    output: FlowValues | null;
+    error: FlowErrorSnapshot | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+}

package/dist/flows/models/FlowStepRun.js

@@ -0,0 +1,137 @@
+import { ActiveRecord } from '../../db/index.js';
+import { FLOW_STEP_STATUS } from '../constants.js';
+import { FlowRun } from './FlowRun.js';
+const FLOW_STEP_RUN_SEQUENCE_UNIQUE = 'flow_step_runs_run_sequence_unique';
+const FLOW_STEP_RUN_BLOCK_UNIQUE = 'flow_step_runs_run_block_unique';
+/**
+ * Durable execution state for one block occurrence within a flow run.
+ */
+export class FlowStepRun extends ActiveRecord {
+    static table = 'flow_step_runs';
+    static primaryKey = 'id';
+    static labelFields = ['blockName', 'status'];
+    static comment = 'Per-block flow execution input, output, error, queue identity, and timing.';
+    /**
+     * Defines the durable per-block execution schema.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow step-run field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.ulid({
+                comment: 'Stable flow step-run ULID.',
+            }),
+            run: field.link(() => FlowRun, {
+                column: 'run_id',
+                required: true,
+                onDelete: 'CASCADE',
+                index: true,
+                indexes: [
+                    {
+                        name: FLOW_STEP_RUN_SEQUENCE_UNIQUE,
+                        columns: ['run_id', 'sequence'],
+                        unique: true,
+                    },
+                    {
+                        name: FLOW_STEP_RUN_BLOCK_UNIQUE,
+                        columns: ['run_id', 'block_id'],
+                        unique: true,
+                    },
+                ],
+                comment: 'Flow run that owns this block execution.',
+            }),
+            blockId: field.string({
+                column: 'block_id',
+                required: true,
+                length: 26,
+                maxLength: 26,
+                comment: 'Stable block occurrence ULID from the definition snapshot.',
+            }),
+            blockType: field.string({
+                column: 'block_type',
+                required: true,
+                length: 160,
+                maxLength: 160,
+                index: true,
+                comment: 'Registered executable block type used for this step.',
+            }),
+            blockName: field.string({
+                column: 'block_name',
+                required: true,
+                length: 255,
+                maxLength: 255,
+                comment: 'Block instance or type name captured for run history.',
+            }),
+            sequence: field.integer({
+                required: true,
+                unsigned: true,
+                min: 0,
+                comment: 'Zero-based position in the compiled sequential plan.',
+            }),
+            status: field.choice({
+                required: true,
+                choices: Object.values(FLOW_STEP_STATUS),
+                default: FLOW_STEP_STATUS.pending,
+                length: 20,
+                maxLength: 20,
+                index: true,
+                comment: 'Current durable lifecycle state for this block execution.',
+            }),
+            attempt: field.integer({
+                required: true,
+                unsigned: true,
+                min: 0,
+                default: 0,
+                comment: 'Most recent queue attempt observed for this step.',
+            }),
+            queueJobId: field.string({
+                column: 'queue_job_id',
+                required: false,
+                length: 255,
+                maxLength: 255,
+                index: true,
+                comment: 'Driver-owned queue job id for the current step dispatch.',
+            }),
+            nestedRun: field.link(() => FlowRun, {
+                column: 'nested_run_id',
+                required: false,
+                onDelete: 'SET NULL',
+                index: true,
+                comment: 'Child flow run delegated to by this flow-backed block.',
+            }),
+            input: field.jsonLongText({
+                required: false,
+                comment: 'Validated values supplied to the block function.',
+            }),
+            output: field.jsonLongText({
+                required: false,
+                comment: 'Validated values returned by the block function.',
+            }),
+            error: field.jsonLongText({
+                required: false,
+                comment: 'Structured error from the most recent failed attempt.',
+            }),
+            startedAt: field.timestamp({
+                column: 'started_at',
+                precision: 3,
+                comment: 'Time the current or successful attempt began.',
+            }),
+            completedAt: field.timestamp({
+                column: 'completed_at',
+                precision: 3,
+                comment: 'Time the step completed or terminally failed.',
+            }),
+            createdAt: field.timestamp({
+                column: 'created_at',
+                precision: 3,
+                auto: 'create',
+            }),
+            updatedAt: field.timestamp({
+                column: 'updated_at',
+                precision: 3,
+                auto: 'update',
+            }),
+        };
+    }
+}

package/dist/flows/models/index.d.ts

@@ -0,0 +1,10 @@
+export * from './FlowRun.js';
+export * from './FlowRunEvent.js';
+export * from './FlowStepRun.js';
+import { FlowRun } from './FlowRun.js';
+import { FlowRunEvent } from './FlowRunEvent.js';
+import { FlowStepRun } from './FlowStepRun.js';
+/**
+ * Framework models an application installs when enabling durable flow runs.
+ */
+export declare const FLOW_MODELS: readonly [typeof FlowRun, typeof FlowStepRun, typeof FlowRunEvent];

package/dist/flows/models/index.js

@@ -0,0 +1,14 @@
+export * from './FlowRun.js';
+export * from './FlowRunEvent.js';
+export * from './FlowStepRun.js';
+import { FlowRun } from './FlowRun.js';
+import { FlowRunEvent } from './FlowRunEvent.js';
+import { FlowStepRun } from './FlowStepRun.js';
+/**
+ * Framework models an application installs when enabling durable flow runs.
+ */
+export const FLOW_MODELS = [
+    FlowRun,
+    FlowStepRun,
+    FlowRunEvent,
+];

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { App, type AppOptions, } from './server/index.js';
+export { RequestContext, type RequestContextValues, } from './server/index.js';
+export * from './cache/index.js';
+export * from './config/index.js';
+export * from './events/index.js';
+export * from './logging/index.js';
+export * from './media/index.js';
+export * from './security/index.js';
+export * from './serialization/index.js';
+export * from './url/index.js';
+export * from './validation/index.js';
+export interface AppManifest {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    icon?: string;
+    entry?: string;
+    adminPath?: string;
+    capabilities?: string[];
+}
+export interface AppDefinition<TManifest extends AppManifest = AppManifest> {
+    manifest: TManifest;
+}
+export declare function defineApp<TManifest extends AppManifest>(manifest: TManifest): AppDefinition<TManifest>;

package/dist/index.js

@@ -0,0 +1,16 @@
+export { App, } from './server/index.js';
+export { RequestContext, } from './server/index.js';
+export * from './cache/index.js';
+export * from './config/index.js';
+export * from './events/index.js';
+export * from './logging/index.js';
+export * from './media/index.js';
+export * from './security/index.js';
+export * from './serialization/index.js';
+export * from './url/index.js';
+export * from './validation/index.js';
+export function defineApp(manifest) {
+    return {
+        manifest,
+    };
+}

package/dist/logging/Log.d.ts

@@ -0,0 +1,66 @@
+import type { ChildLoggerOptions } from 'pino';
+import type * as logging from './contracts/index.js';
+/**
+ * Application logging service exposed as `app().log`.
+ *
+ * Pino supplies the default driver while this service owns framework discovery
+ * and lifecycle. Applications may inject a compatible driver in tests.
+ *
+ * @example
+ * app().log.info({ websiteId }, 'Website crawl started');
+ */
+export declare class Log implements logging.Logger {
+    #private;
+    /**
+     * Creates the application logger from explicit options or the Pino driver.
+     *
+     * @param options - Logging level, destinations, context, and driver overrides.
+     */
+    constructor(options?: logging.LoggingOptions);
+    /** Returns the current trace function, respecting runtime level changes. */
+    get trace(): logging.Logger['trace'];
+    /** Returns the current debug function, respecting runtime level changes. */
+    get debug(): logging.Logger['debug'];
+    /** Returns the current info function, respecting runtime level changes. */
+    get info(): logging.Logger['info'];
+    /** Returns the current warning function, respecting runtime level changes. */
+    get warn(): logging.Logger['warn'];
+    /** Returns the current error function, respecting runtime level changes. */
+    get error(): logging.Logger['error'];
+    /** Returns the current fatal function, respecting runtime level changes. */
+    get fatal(): logging.Logger['fatal'];
+    /** Returns the driver's non-emitting log function. */
+    get silent(): logging.Logger['silent'];
+    /**
+     * Returns the minimum severity currently emitted by the driver.
+     */
+    get level(): string;
+    /**
+     * Changes the minimum emitted severity at runtime.
+     *
+     * @param level - Pino-compatible log level.
+     */
+    set level(level: string);
+    /**
+     * Returns the underlying compatible logger for framework integrations.
+     *
+     * @returns Driver logger accepted by Fastify and worker adapters.
+     */
+    get logger(): logging.Logger;
+    /**
+     * Creates a context-bearing child logger.
+     *
+     * @param bindings - Stable structured fields for subsequent records.
+     * @param options - Optional Pino child logger overrides.
+     * @returns Child logger sharing the configured destinations.
+     */
+    child(bindings: logging.LogBindings, options?: ChildLoggerOptions): logging.Logger;
+    /**
+     * Waits for accepted records to reach their configured destination.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes records and releases transport resources.
+     */
+    close(): Promise<void>;
+}

package/dist/logging/Log.js

@@ -0,0 +1,79 @@
+import { PinoLoggerDriver } from './drivers/PinoLoggerDriver.js';
+/**
+ * Application logging service exposed as `app().log`.
+ *
+ * Pino supplies the default driver while this service owns framework discovery
+ * and lifecycle. Applications may inject a compatible driver in tests.
+ *
+ * @example
+ * app().log.info({ websiteId }, 'Website crawl started');
+ */
+export class Log {
+    #driver;
+    /**
+     * Creates the application logger from explicit options or the Pino driver.
+     *
+     * @param options - Logging level, destinations, context, and driver overrides.
+     */
+    constructor(options = {}) {
+        this.#driver = options.driver ?? new PinoLoggerDriver(options);
+    }
+    /** Returns the current trace function, respecting runtime level changes. */
+    get trace() { return this.#driver.logger.trace.bind(this.#driver.logger); }
+    /** Returns the current debug function, respecting runtime level changes. */
+    get debug() { return this.#driver.logger.debug.bind(this.#driver.logger); }
+    /** Returns the current info function, respecting runtime level changes. */
+    get info() { return this.#driver.logger.info.bind(this.#driver.logger); }
+    /** Returns the current warning function, respecting runtime level changes. */
+    get warn() { return this.#driver.logger.warn.bind(this.#driver.logger); }
+    /** Returns the current error function, respecting runtime level changes. */
+    get error() { return this.#driver.logger.error.bind(this.#driver.logger); }
+    /** Returns the current fatal function, respecting runtime level changes. */
+    get fatal() { return this.#driver.logger.fatal.bind(this.#driver.logger); }
+    /** Returns the driver's non-emitting log function. */
+    get silent() { return this.#driver.logger.silent.bind(this.#driver.logger); }
+    /**
+     * Returns the minimum severity currently emitted by the driver.
+     */
+    get level() {
+        return this.#driver.logger.level;
+    }
+    /**
+     * Changes the minimum emitted severity at runtime.
+     *
+     * @param level - Pino-compatible log level.
+     */
+    set level(level) {
+        this.#driver.logger.level = level;
+    }
+    /**
+     * Returns the underlying compatible logger for framework integrations.
+     *
+     * @returns Driver logger accepted by Fastify and worker adapters.
+     */
+    get logger() {
+        return this.#driver.logger;
+    }
+    /**
+     * Creates a context-bearing child logger.
+     *
+     * @param bindings - Stable structured fields for subsequent records.
+     * @param options - Optional Pino child logger overrides.
+     * @returns Child logger sharing the configured destinations.
+     */
+    child(bindings, options) {
+        return this.#driver.logger.child(bindings, options);
+    }
+    /**
+     * Waits for accepted records to reach their configured destination.
+     */
+    async flush() {
+        await this.#driver.flush();
+    }
+    /**
+     * Flushes records and releases transport resources.
+     */
+    async close() {
+        await this.#driver.close();
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Body representation retained by development HTTP exchange logging.
+ */
+export interface HttpBodyLog {
+    /** How the original payload was represented or why it was omitted. */
+    kind: 'empty' | 'json' | 'text' | 'binary' | 'stream';
+    /** Media type reported by the request or response. */
+    contentType?: string;
+    /** Redacted serialized payload size before the development capture limit. */
+    sizeBytes?: number;
+    /** Whether the displayed value was shortened to the configured byte limit. */
+    truncated?: boolean;
+    /** Redacted JSON value or captured text when the body is inspectable. */
+    value?: unknown;
+    /** Human-readable explanation for an omitted payload. */
+    note?: string;
+}
+/**
+ * Request fields retained by a development HTTP exchange record.
+ */
+export interface HttpRequestLog {
+    /** HTTP method used by the client. */
+    method: string;
+    /** Path and query string requested by the client. */
+    url: string;
+    /** Redacted request headers. */
+    headers: Record<string, unknown>;
+    /** Bounded and redacted request payload. */
+    body: HttpBodyLog;
+}
+/**
+ * Response fields retained by a development HTTP exchange record.
+ */
+export interface HttpResponseLog {
+    /** HTTP status selected before the response is sent. */
+    statusCode: number;
+    /** Redacted response headers. */
+    headers: Record<string, unknown>;
+    /** Bounded and redacted response payload. */
+    body: HttpBodyLog;
+}
+/**
+ * Development-only request and response data attached to a Pino log record.
+ */
+export interface HttpExchangeLog {
+    /** Incoming request details visible to the Fastify handler. */
+    request: HttpRequestLog;
+    /** Outgoing response details visible to Fastify's send lifecycle. */
+    response: HttpResponseLog;
+}

package/dist/logging/contracts/HttpExchange.js

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

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

@@ -0,0 +1,41 @@
+import type { ChildLoggerOptions, LogFn } from 'pino';
+/**
+ * Standard severity levels supported by the framework logger.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+/**
+ * Structured fields attached to one log record or child logger.
+ */
+export type LogBindings = Record<string, unknown>;
+/**
+ * Application logger contract shared by framework services and app code.
+ *
+ * The call signatures intentionally match Pino so structured records can be
+ * passed directly to Fastify and Pino-compatible transports.
+ */
+export interface Logger {
+    /** Minimum severity currently emitted by the logger. */
+    level: string;
+    /** Writes a highly detailed diagnostic record. */
+    trace: LogFn;
+    /** Writes a development diagnostic record. */
+    debug: LogFn;
+    /** Writes a normal operational record. */
+    info: LogFn;
+    /** Writes a recoverable problem record. */
+    warn: LogFn;
+    /** Writes a failed operation record. */
+    error: LogFn;
+    /** Writes a process-ending failure record. */
+    fatal: LogFn;
+    /** Accepts a record without emitting output. */
+    silent: LogFn;
+    /**
+     * Creates a logger that includes stable fields on every record.
+     *
+     * @param bindings - Structured context inherited by child records.
+     * @param options - Optional Pino child logger behavior.
+     * @returns Child logger sharing the same destinations.
+     */
+    child(bindings: LogBindings, options?: ChildLoggerOptions): Logger;
+}

package/dist/logging/contracts/Logger.js

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

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

@@ -0,0 +1,16 @@
+import type { Logger } from './Logger.js';
+/**
+ * Driver boundary used by the framework logging service.
+ */
+export interface LoggerDriver {
+    /** Logger implementation used for record creation. */
+    readonly logger: Logger;
+    /**
+     * Waits until records already accepted by the driver reach its destination.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flushes records and releases transport resources.
+     */
+    close(): Promise<void>;
+}

package/dist/logging/contracts/LoggerDriver.js

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