@db3.ai/app 0.1.0-beta.1

package/dist/media/image/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ImageVariant.js';
+export * from './ImageVariantCacheOptions.js';
+export * from './ImageProcessor.js';

package/dist/media/image/contracts/index.js

@@ -0,0 +1,3 @@
+export * from './ImageVariant.js';
+export * from './ImageVariantCacheOptions.js';
+export * from './ImageProcessor.js';

package/dist/media/image/index.d.ts

@@ -0,0 +1,5 @@
+export * from './contracts/index.js';
+export * from './ImageReconstructionError.js';
+export * from './ImageVariantRenderer.js';
+export * from './ImageVariantRequest.js';
+export * from './processors/index.js';

package/dist/media/image/index.js

@@ -0,0 +1,5 @@
+export * from './contracts/index.js';
+export * from './ImageReconstructionError.js';
+export * from './ImageVariantRenderer.js';
+export * from './ImageVariantRequest.js';
+export * from './processors/index.js';

package/dist/media/image/processors/SharpImageProcessor.d.ts

@@ -0,0 +1,25 @@
+import { type Sharp } from 'sharp';
+import type { ImageProcessor, ImageProcessorCommand, ImageProcessorReconstructionCommand } from '../contracts/index.js';
+/**
+ * Sharp/libvips image processor used by the framework's default media service.
+ */
+export declare class SharpImageProcessor implements ImageProcessor {
+    #private;
+    /**
+     * Creates a bounded Sharp transform for one validated framework command.
+     *
+     * @param command - Trusted image transformation command.
+     * @returns Sharp duplex stream for encoded source and output bytes.
+     */
+    transform(command: ImageProcessorCommand): Sharp;
+    /**
+     * Creates a bounded full-resolution reconstruction of untrusted image bytes.
+     *
+     * Reconstruction preserves animated GIF and WebP frames, applies source
+     * orientation, and relies on Sharp's default metadata removal.
+     *
+     * @param command - Validated canonical reconstruction command.
+     * @returns Sharp duplex stream for complete decoding and canonical encoding.
+     */
+    reconstruct(command: ImageProcessorReconstructionCommand): Sharp;
+}

package/dist/media/image/processors/SharpImageProcessor.js

@@ -0,0 +1,112 @@
+import sharp from 'sharp';
+const IMAGE_VARIANT_INPUT_PIXEL_LIMIT = 40_000_000;
+const IMAGE_VARIANT_PROCESSING_TIMEOUT_SECONDS = 20;
+const CANONICAL_JPEG_QUALITY = 90;
+const CANONICAL_WEBP_QUALITY = 90;
+/**
+ * Sharp/libvips image processor used by the framework's default media service.
+ */
+export class SharpImageProcessor {
+    /**
+     * Creates a bounded Sharp transform for one validated framework command.
+     *
+     * @param command - Trusted image transformation command.
+     * @returns Sharp duplex stream for encoded source and output bytes.
+     */
+    transform(command) {
+        let image = this.#source(false);
+        if (command.width !== null) {
+            image = image.resize({
+                width: command.width,
+                withoutEnlargement: true,
+            });
+        }
+        switch (command.outputMimeType) {
+            case 'image/avif':
+                return image.avif({
+                    quality: 50,
+                });
+            case 'image/jpeg':
+                return image.jpeg({
+                    progressive: true,
+                    quality: 82,
+                });
+            case 'image/png':
+                return image.png({
+                    compressionLevel: 9,
+                });
+            case 'image/webp':
+                return image.webp({
+                    quality: 82,
+                });
+            default:
+                throw new Error(`Sharp cannot encode responsive image MIME type "${command.outputMimeType}".`);
+        }
+    }
+    /**
+     * Creates a bounded full-resolution reconstruction of untrusted image bytes.
+     *
+     * Reconstruction preserves animated GIF and WebP frames, applies source
+     * orientation, and relies on Sharp's default metadata removal.
+     *
+     * @param command - Validated canonical reconstruction command.
+     * @returns Sharp duplex stream for complete decoding and canonical encoding.
+     */
+    reconstruct(command) {
+        const image = this.#source(isAnimatedImageMimeType(command.sourceMimeType));
+        switch (command.outputMimeType) {
+            case 'image/avif':
+                return image.avif({
+                    quality: 65,
+                });
+            case 'image/gif':
+                return image.gif({
+                    effort: 7,
+                    interFrameMaxError: 0,
+                });
+            case 'image/jpeg':
+                return image.jpeg({
+                    progressive: true,
+                    quality: CANONICAL_JPEG_QUALITY,
+                });
+            case 'image/png':
+                return image.png({
+                    compressionLevel: 9,
+                });
+            case 'image/webp':
+                return image.webp({
+                    effort: 5,
+                    quality: CANONICAL_WEBP_QUALITY,
+                });
+            default:
+                throw new Error(`Sharp cannot reconstruct image MIME type "${command.outputMimeType}".`);
+        }
+    }
+    /**
+     * Creates one security-bounded Sharp input pipeline.
+     *
+     * @param animated - Whether all frames from a supported animated source are decoded.
+     * @returns Sharp input stream with decode limits, orientation, and timeout configured.
+     */
+    #source(animated) {
+        return sharp({
+            animated,
+            failOn: 'warning',
+            limitInputPixels: IMAGE_VARIANT_INPUT_PIXEL_LIMIT,
+            sequentialRead: true,
+        })
+            .autoOrient()
+            .timeout({
+            seconds: IMAGE_VARIANT_PROCESSING_TIMEOUT_SECONDS,
+        });
+    }
+}
+/**
+ * Returns whether reconstruction must decode every source animation frame.
+ *
+ * @param mimeType - Normalized source image MIME type.
+ * @returns True for supported animated container formats.
+ */
+function isAnimatedImageMimeType(mimeType) {
+    return mimeType === 'image/gif' || mimeType === 'image/webp';
+}

package/dist/media/image/processors/index.d.ts

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

package/dist/media/image/processors/index.js

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

package/dist/media/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './contracts/index.js';
+export * from './image/index.js';
+export * from './MediaFile.js';
+export * from './MediaItem.js';
+export * from './MediaLibrary.js';
+export * from './MediaManager.js';
+export * from './types.js';

package/dist/media/index.js

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './contracts/index.js';
+export * from './image/index.js';
+export * from './MediaFile.js';
+export * from './MediaItem.js';
+export * from './MediaLibrary.js';
+export * from './MediaManager.js';
+export * from './types.js';

package/dist/media/types.d.ts

@@ -0,0 +1,129 @@
+import type { Readable } from 'node:stream';
+import type { StorageContents } from '../storage/index.js';
+import type { MediaFileVisibility } from './constants.js';
+import type { MediaFile } from './MediaFile.js';
+import type { MediaItem } from './MediaItem.js';
+import type { MediaLibrary } from './MediaLibrary.js';
+/**
+ * App-owned scope used to find or create a media library.
+ */
+export interface MediaLibraryScope {
+    /** Opaque scope type such as `app.website` or `app.organization`. */
+    scopeType: string;
+    /** Opaque app-owned scope id. */
+    scopeId: string;
+    /** Scope-local library key. Defaults to `default`. */
+    key?: string;
+    /** Human-readable library name used when a new library is created. */
+    name?: string;
+    /** Optional default storage disk for files written into this library. */
+    defaultDisk?: string | null;
+    /** Optional storage path prefix for files written into this library. */
+    pathPrefix?: string | null;
+    /** Optional app-owned library metadata. */
+    meta?: Record<string, unknown> | null;
+}
+/**
+ * Library input accepted by media manager methods.
+ */
+export type MediaLibraryInput = MediaLibrary | string;
+/**
+ * Input for writing a managed file without making it visible in the browser.
+ */
+export interface MediaStoreFileInput {
+    /** Existing media library or library id that will own the file. */
+    library: MediaLibraryInput;
+    /** File bytes or text accepted by the storage layer. */
+    contents: StorageContents;
+    /** Optional display filename. Defaults to the file id plus MIME extension. */
+    name?: string | null;
+    /** MIME type recorded on the file and passed to storage writes. */
+    mimeType?: string | null;
+    /** Optional storage disk override. Defaults to the library disk or app default. */
+    disk?: string | null;
+    /** Optional storage path override. Defaults to a library-scoped generated path. */
+    path?: string | null;
+    /** Optional app-owned source label such as generated-image or upload. */
+    source?: string | null;
+    /** Storage visibility used for the write. Defaults to private. */
+    visibility?: MediaFileVisibility | null;
+    /** Optional known byte size. Defaults to the byte length of the supplied contents. */
+    size?: number | null;
+    /** Optional app-owned file metadata. */
+    meta?: Record<string, unknown> | null;
+}
+/**
+ * Input for streaming a managed file without buffering it in application memory.
+ */
+export interface MediaStoreFileStreamInput extends Omit<MediaStoreFileInput, 'contents'> {
+    /** Readable stream containing the file bytes. */
+    stream: Readable;
+    /** Known byte size, or null when storage should measure the completed stream. */
+    size?: number | null;
+}
+/**
+ * Input for showing an existing managed file in the browser tree.
+ */
+export interface MediaAttachFileInput {
+    /** Existing media library or library id that owns the browser tree. */
+    library: MediaLibraryInput;
+    /** Managed file or file id to place in the browser. */
+    file: MediaFile | string;
+    /** Slash-prefixed folder path. Defaults to the library root. */
+    folderPath?: string | null;
+    /** Optional browser row name. Defaults to the file name. */
+    name?: string | null;
+    /** Optional app-owned item metadata. */
+    meta?: Record<string, unknown> | null;
+}
+/**
+ * Input for writing a file and immediately placing it in the browser tree.
+ */
+export interface MediaStoreVisibleFileInput extends MediaStoreFileInput {
+    /** Slash-prefixed folder path for the browser item. Defaults to the library root. */
+    folderPath?: string | null;
+    /** Optional browser row name. Defaults to the stored filename. */
+    itemName?: string | null;
+    /** Optional browser item metadata. */
+    itemMeta?: Record<string, unknown> | null;
+}
+/**
+ * Input for streaming a file and immediately placing it in the browser tree.
+ */
+export interface MediaStoreVisibleFileStreamInput extends MediaStoreFileStreamInput {
+    /** Slash-prefixed folder path for the browser item. Defaults to the library root. */
+    folderPath?: string | null;
+    /** Optional browser row name. Defaults to the stored filename. */
+    itemName?: string | null;
+    /** Optional browser item metadata. */
+    itemMeta?: Record<string, unknown> | null;
+}
+/**
+ * Input for reconstructing an image stream before durable browser placement.
+ */
+export interface MediaStoreReconstructedVisibleImageStreamInput extends Omit<MediaStoreVisibleFileStreamInput, 'mimeType' | 'size'> {
+    /** Allowlisted source MIME type used for decoding and canonical output. */
+    mimeType: string;
+}
+/**
+ * Result returned after a file is written and placed in the browser tree.
+ */
+export interface MediaStoredVisibleFile {
+    /** Library that owns the file and item. */
+    library: MediaLibrary;
+    /** Managed file row for loading bytes by ULID. */
+    file: MediaFile;
+    /** Browser-visible item row that points at the managed file. */
+    item: MediaItem;
+}
+/**
+ * Input for creating or finding a browser folder.
+ */
+export interface MediaFolderInput {
+    /** Existing media library or library id that owns the browser tree. */
+    library: MediaLibraryInput;
+    /** Slash-prefixed folder path to ensure. */
+    path: string;
+    /** Optional folder metadata applied only when a folder is created. */
+    meta?: Record<string, unknown> | null;
+}

package/dist/media/types.js

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

package/dist/queue/FailedJob.d.ts

@@ -0,0 +1,31 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+import type * as queue from './contracts/index.js';
+/**
+ * Queue record for jobs that exhausted their configured attempts.
+ */
+export declare class FailedJob extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    /**
+     * Defines the database schema for jobs that have exhausted their retries.
+     *
+     * @param field - Field builder used by ActiveRecord schema installation.
+     * @returns Failed queue job field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").BigIncrementsField;
+        uuid: import("../db/index.js").StringField;
+        connection: import("../db/index.js").TextField;
+        queue: import("../db/index.js").TextField;
+        payload: import("../db/index.js").JsonStringField<queue.JobEnvelope<Record<string, unknown>>>;
+        exception: import("../db/index.js").TextField;
+        failedAt: import("../db/index.js").TimestampField;
+    };
+    id: number | null;
+    uuid: string | null;
+    connection: string | null;
+    queue: string | null;
+    payload: queue.JobEnvelope<Record<string, unknown>> | null;
+    exception: string | null;
+    failedAt: Date | null;
+}

package/dist/queue/FailedJob.js

@@ -0,0 +1,41 @@
+import { ActiveRecord } from '../db/index.js';
+/**
+ * Queue record for jobs that exhausted their configured attempts.
+ */
+export class FailedJob extends ActiveRecord {
+    static table = 'jobs_failed';
+    static primaryKey = 'id';
+    /**
+     * Defines the database schema for jobs that have exhausted their retries.
+     *
+     * @param field - Field builder used by ActiveRecord schema installation.
+     * @returns Failed queue job field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.bigIncrements(),
+            uuid: field.string({
+                required: true,
+                unique: true,
+                length: 255,
+            }),
+            connection: field.text({
+                required: true,
+            }),
+            queue: field.text({
+                required: true,
+            }),
+            payload: field.jsonLongText({
+                required: true,
+            }),
+            exception: field.longText({
+                required: true,
+            }),
+            failedAt: field.timestamp({
+                column: 'failed_at',
+                required: true,
+                auto: 'create',
+            }),
+        };
+    }
+}

package/dist/queue/Queue.d.ts

@@ -0,0 +1,208 @@
+import type { Database } from '../db/index.js';
+import { type QueueMonitor } from './queueMonitor.js';
+import { QueueEvents } from './QueueEvents.js';
+import { QueueWorker } from './QueueWorker.js';
+import { type QueueableJob } from './QueueableJob.js';
+import type * as queue from './contracts/index.js';
+export type { QueueOptions, QueueService, QueueWorkOptions } from './contracts/index.js';
+/**
+ * Coordinates queue drivers, job handlers, dispatching, retries, and one-off processing.
+ *
+ * The Queue owns the durable job semantics. Long-running polling lives in QueueWorker so
+ * callers can either process one job at a time or start a worker loop over the same API.
+ */
+export declare class Queue implements queue.QueueService {
+    private readonly db;
+    private readonly options;
+    private readonly handlers;
+    private readonly driver;
+    private readonly monitor;
+    readonly events: QueueEvents;
+    constructor(db: Database, options?: queue.QueueOptions);
+    /**
+     * Returns the queue lifecycle monitor attached to this queue, when enabled.
+     */
+    get queueMonitor(): QueueMonitor | null;
+    /**
+     * Returns recent terminal failures from the configured queue driver.
+     *
+     * Drivers without persisted failure inspection return an empty collection so
+     * development tooling can use one queue-level API without knowing the driver.
+     *
+     * @param limit - Maximum number of recent failed jobs to return.
+     * @returns Recent failed jobs ordered from newest to oldest.
+     */
+    failedJobs(limit?: number): Promise<queue.QueueFailedJob[]>;
+    /**
+     * Replays one terminal failure as a new active queue job.
+     *
+     * The failed record remains untouched for audit. The replacement receives a
+     * new UUID and a retry reference to the original failure.
+     *
+     * @param id - Driver-owned failed-job record id.
+     * @param options - Optional dispatch overrides for the replacement job.
+     * @returns Queue driver id for the replacement job.
+     */
+    retryFailed(id: queue.QueueJobId, options?: queue.DispatchOptions): Promise<queue.QueueJobId>;
+    /**
+     * Registers an async handler for a named job payload.
+     */
+    registerHandler<TData = Record<string, unknown>>(name: string, handler: queue.JobHandler<TData>): void;
+    /**
+     * Registers a queueable job class by rehydrating it for each queued payload.
+     *
+     * @param Job - Queueable job class to register.
+     */
+    registerJob<TJob extends queue.QueueableJobClass>(Job: TJob): void;
+    /**
+     * Pushes a job payload to the configured driver.
+     *
+     * Queueable job instances are auto-registered on first dispatch in the current process.
+     */
+    dispatch<TData extends Record<string, unknown>>(job: string, data: TData, options?: queue.DispatchOptions): Promise<queue.QueueJobId>;
+    dispatch<TJob extends QueueableJob>(job: TJob, options?: queue.DispatchOptions): Promise<queue.QueueJobId>;
+    /**
+     * Dispatches the first job in a serialized chain.
+     *
+     * @param jobs - Serializable jobs to run in order.
+     * @param options - Dispatch options for the first job.
+     * @returns Queue id for the first queued job.
+     */
+    chain(jobs: QueueableJob[], options?: queue.DispatchOptions): Promise<queue.QueueJobId>;
+    /**
+     * Dispatches several queueable jobs independently.
+     *
+     * @param jobs - Serializable jobs to dispatch.
+     * @param options - Dispatch options applied to each job.
+     * @returns Queue ids for the dispatched jobs.
+     */
+    batch(jobs: QueueableJob[], options?: queue.DispatchOptions): Promise<queue.QueueJobId[]>;
+    /**
+     * Processes at most one available job and returns whether any work was handled.
+     */
+    processNextJob(queue?: string): Promise<boolean>;
+    /**
+     * Claims one job, runs its handler, and records the resulting success, retry, or failure.
+     */
+    workNextJob(queue?: string, options?: queue.QueueWorkOptions): Promise<queue.QueueProcessResult | null>;
+    /**
+     * Periodically renews a claimed job while its handler is still running.
+     *
+     * @param job - Claimed queue job.
+     * @param retryAfterSeconds - Driver lease duration in seconds.
+     * @returns Async stop function that also waits for an in-flight renewal.
+     */
+    private startLeaseHeartbeat;
+    /**
+     * Renews a lease immediately before committing an attempt outcome.
+     *
+     * A final renewal is both an ownership check and a fresh fencing window for
+     * the short transition that follows. Renewal errors are treated as unknown
+     * ownership so the worker leaves the durable record for safe recovery.
+     *
+     * @param job - Claimed queue job.
+     * @param retryAfterSeconds - Driver lease duration in seconds.
+     * @param operation - Outcome the worker intends to commit.
+     * @returns Null when ownership is confirmed, otherwise a lease error.
+     */
+    private confirmLease;
+    /**
+     * Records that a stale attempt stopped before changing newer queue state.
+     *
+     * @param job - Claimed job whose lease could not be confirmed.
+     * @param startedAt - Monotonic handler start time.
+     * @param error - Error describing the rejected transition.
+     * @returns Lease-lost queue result for worker logging.
+     */
+    private recordLostLease;
+    /**
+     * Creates a consistent error for one rejected attempt transition.
+     *
+     * @param job - Claimed queue job.
+     * @param operation - Transition rejected by lease fencing.
+     * @param detail - Optional driver error explaining unknown ownership.
+     * @returns Lease ownership error suitable for monitoring and logs.
+     */
+    private lostLeaseError;
+    /**
+     * Starts a polling worker for a queue unless workers are disabled by configuration.
+     */
+    startWorker(queue?: string, options?: queue.QueueWorkerOptions): QueueWorker | null;
+    private resolveDriver;
+    /**
+     * Returns a positive reservation timeout for queue claims and heartbeats.
+     *
+     * @returns Queue lease duration in whole seconds.
+     */
+    private retryAfterSeconds;
+    /**
+     * Resolves the durable backoff stored on a newly dispatched job.
+     *
+     * @param options - Optional per-dispatch backoff overrides.
+     * @returns Complete validated retry backoff.
+     */
+    private resolveRetryBackoff;
+    private workerIntervalMs;
+    private maxJobsPerTick;
+    private workerDisabled;
+    /**
+     * Builds the runtime context passed to a rehydrated queueable job.
+     */
+    private createQueueableJobContext;
+    /**
+     * Returns a registered handler, resolving a conventional job class when possible.
+     */
+    private handlerForJob;
+    /**
+     * Pushes a serialized queueable job to the driver.
+     *
+     * @param serialized - Serialized queueable job payload.
+     * @param options - Dispatch options for this queued job.
+     * @param chained - Optional chain tail to attach to this queued job.
+     * @returns Queue id for the pushed job.
+     */
+    private dispatchSerializedJob;
+    /**
+     * Dispatches the next job from a completed job chain.
+     *
+     * @param job - Successfully handled queue job.
+     */
+    private dispatchNextChainedJob;
+    /**
+     * Creates and pushes the durable queue envelope.
+     *
+     * @param name - Queue job name.
+     * @param data - JSON-safe job payload data.
+     * @param options - Dispatch options.
+     * @param displayName - Optional human-readable display name.
+     * @param chained - Serialized jobs to run after this job succeeds.
+     * @param retryOf - Optional terminal failure replayed to create this job.
+     * @returns Queue id returned by the driver.
+     */
+    private pushJob;
+    /**
+     * Publishes one lifecycle transition for a claimed queue job.
+     *
+     * @param action - Queue transition that has already occurred.
+     * @param job - Claimed job associated with the transition.
+     * @param details - Optional timing, delay, and error values.
+     * @returns Published immutable lifecycle event.
+     */
+    private publishJobEvent;
+    /**
+     * Runs one optional QueueableJob hook without changing the queue outcome.
+     *
+     * @param execution - Prepared job execution containing optional hooks.
+     * @param hook - Hook selected by the committed queue transition.
+     * @param event - Lifecycle event already published for the transition.
+     * @param error - Handler error that caused the transition.
+     * @param delaySeconds - Retry delay supplied to onRetry.
+     */
+    private runJobHook;
+    /**
+     * Reports an isolated lifecycle failure without throwing into queue work.
+     *
+     * @param failure - Listener or job-hook failure to report.
+     */
+    private reportLifecycleFailure;
+}