@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/db/migrations/index.js

@@ -2,7 +2,7 @@ export * from './contracts/index.js';
 export * from './DatabaseMigrationManager.js';
 export * from './DatabaseSchemaInspector.js';
 export * from './errors.js';
-export * from './KnexMigrationRenderer.js';
+export * from './renderKnexMigration.js';
 export * from './ModelSchemaCollector.js';
 export * from './promoteDestructiveSchemaChanges.js';
 export * from './SchemaDiffer.js';

package/dist/db/migrations/{KnexMigrationRenderer.d.ts → renderKnexMigration.d.ts}

@@ -1,11 +1,12 @@
 import type { SchemaMigrationPlan } from './contracts/index.js';
 /**
- * Renders a frozen TypeScript Knex migration from a safe schema plan.
+ * Renders a frozen TypeScript or JavaScript Knex migration from a safe schema plan.
  *
  * Generated source contains literal table, column, index, and foreign-key
  * operations. It never imports current models or field implementations.
  *
  * @param plan - Pure schema plan with no blocked changes.
- * @returns Deterministic TypeScript migration source.
+ * @param language - JavaScript keeps migration bytes identical in local and packaged apps.
+ * @returns Deterministic migration source.
  */
-export declare function renderKnexMigration(plan: SchemaMigrationPlan): string;
+export declare function renderKnexMigration(plan: SchemaMigrationPlan, language?: 'typescript' | 'javascript'): string;

package/dist/db/migrations/{KnexMigrationRenderer.js → renderKnexMigration.js}

@@ -1,13 +1,14 @@
 /**
- * Renders a frozen TypeScript Knex migration from a safe schema plan.
+ * Renders a frozen TypeScript or JavaScript Knex migration from a safe schema plan.
  *
  * Generated source contains literal table, column, index, and foreign-key
  * operations. It never imports current models or field implementations.
  *
  * @param plan - Pure schema plan with no blocked changes.
- * @returns Deterministic TypeScript migration source.
+ * @param language - JavaScript keeps migration bytes identical in local and packaged apps.
+ * @returns Deterministic migration source.
  */
-export function renderKnexMigration(plan) {
+export function renderKnexMigration(plan, language = 'typescript') {
     if (plan.blockedChanges.length > 0) {
         throw new Error('Cannot render a migration plan containing blocked changes.');
     }
@@ -15,7 +16,7 @@ export function renderKnexMigration(plan) {
         throw new Error('Cannot render an empty database migration.');
     }
     const lines = [
-        "import type { Knex } from 'knex';",
+        ...(language === 'typescript' ? ["import type { Knex } from 'knex';"] : []),
         '',
         '/** Knex migration settings for MariaDB non-transactional DDL. */',
         'export const config = { transaction: false };',
@@ -32,11 +33,11 @@ export function renderKnexMigration(plan) {
         ' * @param knex - Knex connection managed by the application migration runner.',
         ' * @returns Promise that resolves after every schema operation completes.',
         ' */',
-        'export async function up(knex: Knex): Promise<void> {',
+        language === 'typescript' ? 'export async function up(knex: Knex): Promise<void> {' : 'export async function up(knex) {',
     ];
     const body = renderMigrationBody(plan.safeChanges);
     lines.push(...body.map(line => line ? `\t${line}` : ''));
-    lines.push('}', '', '/**', ' * Refuses automatic rollback because generated MariaDB DDL is forward-only.', ' *', ' * @param _knex - Unused Knex connection supplied by the migration runner.', ' * @returns Promise that always rejects before performing database DDL.', ' */', 'export async function down(_knex: Knex): Promise<void> {', "\tthrow new Error('Generated database migrations are forward-only.');", '}', '');
+    lines.push('}', '', '/**', ' * Refuses automatic rollback because generated MariaDB DDL is forward-only.', ' *', ' * @param _knex - Unused Knex connection supplied by the migration runner.', ' * @returns Promise that always rejects before performing database DDL.', ' */', language === 'typescript' ? 'export async function down(_knex: Knex): Promise<void> {' : 'export async function down(_knex) {', "\tthrow new Error('Generated database migrations are forward-only.');", '}', '');
     return lines.join('\n');
 }
 /**

package/dist/flows/FlowCompiler.js

@@ -1,7 +1,7 @@
 import { isUlid } from '@db3.ai/pure/ulid';
 import { FLOW_INPUT_BLOCK_TYPE, FLOW_OUTPUT_BLOCK_TYPE } from './blocks/index.js';
 import { FlowDefinitionError } from './FlowDefinitionError.js';
-import { matchesDefinition, validateFlowValues } from './FlowValueValidator.js';
+import { matchesDefinition, validateFlowValues } from './flowValueValidator.js';
 const FLOW_VALUE_TYPES = new Set([
     'string',
     'number',

package/dist/flows/Flows.js

@@ -6,7 +6,7 @@ import { FlowCompiler } from './FlowCompiler.js';
 import { FlowDefinitionError } from './FlowDefinitionError.js';
 import { flowErrorSnapshot } from './errors.js';
 import { FlowStepJob } from './FlowStepJob.js';
-import { validateFlowValues } from './FlowValueValidator.js';
+import { validateFlowValues } from './flowValueValidator.js';
 import { FlowRun, FlowRunEvent, FlowStepRun } from './models/index.js';
 const DEFAULT_MAX_PAYLOAD_BYTES = 1024 * 1024;
 /**

package/dist/flows/index.d.ts

@@ -9,5 +9,5 @@ export * from './FlowCompiler.js';
 export * from './FlowDefinitionError.js';
 export * from './Flows.js';
 export * from './FlowStepJob.js';
-export * from './FlowValueValidator.js';
+export * from './flowValueValidator.js';
 export * from './models/index.js';

package/dist/flows/index.js

@@ -9,5 +9,5 @@ export * from './FlowCompiler.js';
 export * from './FlowDefinitionError.js';
 export * from './Flows.js';
 export * from './FlowStepJob.js';
-export * from './FlowValueValidator.js';
+export * from './flowValueValidator.js';
 export * from './models/index.js';

package/dist/health/Health.d.ts

@@ -0,0 +1,41 @@
+import type * as health from './contracts/index.js';
+/** Aggregates framework and application component checks into one safe report. */
+export declare class Health {
+    #private;
+    /**
+     * Creates an application health registry with the framework runtime check.
+     *
+     * @param options - Service identity and initial application checks.
+     */
+    constructor(options?: health.HealthOptions);
+    /**
+     * Registers or replaces one named component check.
+     *
+     * Stable names let applications override a framework default without
+     * producing duplicate output.
+     *
+     * @param name - Public component name used as the report key.
+     * @param check - Bounded check that returns only public-safe details.
+     * @returns This health service for fluent registration.
+     */
+    register(name: string, check: health.HealthCheck): this;
+    /**
+     * Removes one optional component check.
+     *
+     * The framework-owned application check cannot be removed because it makes
+     * the default endpoint useful without any application configuration.
+     *
+     * @param name - Registered component name.
+     * @returns Whether an application-owned check was removed.
+     */
+    remove(name: string): boolean;
+    /**
+     * Executes all checks concurrently and returns a public-safe aggregate.
+     *
+     * Thrown values are contained and converted to a generic unhealthy result;
+     * applications must log diagnostic details inside their check when needed.
+     *
+     * @returns Current aggregate and per-component health state.
+     */
+    report(): Promise<health.HealthReport>;
+}

package/dist/health/Health.js

@@ -0,0 +1,153 @@
+const STATUS_PRIORITY = {
+    ok: 0,
+    degraded: 1,
+    unhealthy: 2,
+};
+/** Aggregates framework and application component checks into one safe report. */
+export class Health {
+    #service;
+    #timeoutMs;
+    #checks = new Map();
+    /**
+     * Creates an application health registry with the framework runtime check.
+     *
+     * @param options - Service identity and initial application checks.
+     */
+    constructor(options = {}) {
+        this.#service = options.service?.trim() || 'application';
+        this.#timeoutMs = positiveTimeout(options.timeoutMs);
+        this.register('application', () => ({ status: 'ok' }));
+        for (const [name, check] of Object.entries(options.checks ?? {})) {
+            this.register(name, check);
+        }
+    }
+    /**
+     * Registers or replaces one named component check.
+     *
+     * Stable names let applications override a framework default without
+     * producing duplicate output.
+     *
+     * @param name - Public component name used as the report key.
+     * @param check - Bounded check that returns only public-safe details.
+     * @returns This health service for fluent registration.
+     */
+    register(name, check) {
+        const normalized = normalizeCheckName(name);
+        if (typeof check !== 'function')
+            throw new TypeError(`Health check "${normalized}" must be a function.`);
+        this.#checks.set(normalized, check);
+        return this;
+    }
+    /**
+     * Removes one optional component check.
+     *
+     * The framework-owned application check cannot be removed because it makes
+     * the default endpoint useful without any application configuration.
+     *
+     * @param name - Registered component name.
+     * @returns Whether an application-owned check was removed.
+     */
+    remove(name) {
+        const normalized = normalizeCheckName(name);
+        if (normalized === 'application')
+            return false;
+        return this.#checks.delete(normalized);
+    }
+    /**
+     * Executes all checks concurrently and returns a public-safe aggregate.
+     *
+     * Thrown values are contained and converted to a generic unhealthy result;
+     * applications must log diagnostic details inside their check when needed.
+     *
+     * @returns Current aggregate and per-component health state.
+     */
+    async report() {
+        const entries = await Promise.all([...this.#checks.entries()].map(async ([name, check]) => {
+            const startedAt = performance.now();
+            let result;
+            try {
+                result = normalizeCheckResult(await withTimeout(check(), this.#timeoutMs));
+            }
+            catch {
+                result = { status: 'unhealthy', message: 'Health check failed.' };
+            }
+            return [name, {
+                    ...result,
+                    durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+                }];
+        }));
+        const checks = Object.fromEntries(entries);
+        const status = entries.reduce((current, [, result]) => {
+            return STATUS_PRIORITY[result.status] > STATUS_PRIORITY[current] ? result.status : current;
+        }, 'ok');
+        return {
+            status,
+            service: this.#service,
+            timestamp: new Date().toISOString(),
+            checks,
+        };
+    }
+}
+/**
+ * Normalizes and validates a public component name.
+ *
+ * @param name - Caller-supplied check name.
+ * @returns Trimmed stable report key.
+ */
+function normalizeCheckName(name) {
+    const normalized = name.trim();
+    if (!normalized)
+        throw new TypeError('Health check names cannot be empty.');
+    return normalized;
+}
+/**
+ * Applies the healthy default and validates a component result.
+ *
+ * @param result - Value returned by a registered health check.
+ * @returns Validated public-safe component result.
+ */
+function normalizeCheckResult(result) {
+    if (result === undefined)
+        return { status: 'ok' };
+    if (!Object.hasOwn(STATUS_PRIORITY, result.status))
+        throw new TypeError(`Unsupported health status "${String(result.status)}".`);
+    return result.message
+        ? { status: result.status, message: result.message }
+        : { status: result.status };
+}
+/**
+ * Resolves the bounded per-check timeout.
+ *
+ * @param timeoutMs - Optional application override.
+ * @returns Positive timeout in milliseconds.
+ */
+function positiveTimeout(timeoutMs) {
+    if (timeoutMs === undefined)
+        return 3000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new TypeError('Health timeoutMs must be a positive number.');
+    return timeoutMs;
+}
+/**
+ * Prevents a stuck dependency from hanging the aggregate health endpoint.
+ *
+ * @param result - Check result or promise returned by the application.
+ * @param timeoutMs - Maximum time allowed for the check.
+ * @returns Check result before the timeout expires.
+ */
+async function withTimeout(result, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve(result),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('Health check timed out.')), timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/health/contracts/Health.d.ts

@@ -0,0 +1,36 @@
+/** Health states shared by aggregate reports and individual component checks. */
+export type HealthStatus = 'ok' | 'degraded' | 'unhealthy';
+/** Public-safe result returned by one named health check. */
+export interface HealthCheckResult {
+    /** Current component state. Unhealthy checks make the aggregate endpoint unavailable. */
+    status: HealthStatus;
+    /** Optional public-safe explanation suitable for an operator or external monitor. */
+    message?: string;
+}
+/** Recorded result for one component in an aggregate health report. */
+export interface HealthCheckReport extends HealthCheckResult {
+    /** Time spent executing this check, rounded to milliseconds. */
+    durationMs: number;
+}
+/** Complete application health report returned by the HTTP adapter. */
+export interface HealthReport {
+    /** Aggregate state derived from every registered component check. */
+    status: HealthStatus;
+    /** Stable service name configured by the application. */
+    service: string;
+    /** ISO timestamp recorded after all component checks complete. */
+    timestamp: string;
+    /** Results keyed by the stable names used when checks were registered. */
+    checks: Record<string, HealthCheckReport>;
+}
+/** Function used to inspect one framework or application component. */
+export type HealthCheck = () => HealthCheckResult | void | Promise<HealthCheckResult | void>;
+/** Configuration accepted when the application health service is created. */
+export interface HealthOptions {
+    /** Stable service name included in every report. */
+    service?: string;
+    /** Maximum time allowed for each check, defaulting to 3,000 milliseconds. */
+    timeoutMs?: number;
+    /** Initial framework or application checks keyed by stable component name. */
+    checks?: Record<string, HealthCheck>;
+}

package/dist/health/contracts/Health.js

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

package/dist/health/contracts/HealthHttp.d.ts

@@ -0,0 +1,15 @@
+import type { Health } from '../Health.js';
+/** Minimal application shape required by the health HTTP adapter. */
+export interface HealthApplication {
+    /** Health service whose aggregate report is exposed over HTTP. */
+    health: Health;
+}
+/** HTTP route configuration shared by supported server adapters. */
+export interface HealthRouteOptions {
+    /** Application that owns the health checks. */
+    app: HealthApplication;
+    /** Canonical endpoint path, defaulting to `/health`. */
+    path?: string;
+    /** Compatibility paths that return the same report. */
+    aliases?: string[];
+}

package/dist/health/contracts/HealthHttp.js

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

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

@@ -0,0 +1,2 @@
+export type * from './Health.js';
+export type * from './HealthHttp.js';

package/dist/health/contracts/index.js

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

package/dist/health/databaseHealthCheck.d.ts

@@ -0,0 +1,15 @@
+import type { Database } from '../db/index.js';
+import type { HealthCheck } from './contracts/index.js';
+/**
+ * Creates the standard database dependency check used by HTTP applications.
+ *
+ * The query proves the active connection can accept work without inspecting
+ * application tables or mutating customer data.
+ *
+ * @param database - Framework database service to query.
+ * @returns Health check suitable for `app().health.register()`.
+ *
+ * @example
+ * app().health.register('database', databaseHealthCheck(app().db));
+ */
+export declare function databaseHealthCheck(database: Database): HealthCheck;

package/dist/health/databaseHealthCheck.js

@@ -0,0 +1,18 @@
+/**
+ * Creates the standard database dependency check used by HTTP applications.
+ *
+ * The query proves the active connection can accept work without inspecting
+ * application tables or mutating customer data.
+ *
+ * @param database - Framework database service to query.
+ * @returns Health check suitable for `app().health.register()`.
+ *
+ * @example
+ * app().health.register('database', databaseHealthCheck(app().db));
+ */
+export function databaseHealthCheck(database) {
+    return async () => {
+        await database.knex.raw('SELECT 1');
+        return { status: 'ok' };
+    };
+}

package/dist/health/fastify.d.ts

@@ -0,0 +1,13 @@
+import type { FastifyInstance } from 'fastify';
+import type * as health from './contracts/index.js';
+/**
+ * Registers the canonical application health endpoint on a Fastify server.
+ *
+ * Healthy and degraded reports return HTTP 200 so optional degradation does not
+ * remove the process from service. An unhealthy component returns HTTP 503.
+ * Compatibility aliases are useful while external monitors migrate to `/health`.
+ *
+ * @param server - Fastify server that owns the HTTP lifecycle.
+ * @param options - Application health service and route paths.
+ */
+export declare function registerHealthRoute(server: FastifyInstance, options: health.HealthRouteOptions): void;

package/dist/health/fastify.js

@@ -0,0 +1,44 @@
+/**
+ * Registers the canonical application health endpoint on a Fastify server.
+ *
+ * Healthy and degraded reports return HTTP 200 so optional degradation does not
+ * remove the process from service. An unhealthy component returns HTTP 503.
+ * Compatibility aliases are useful while external monitors migrate to `/health`.
+ *
+ * @param server - Fastify server that owns the HTTP lifecycle.
+ * @param options - Application health service and route paths.
+ */
+export function registerHealthRoute(server, options) {
+    const paths = uniquePaths(options.path ?? '/health', options.aliases ?? []);
+    for (const path of paths) {
+        server.get(path, async (_request, reply) => healthResponse(options.app.health, reply));
+    }
+}
+/**
+ * Builds one safe response from the shared health service.
+ *
+ * @param service - Application health registry.
+ * @param reply - Fastify response used to set status and cache policy.
+ * @returns Aggregate health report.
+ */
+async function healthResponse(service, reply) {
+    const report = await service.report();
+    reply.header('cache-control', 'no-store');
+    reply.code(report.status === 'unhealthy' ? 503 : 200);
+    return report;
+}
+/**
+ * Validates and deduplicates canonical and compatibility route paths.
+ *
+ * @param canonical - Canonical health endpoint path.
+ * @param aliases - Optional compatibility paths.
+ * @returns Unique validated route paths in registration order.
+ */
+function uniquePaths(canonical, aliases) {
+    return [...new Set([canonical, ...aliases].map(path => {
+            const normalized = path.trim();
+            if (!normalized.startsWith('/'))
+                throw new TypeError(`Health route "${path}" must start with "/".`);
+            return normalized;
+        }))];
+}

package/dist/health/index.d.ts

@@ -0,0 +1,3 @@
+export { Health } from './Health.js';
+export { databaseHealthCheck } from './databaseHealthCheck.js';
+export type * from './contracts/index.js';

package/dist/health/index.js

@@ -0,0 +1,2 @@
+export { Health } from './Health.js';
+export { databaseHealthCheck } from './databaseHealthCheck.js';

package/dist/in-app/InApp.d.ts

@@ -0,0 +1,33 @@
+import { type UserIdentityModel } from '../auth/index.js';
+import type * as inbox from './contracts/index.js';
+/** Persistent in-app inbox independent of notification classes, email and live delivery. */
+export declare class InApp {
+    #private;
+    readonly options: inbox.InAppOptions;
+    readonly identityModel: UserIdentityModel;
+    /** Creates the service; ordinary applications use app().inApp and App's configured Auth identity model. */
+    constructor(options?: inbox.InAppOptions, identityModel?: UserIdentityModel);
+    /**
+     * Atomically accepts one message for up to 100 distinct recipients.
+     * Trusted server code owns sender authorization. The service validates identities and receive-scope policy.
+     * @param recipients - User ID or IDs; an empty list creates no work.
+     * @param message - Inbox content with a required plain-text fallback and optional rich body.
+     * @param options - Explicit scope, notification type and optional deduplication key.
+     * @returns Per-recipient durable acceptance, never a claim of browser delivery.
+     * @example await app().inApp.send(userId, { title: 'Ready', body: 'Your report is ready.' }, { scope: { type: 'account' }, type: 'report.ready' });
+     */
+    send(recipients: string | readonly string[], message: inbox.InAppMessage, options: inbox.InAppSendOptions): Promise<inbox.InAppAcceptance[]>;
+    /**
+     * Lists only the authenticated user's unarchived items in an authorized scope.
+     * @param query - Scope, page size, optional position and inbox/banner view.
+     * @returns Safe content, unread count and next-page position. Reading a page changes no state.
+     */
+    inbox(query: inbox.InAppInboxQuery): Promise<inbox.InAppInboxPage>;
+    /**
+     * Changes one owned item's read, dismissal or archive state without coupling those states.
+     * @param id - Inbox item ID; a foreign or missing ID returns the same not-found error.
+     * @param transition - Explicit recipient action.
+     * @param scope - Currently authorized scope, never inferred from the target item.
+     */
+    update(id: string, transition: inbox.InAppTransition, scope: inbox.InAppScope): Promise<void>;
+}