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

package/dist/in-app/InApp.js

@@ -0,0 +1,191 @@
+import { createHash } from 'node:crypto';
+import { ActiveRecord } from '../db/index.js';
+import { UserIdentity } from '../auth/index.js';
+import { app } from '../server/appContext.js';
+import { InAppRecord } from './InAppRecord.js';
+import { InAppError } from './InAppError.js';
+import { normalizeMessage, normalizeQuery, normalizeRecipients, normalizeScope, normalizeSend } from './validation.js';
+/** Persistent in-app inbox independent of notification classes, email and live delivery. */
+export class InApp {
+    options;
+    identityModel;
+    #commits = new WeakMap();
+    /** Creates the service; ordinary applications use app().inApp and App's configured Auth identity model. */
+    constructor(options = {}, identityModel = UserIdentity) {
+        this.options = options;
+        this.identityModel = identityModel;
+    }
+    /**
+     * 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' });
+     */
+    async send(recipients, message, options) {
+        const ids = normalizeRecipients(recipients);
+        const content = normalizeMessage(message);
+        const input = normalizeSend(options);
+        const contentHash = hash(content);
+        if (!ids.length)
+            return [];
+        const connection = InAppRecord.getDb();
+        const committed = this.#committed(connection);
+        const accepted = await connection.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            // Lock in stable order so concurrent batches and retries cannot deadlock by recipient order.
+            const canonicalIds = new Map();
+            for (const userId of [...ids].sort((left, right) => left.toLowerCase().localeCompare(right.toLowerCase()))) {
+                const row = await this.identityModel.where(this.identityModel.primaryKey, userId).toKnex().forUpdate().first();
+                if (!row)
+                    throw new InAppError('forbidden', 'Notification recipient is unavailable.');
+                const canonicalId = String(this.identityModel.fromDb(row).get(this.identityModel.primaryKey));
+                canonicalIds.set(userId, canonicalId);
+                await this.#authorize(canonicalId, input.scope, 'receive');
+            }
+            const results = [];
+            for (const userId of new Set(ids.map(id => canonicalIds.get(id)))) {
+                const deduplicationHash = input.key === undefined ? null : hash([userId, input.scope.type, scopeId(input.scope), input.type, input.key]);
+                // Request a current read; stale outer snapshots may require a caller-owned transaction retry.
+                const existingRow = deduplicationHash ? await InAppRecord.where('deduplicationHash', deduplicationHash).toKnex().forUpdate().first() : null;
+                const existing = existingRow ? InAppRecord.fromDb(existingRow) : null;
+                if (existing) {
+                    if (existing.contentHash !== contentHash)
+                        throw new InAppError('conflict', 'This notification key already has different content.');
+                    results.push({ userId, id: existing.id, status: 'existing' });
+                    continue;
+                }
+                const record = InAppRecord.create({ userId, scopeType: input.scope.type, scopeId: scopeId(input.scope), type: input.type, message: content, presentation: content.presentation, deduplicationHash, contentHash });
+                await record.save();
+                results.push({ userId, id: record.id, status: 'created' });
+            }
+            return results;
+        }));
+        await this.#changed(accepted.filter(item => item.status === 'created').map(item => item.userId), committed);
+        return accepted;
+    }
+    /**
+     * 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.
+     */
+    async inbox(query) {
+        const input = normalizeQuery(query);
+        const userId = await this.#reader(input.scope, 'read');
+        const rows = this.#query(userId, input.scope).whereNull('archivedAt');
+        if (input.view === 'banners')
+            rows.where('presentation', 'banner').whereNull('dismissedAt');
+        if (input.before)
+            rows.where('id', '<', input.before);
+        const records = await rows.orderBy('id', 'desc').limit(input.limit + 1).all();
+        const unreadCount = await this.#query(userId, input.scope).whereNull('archivedAt').whereNull('readAt').count();
+        const items = records.slice(0, input.limit).map(itemView);
+        return { items, unreadCount, nextBefore: records.length > input.limit ? items.at(-1).id : null };
+    }
+    /**
+     * 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.
+     */
+    async update(id, transition, scope) {
+        const input = normalizeScope(scope);
+        if (!/^[0-9A-HJKMNP-TV-Z]{26}$/.test(id) || !['read', 'unread', 'dismiss', 'archive'].includes(transition))
+            throw new InAppError('invalid', 'Invalid inbox state change.');
+        const userId = await this.#reader(input, 'update');
+        const query = this.#query(userId, input).where('id', id);
+        if (!await query.first())
+            throw new InAppError('not_found', 'Inbox item not found.');
+        const field = transition === 'dismiss' ? 'dismissedAt' : transition === 'archive' ? 'archivedAt' : 'readAt';
+        const committed = this.#committed(InAppRecord.getDb());
+        const update = this.#query(userId, input).where('id', id);
+        if (transition !== 'unread')
+            update.whereNull(field);
+        const count = await update.patch({ [field]: transition === 'unread' ? null : new Date() });
+        if (count)
+            await this.#changed([userId], committed);
+    }
+    /** Observes all surrounding savepoints and the outer commit, including explicit rollback without an error. */
+    #committed(connection) {
+        if (!this.options.onChanged || !connection.isTransaction)
+            return;
+        const transactions = [];
+        let current = connection;
+        while (current) {
+            const transaction = current;
+            let result = this.#commits.get(transaction);
+            if (!result) {
+                let rolledBack = false;
+                /** The final control statement distinguishes silent rollback from commit or savepoint release. */
+                const query = (event) => {
+                    if (/^ROLLBACK/i.test(event.sql))
+                        rolledBack = true;
+                    else if (/^(COMMIT|RELEASE SAVEPOINT)/i.test(event.sql))
+                        rolledBack = false;
+                };
+                transaction.on('query', query);
+                result = transaction.executionPromise.then(() => !rolledBack, () => false).finally(() => transaction.off('query', query));
+                this.#commits.set(transaction, result);
+            }
+            transactions.push(result);
+            current = transaction.parentTransaction;
+        }
+        return Promise.all(transactions).then(results => results.every(Boolean));
+    }
+    /** Publishes only committed recipient changes; nested transactions defer without blocking their own commit. */
+    async #changed(userIds, committed) {
+        if (!this.options.onChanged || !userIds.length)
+            return;
+        const connection = app().db.knex;
+        /** Contains push failures so retrying notification delivery cannot duplicate an accepted message. */
+        const deliver = async () => ActiveRecord.withDb(connection, async () => {
+            await Promise.all([...new Set(userIds)].map(async (userId) => {
+                try {
+                    await this.options.onChanged(userId);
+                }
+                catch (error) {
+                    try {
+                        this.options.onDeliveryError?.(error);
+                    }
+                    catch { /* Reporting cannot undo the write. */ }
+                }
+            }));
+        });
+        if (committed) {
+            void committed.then(success => { if (success)
+                return deliver(); });
+        }
+        else
+            await deliver();
+    }
+    /** Builds an ownership-scoped query; callers never accept a reader ID from a browser. */
+    #query(userId, scope) {
+        return InAppRecord.where('userId', userId).where('scopeType', scope.type).where('scopeId', scopeId(scope));
+    }
+    /** Requires isolated request authentication and current scope authorization on every operation. */
+    async #reader(scope, operation) {
+        const application = app();
+        const user = application.requestContext.active ? application.auth.user : null;
+        if (!user)
+            throw new InAppError('unauthenticated', 'Sign in to access your inbox.');
+        const userId = String(user.get(this.identityModel.primaryKey));
+        await this.#authorize(userId, scope, operation);
+        return userId;
+    }
+    /** Account ownership is built in; application scopes require an explicit policy. */
+    async #authorize(userId, scope, operation) {
+        if (scope.type === 'account' && !this.options.authorizeScope)
+            return;
+        if (!await this.options.authorizeScope?.(userId, scope, operation))
+            throw new InAppError('forbidden', 'Notification scope is unavailable.');
+    }
+}
+/** Uses a nonempty sentinel only for the explicitly typed account scope. */
+function scopeId(scope) { return scope.type === 'account' ? 'account' : scope.id; }
+/** Hashes a normalized value; array envelopes avoid ambiguous delimiter concatenation. */
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+/** Serializes only the public inbox contract, never routing or deduplication internals. */
+function itemView(record) {
+    return { id: record.id, type: record.type, message: record.message, createdAt: record.createdAt.toISOString(), readAt: record.readAt?.toISOString() ?? null, dismissedAt: record.dismissedAt?.toISOString() ?? null, archivedAt: record.archivedAt?.toISOString() ?? null };
+}

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

@@ -0,0 +1,6 @@
+/** Stable service errors that HTTP adapters may translate without exposing storage details. */
+export declare class InAppError extends Error {
+    readonly code: 'invalid' | 'unauthenticated' | 'forbidden' | 'not_found' | 'conflict';
+    /** Creates a validation, access, missing-item or conflicting-retry error. */
+    constructor(code: 'invalid' | 'unauthenticated' | 'forbidden' | 'not_found' | 'conflict', message: string);
+}

package/dist/in-app/InAppError.js

@@ -0,0 +1,10 @@
+/** Stable service errors that HTTP adapters may translate without exposing storage details. */
+export class InAppError extends Error {
+    code;
+    /** Creates a validation, access, missing-item or conflicting-retry error. */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'InAppError';
+    }
+}

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

@@ -0,0 +1,36 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+import type { InAppMessage } from './contracts/index.js';
+/** Durable inbox item and independent state for one recipient; install through app migrations. */
+export declare class InAppRecord extends ActiveRecord {
+    static table: string;
+    static requestFillable: string[];
+    /** Defines inbox ownership, deduplication and recipient-state storage. */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        userId: import("../db/index.js").StringField;
+        scopeType: import("../db/index.js").StringField;
+        scopeId: import("../db/index.js").StringField;
+        type: import("../db/index.js").StringField;
+        message: import("../db/index.js").JsonField<InAppMessage | null>;
+        deduplicationHash: import("../db/index.js").StringField;
+        contentHash: import("../db/index.js").StringField;
+        presentation: import("../db/index.js").StringField;
+        readAt: import("../db/index.js").TimestampField;
+        dismissedAt: import("../db/index.js").TimestampField;
+        archivedAt: import("../db/index.js").TimestampField;
+        createdAt: import("../db/index.js").TimestampField;
+    };
+    id: string;
+    userId: string;
+    scopeType: string;
+    scopeId: string;
+    type: string;
+    message: InAppMessage;
+    deduplicationHash: string | null;
+    contentHash: string;
+    presentation: string;
+    readAt: Date | null;
+    dismissedAt: Date | null;
+    archivedAt: Date | null;
+    createdAt: Date;
+}

package/dist/in-app/InAppRecord.js

@@ -0,0 +1,24 @@
+import { ActiveRecord } from '../db/index.js';
+/** Durable inbox item and independent state for one recipient; install through app migrations. */
+export class InAppRecord extends ActiveRecord {
+    static table = 'in_app_messages';
+    static requestFillable = [];
+    /** Defines inbox ownership, deduplication and recipient-state storage. */
+    static fields(field) {
+        return {
+            id: field.ulid(),
+            userId: field.string({ column: 'user_id', required: true, length: 255, maxLength: 255, indexes: [{ name: 'in_app_recipient_scope', columns: ['user_id', 'scope_type', 'scope_id'] }] }),
+            scopeType: field.string({ column: 'scope_type', required: true, length: 80, maxLength: 80 }),
+            scopeId: field.string({ column: 'scope_id', required: true, length: 255, maxLength: 255 }),
+            type: field.string({ required: true, length: 120, maxLength: 120 }),
+            message: field.json({ required: true }),
+            deduplicationHash: field.string({ column: 'deduplication_hash', length: 64, maxLength: 64, unique: true, hidden: true }),
+            contentHash: field.string({ column: 'content_hash', required: true, length: 64, maxLength: 64, hidden: true }),
+            presentation: field.string({ required: true, length: 16, maxLength: 16 }),
+            readAt: field.timestamp({ column: 'read_at' }),
+            dismissedAt: field.timestamp({ column: 'dismissed_at' }),
+            archivedAt: field.timestamp({ column: 'archived_at' }),
+            createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+        };
+    }
+}

package/dist/in-app/contracts/InAppInbox.d.ts

@@ -0,0 +1,45 @@
+import type { InAppMessage } from './InAppMessage.js';
+import type { InAppScope } from './InAppScope.js';
+/** A safe recipient-facing view; internal deduplication hashes are never exposed. */
+export interface InAppItem {
+    id: string;
+    type: string;
+    message: InAppMessage;
+    createdAt: string;
+    readAt: string | null;
+    /** Dismissal hides a banner without removing its inbox item or implying it was read. */
+    dismissedAt: string | null;
+    archivedAt: string | null;
+}
+/** Trusted server dispatch metadata. Sending is not a public browser-authorized operation. */
+export interface InAppSendOptions {
+    scope: InAppScope;
+    /** Stable notification type, for example content-plan.ready. */
+    type: string;
+    /** Retry identity, unique within type, scope and recipient. Omit to create a new occurrence. */
+    key?: string;
+}
+/** One result per distinct recipient, in first-input order. Empty input returns an empty array. */
+export interface InAppAcceptance {
+    userId: string;
+    id: string;
+    status: 'created' | 'existing';
+}
+/** Query for the authenticated user's inbox in one explicit scope. */
+export interface InAppInboxQuery {
+    scope: InAppScope;
+    /** Defaults to 25; maximum 100. */
+    limit?: number;
+    /** ID from nextBefore. Pagination is an inbox position, not a realtime/replay cursor. */
+    before?: string;
+    /** Defaults to inbox; banners excludes dismissed items. All views exclude archived items. */
+    view?: 'inbox' | 'banners';
+}
+/** Paginated items and the unread count for the whole unarchived scoped inbox. */
+export interface InAppInboxPage {
+    items: InAppItem[];
+    unreadCount: number;
+    nextBefore: string | null;
+}
+/** Explicit independent recipient state transitions. */
+export type InAppTransition = 'read' | 'unread' | 'dismiss' | 'archive';

package/dist/in-app/contracts/InAppInbox.js

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

package/dist/in-app/contracts/InAppMessage.d.ts

@@ -0,0 +1,22 @@
+/** Recipient-facing content stored in an inbox. */
+export interface InAppMessage {
+    title: string;
+    /** Plain-text fallback used by compact, accessibility and non-HTML renderers. */
+    body: string;
+    /**
+     * Optional rich body authored by trusted application code.
+     *
+     * The framework validates and stores this value but does not sanitize it because
+     * permitted markup is an application policy. Every HTML renderer must sanitize it.
+     */
+    bodyHtml?: string;
+    /** Defaults to info. Severity does not determine persistence or prominence. */
+    severity?: 'info' | 'success' | 'warning' | 'error';
+    /** Defaults to toast. Every presentation remains in the durable inbox. */
+    presentation?: 'inbox' | 'toast' | 'banner';
+    /** Root-relative or HTTP(S) action; the destination must enforce its own authorization. */
+    action?: {
+        label: string;
+        href: string;
+    };
+}

package/dist/in-app/contracts/InAppMessage.js

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

package/dist/in-app/contracts/InAppScope.d.ts

@@ -0,0 +1,17 @@
+/** Explicit account or application-owned scope; tenant scopes require an authorization policy. */
+export type InAppScope = {
+    type: 'account';
+    id?: never;
+} | {
+    type: string;
+    id: string;
+};
+/** Scope policy invoked for recipients and authenticated readers, including state mutations. */
+export interface InAppOptions {
+    /** Best-effort invalidation after committed writes. Failures never undo durable acceptance. */
+    onChanged?: (userId: string) => void | Promise<void>;
+    /** Reports failed invalidations; inbox state remains authoritative. */
+    onDeliveryError?: (error: unknown) => void;
+    /** Non-account scopes fail closed when this policy is absent. Check current membership and write permissions. */
+    authorizeScope?: (userId: string, scope: InAppScope, operation: 'receive' | 'read' | 'update') => boolean | Promise<boolean>;
+}

package/dist/in-app/contracts/InAppScope.js

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

package/dist/in-app/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './InAppMessage.js';
+export * from './InAppScope.js';
+export * from './InAppInbox.js';

package/dist/in-app/contracts/index.js

@@ -0,0 +1,3 @@
+export * from './InAppMessage.js';
+export * from './InAppScope.js';
+export * from './InAppInbox.js';

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

@@ -0,0 +1,4 @@
+export * from './contracts/index.js';
+export { InApp } from './InApp.js';
+export { InAppRecord } from './InAppRecord.js';
+export { InAppError } from './InAppError.js';

package/dist/in-app/index.js

@@ -0,0 +1,4 @@
+export * from './contracts/index.js';
+export { InApp } from './InApp.js';
+export { InAppRecord } from './InAppRecord.js';
+export { InAppError } from './InAppError.js';

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

@@ -0,0 +1,21 @@
+import type * as inbox from './contracts/index.js';
+/** Copies and validates content before it can be persisted. */
+export declare function normalizeMessage(value: inbox.InAppMessage): inbox.InAppMessage;
+/** Validates the explicit dispatch scope, type and retry identity. */
+export declare function normalizeSend(value: inbox.InAppSendOptions): inbox.InAppSendOptions;
+/** Validates a scoped inbox query and resolves pagination defaults. */
+export declare function normalizeQuery(value: inbox.InAppInboxQuery): {
+    scope: {
+        type: "account";
+    } | {
+        type: string;
+        id: string;
+    };
+    limit: number;
+    view: "inbox" | "banners";
+    before?: string | undefined;
+};
+/** Validates a scope for state-changing operations. */
+export declare function normalizeScope(value: inbox.InAppScope): inbox.InAppScope;
+/** Validates the bounded recipient list and removes repeated identities. */
+export declare function normalizeRecipients(value: string | readonly string[]): string[];

package/dist/in-app/validation.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { InAppError } from './InAppError.js';
+const identifier = z.string().min(1).max(255).regex(/^\S+$/u);
+const scopeSchema = z.union([
+    z.object({ type: z.literal('account') }).strict(),
+    z.object({ type: z.string().min(1).max(80).regex(/^[a-zA-Z][a-zA-Z0-9_.-]*$/).refine(value => value !== 'account'), id: identifier }).strict(),
+]);
+const messageSchema = z.object({
+    title: z.string().trim().min(1).max(255),
+    body: z.string().trim().min(1).max(10_000),
+    bodyHtml: z.string().trim().min(1).max(50_000).optional(),
+    severity: z.enum(['info', 'success', 'warning', 'error']).default('info'),
+    presentation: z.enum(['inbox', 'toast', 'banner']).default('toast'),
+    action: z.object({ label: z.string().trim().min(1).max(120), href: z.string().min(1).max(2048).refine(safeAction) }).strict().optional(),
+}).strict();
+const sendSchema = z.object({ scope: scopeSchema, type: z.string().min(1).max(120).regex(/^[a-zA-Z0-9_.-]+$/), key: z.string().min(1).max(255).optional() }).strict();
+const querySchema = z.object({ scope: scopeSchema, limit: z.number().int().min(1).max(100).default(25), before: z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/).optional(), view: z.enum(['inbox', 'banners']).default('inbox') }).strict();
+/** Accepts local absolute paths and credential-free HTTP(S) URLs, rejecting executable and ambiguous forms. */
+function safeAction(value) {
+    if (/[\s\\\u0000-\u001f\u007f]/u.test(value))
+        return false;
+    if (value.startsWith('/') && !value.startsWith('//'))
+        return true;
+    try {
+        const url = new URL(value);
+        return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** Parses public input without leaking database or recipient information. */
+function parse(schema, value) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new InAppError('invalid', 'Invalid in-app message input.');
+    return result.data;
+}
+/** Copies and validates content before it can be persisted. */
+export function normalizeMessage(value) { return parse(messageSchema, value); }
+/** Validates the explicit dispatch scope, type and retry identity. */
+export function normalizeSend(value) { return parse(sendSchema, value); }
+/** Validates a scoped inbox query and resolves pagination defaults. */
+export function normalizeQuery(value) { return parse(querySchema, value); }
+/** Validates a scope for state-changing operations. */
+export function normalizeScope(value) { return parse(scopeSchema, value); }
+/** Validates the bounded recipient list and removes repeated identities. */
+export function normalizeRecipients(value) {
+    return [...new Set(parse(z.array(identifier).max(100), typeof value === 'string' ? [value] : value))];
+}

package/dist/index.d.ts

@@ -3,23 +3,11 @@ 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 './health/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>;
+export * from './apps/index.js';

package/dist/index.js

@@ -3,14 +3,11 @@ export { RequestContext, } from './server/index.js';
 export * from './cache/index.js';
 export * from './config/index.js';
 export * from './events/index.js';
+export * from './health/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,
-    };
-}
+export * from './apps/index.js';

package/dist/logging/DevelopmentConsole.d.ts

@@ -0,0 +1,42 @@
+import { Writable } from 'node:stream';
+import type * as logging from './contracts/index.js';
+/**
+ * Owns grouped log output and a bounded live pending area in one terminal.
+ * Multi-process launchers must pipe every child's output through this owner;
+ * unrelated processes writing directly to the same TTY cannot be coordinated.
+ */
+export declare class DevelopmentConsole {
+    #private;
+    /**
+     * Creates a console owner without starting an HTTP server or taking stream ownership.
+     * @param options - Destination, terminal capability and stdio coordination.
+     */
+    constructor(options?: logging.DevelopmentConsoleOptions);
+    /** Accepts a complete Pino JSON line, retaining ordinary non-log text verbatim. */
+    write(line: string): void;
+    /** Writes tool output above pending rows, removing controls that clear terminal history. */
+    writeText(text: string): void;
+    /**
+     * Creates a separately buffered child stdout/stderr sink, handling split UTF-8
+     * and final unterminated lines. Long non-JSON lines are forwarded in bounded chunks.
+     * @returns A writable input; end it when its child stream closes.
+     */
+    createInput(): Writable;
+    /** Finalizes pending work from an exited child without disturbing other children. */
+    endSource(pid: number): void;
+    /** Waits for previously rendered output to reach the caller-owned destination. */
+    flush(): Promise<void>;
+    /** Clears only owned rows, releases timers/listeners and restores patched stdio. */
+    close(): void;
+}
+/**
+ * Whether the pretty console uses colour. `NO_COLOR` turns it off; a set
+ * `FORCE_COLOR` (other than `0` or `false`) turns it on even without a TTY, as
+ * when a process manager pipes output into its own terminal view; otherwise a
+ * TTY decides.
+ *
+ * @param isTTY - Whether the output stream is a terminal.
+ * @param env - Process environment.
+ * @returns Whether to emit ANSI colours.
+ */
+export declare function consoleColor(isTTY: boolean, env: NodeJS.ProcessEnv): boolean;