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

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

@@ -0,0 +1,6 @@
+export type { WebSocketContext, WebSocketClosed, WebSocketEndpoint } from './WebSocketEndpoint.js';
+export type { WebSocketOptions, WebSocketLimits } from './WebSocketOptions.js';
+export type { WebSocketPresence } from './WebSocketPresence.js';
+export type { ClientSocket, WebSocketClientOptions, WebSocketClientState, WebSocketClientChannel } from './WebSocketClient.js';
+export type { WebSocketChannelContext, WebSocketChannelDefinition, WebSocketChannelPublisher } from './WebSocketChannel.js';
+export type { WebSocketServiceOptions } from './WebSocketServiceOptions.js';

package/dist/websocket/contracts/index.js

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

package/dist/websocket/defineChannel.d.ts

@@ -0,0 +1,8 @@
+import type { WebSocketChannelDefinition } from './contracts/WebSocketChannel.js';
+/**
+ * Defines a private resource channel with an explicit application access policy.
+ * @param pattern - Colon-delimited name with optional {parameter} segments.
+ * @param options - Access check using the freshly authenticated user and resource parameters.
+ * @returns A definition to include in an endpoint's channels array.
+ */
+export declare function defineChannel(pattern: string, options: Omit<WebSocketChannelDefinition, 'pattern'>): WebSocketChannelDefinition;

package/dist/websocket/defineChannel.js

@@ -0,0 +1,13 @@
+/**
+ * Defines a private resource channel with an explicit application access policy.
+ * @param pattern - Colon-delimited name with optional {parameter} segments.
+ * @param options - Access check using the freshly authenticated user and resource parameters.
+ * @returns A definition to include in an endpoint's channels array.
+ */
+export function defineChannel(pattern, options) {
+    const segments = pattern.split(':');
+    const parameters = segments.filter(segment => segment.startsWith('{'));
+    if (pattern.length > 256 || !segments.every(segment => /^[a-zA-Z0-9_.-]+$/.test(segment) || /^\{[a-zA-Z][a-zA-Z0-9_]*\}$/.test(segment)) || new Set(parameters).size !== parameters.length || typeof options.authorize !== 'function')
+        throw new Error('Invalid channel definition.');
+    return Object.freeze({ pattern, authorize: options.authorize });
+}

package/dist/websocket/defineWebSocket.d.ts

@@ -0,0 +1,14 @@
+import type { WebSocketEndpoint } from './contracts/index.js';
+/**
+ * Defines controller actions while inferring the validated message type.
+ * @param endpoint - Application-owned authorization, validation and lifecycle actions.
+ * @returns The same definition for registration against an exact URL path.
+ * @example defineWebSocket({ open: async ({ send }) => { await send({ ready: true }); } });
+ */
+export declare function defineWebSocket<TMessage = unknown>(endpoint: WebSocketEndpoint<TMessage, null> & {
+    auth: 'public';
+}): WebSocketEndpoint<TMessage, null> & {
+    auth: 'public';
+};
+/** Defines an authenticated endpoint; omitted auth always requires a valid session. */
+export declare function defineWebSocket<TMessage = unknown>(endpoint: WebSocketEndpoint<TMessage>): WebSocketEndpoint<TMessage>;

package/dist/websocket/defineWebSocket.js

@@ -0,0 +1,4 @@
+/** Retains controller definitions without wrapping application actions. */
+export function defineWebSocket(endpoint) {
+    return endpoint;
+}

package/dist/websocket/fastify.d.ts

@@ -0,0 +1,11 @@
+import type { FastifyInstance } from 'fastify';
+import type { App } from '../server/App.js';
+import type { WebSocketOptions } from './contracts/index.js';
+/**
+ * Registers authenticated controller endpoints and closes upgraded sockets before Fastify drains HTTP.
+ * @param server - Fastify server before listen(). HTTP route hooks do not authorize upgrades.
+ * @param options - Application, exact origins, endpoints and optional limits.
+ */
+export declare function registerWebSockets(server: FastifyInstance, options: WebSocketOptions & {
+    app: App;
+}): void;

package/dist/websocket/fastify.js

@@ -0,0 +1,38 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * Registers authenticated controller endpoints and closes upgraded sockets before Fastify drains HTTP.
+ * @param server - Fastify server before listen(). HTTP route hooks do not authorize upgrades.
+ * @param options - Application, exact origins, endpoints and optional limits.
+ */
+export function registerWebSockets(server, options) {
+    options.app.webSockets.mount(server.server, options);
+    if (options.publish) {
+        const { path, token } = options.publish;
+        if (!/^\/[A-Za-z0-9/_-]+$/.test(path) || path.startsWith('//'))
+            throw new Error('Invalid WebSocket publishing path.');
+        if (!/^[A-Za-z0-9_-]{32,256}$/.test(token))
+            throw new Error('WebSocket publish token must contain 32 to 256 URL-safe characters.');
+        const expected = createHash('sha256').update(`Bearer ${token}`).digest();
+        server.post(path, {
+            bodyLimit: 65536,
+            /** Service credentials are checked before parsing a body; browser/session credentials never authorize publication. */
+            onRequest: async (request, reply) => {
+                const supplied = createHash('sha256').update(request.headers.authorization ?? '').digest();
+                if (request.headers.origin !== undefined || !timingSafeEqual(expected, supplied))
+                    return reply.code(401).send({ error: 'Unauthorized' });
+            },
+            schema: { body: {
+                    type: 'object', required: ['channel', 'event'], additionalProperties: false,
+                    properties: {
+                        channel: { type: 'string', maxLength: 256, pattern: '^[a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)*$' },
+                        event: { type: 'string', minLength: 1, maxLength: 256 }, data: {},
+                    },
+                } },
+        }, async (request, reply) => {
+            // Deliver locally, never call the outbound HTTP publisher or relay recursively.
+            await options.app.requestContext.run(() => options.app.webSockets.channels.publishEvent(request.body.channel, request.body.event, request.body.data));
+            return reply.code(204).send();
+        });
+    }
+    server.addHook('preClose', async () => { await options.app.webSockets.close(); });
+}

package/dist/websocket/index.d.ts

@@ -0,0 +1,5 @@
+export { WebSockets } from './WebSockets.js';
+export { WebSocketChannels } from './WebSocketChannels.js';
+export { defineWebSocket } from './defineWebSocket.js';
+export type * from './contracts/index.js';
+export { defineChannel } from './defineChannel.js';

package/dist/websocket/index.js

@@ -0,0 +1,4 @@
+export { WebSockets } from './WebSockets.js';
+export { WebSocketChannels } from './WebSocketChannels.js';
+export { defineWebSocket } from './defineWebSocket.js';
+export { defineChannel } from './defineChannel.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@db3.ai/app",
-	"version": "0.1.0-beta.1",
+	"version": "0.1.0",
 	"description": "A typed backend application framework with service-owned runtime modules and behavioural contracts.",
 	"license": "MIT",
 	"type": "module",
@@ -22,6 +22,26 @@
 		"db3": "bin/db3.mjs"
 	},
 	"exports": {
+		"./apps": {
+			"types": "./dist/apps/index.d.ts",
+			"import": "./dist/apps/index.js",
+			"default": "./dist/apps/index.js"
+		},
+		"./apps/contracts": {
+			"types": "./dist/apps/contracts/index.d.ts",
+			"import": "./dist/apps/contracts/index.js",
+			"default": "./dist/apps/contracts/index.js"
+		},
+		"./apps/fastify": {
+			"types": "./dist/apps/fastify.d.ts",
+			"import": "./dist/apps/fastify.js",
+			"default": "./dist/apps/fastify.js"
+		},
+		"./apps/commands": {
+			"types": "./dist/apps/commands/index.d.ts",
+			"import": "./dist/apps/commands/index.js",
+			"default": "./dist/apps/commands/index.js"
+		},
 		"./ai": {
 			"types": "./dist/ai/index.d.ts",
 			"import": "./dist/ai/index.js",
@@ -133,6 +153,16 @@
 			"import": "./dist/events/index.js",
 			"default": "./dist/events/index.js"
 		},
+		"./health": {
+			"types": "./dist/health/index.d.ts",
+			"import": "./dist/health/index.js",
+			"default": "./dist/health/index.js"
+		},
+		"./health/fastify": {
+			"types": "./dist/health/fastify.d.ts",
+			"import": "./dist/health/fastify.js",
+			"default": "./dist/health/fastify.js"
+		},
 		"./flows": {
 			"types": "./dist/flows/index.d.ts",
 			"import": "./dist/flows/index.js",
@@ -148,6 +178,16 @@
 			"import": "./dist/url/index.js",
 			"default": "./dist/url/index.js"
 		},
+		"./in-app": {
+			"types": "./dist/in-app/index.d.ts",
+			"import": "./dist/in-app/index.js",
+			"default": "./dist/in-app/index.js"
+		},
+		"./in-app/contracts": {
+			"types": "./dist/in-app/contracts/index.d.ts",
+			"import": "./dist/in-app/contracts/index.js",
+			"default": "./dist/in-app/contracts/index.js"
+		},
 		"./mail": {
 			"types": "./dist/mail/index.d.ts",
 			"import": "./dist/mail/index.js",
@@ -158,6 +198,16 @@
 			"import": "./dist/logging/index.js",
 			"default": "./dist/logging/index.js"
 		},
+		"./network": {
+			"types": "./dist/network/index.d.ts",
+			"import": "./dist/network/index.js",
+			"default": "./dist/network/index.js"
+		},
+		"./network/playwright": {
+			"types": "./dist/network/playwright/index.d.ts",
+			"import": "./dist/network/playwright/index.js",
+			"default": "./dist/network/playwright/index.js"
+		},
 		"./media": {
 			"types": "./dist/media/index.d.ts",
 			"import": "./dist/media/index.js",
@@ -168,6 +218,16 @@
 			"import": "./dist/media/image/index.js",
 			"default": "./dist/media/image/index.js"
 		},
+		"./notifications": {
+			"types": "./dist/notifications/index.d.ts",
+			"import": "./dist/notifications/index.js",
+			"default": "./dist/notifications/index.js"
+		},
+		"./notifications/contracts": {
+			"types": "./dist/notifications/contracts/index.d.ts",
+			"import": "./dist/notifications/contracts/index.js",
+			"default": "./dist/notifications/contracts/index.js"
+		},
 		"./queue": {
 			"types": "./dist/queue/index.d.ts",
 			"import": "./dist/queue/index.js",
@@ -198,6 +258,11 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./server/browser-json": {
+			"types": "./dist/server/registerBrowserJsonFormatting.d.ts",
+			"import": "./dist/server/registerBrowserJsonFormatting.js",
+			"default": "./dist/server/registerBrowserJsonFormatting.js"
+		},
 		"./ssr": {
 			"types": "./dist/ssr/index.d.ts",
 			"import": "./dist/ssr/index.js",
@@ -222,35 +287,65 @@
 			"types": "./dist/validation/index.d.ts",
 			"import": "./dist/validation/index.js",
 			"default": "./dist/validation/index.js"
+		},
+		"./websocket": {
+			"types": "./dist/websocket/index.d.ts",
+			"import": "./dist/websocket/index.js",
+			"default": "./dist/websocket/index.js"
+		},
+		"./websocket/fastify": {
+			"types": "./dist/websocket/fastify.d.ts",
+			"import": "./dist/websocket/fastify.js",
+			"default": "./dist/websocket/fastify.js"
+		},
+		"./websocket/client": {
+			"types": "./dist/websocket/client/index.d.ts",
+			"import": "./dist/websocket/client/index.js",
+			"default": "./dist/websocket/client/index.js"
+		},
+		"./websocket/contracts": {
+			"types": "./dist/websocket/contracts/index.d.ts",
+			"import": "./dist/websocket/contracts/index.js",
+			"default": "./dist/websocket/contracts/index.js"
+		},
+		"./apps/vite": {
+			"types": "./dist/apps/vite.d.ts",
+			"import": "./dist/apps/vite.js",
+			"default": "./dist/apps/vite.js"
 		}
 	},
 	"dependencies": {
-		"tsx": "^4.22.4",
-		"openai": "^6.44.0",
 		"@aws-sdk/client-s3": "^3.1077.0",
+		"@db3.ai/pure": "0.1.0",
 		"@flystorage/aws-s3": "^1.2.0",
 		"@flystorage/file-storage": "^1.2.2",
 		"@flystorage/local-fs": "^1.2.0",
 		"@keyv/redis": "^5.1.6",
-		"@db3.ai/pure": "0.1.0-beta.1",
+		"@openai/agents": "0.12.1",
 		"@redis/client": "^6.1.0",
+		"@types/ws": "^8.18.1",
 		"cache-manager": "^7.2.9",
 		"cacheable": "^2.5.0",
 		"dotenv": "^17.4.2",
+		"js-tiktoken": "^1.0.21",
 		"knex": "^3.2.10",
 		"mysql2": "^3.22.5",
+		"openai": "^6.44.0",
 		"pino": "^10.3.1",
 		"pino-abstract-transport": "^3.0.0",
 		"sharp": "^0.35.4",
 		"thread-stream": "^4.0.0",
-		"zod": "^4.4.3",
-		"@openai/agents": "0.12.1"
+		"tsx": "^4.22.4",
+		"undici": "^7.29.1",
+		"ws": "^8.21.0",
+		"zod": "^4.4.3"
 	},
 	"peerDependencies": {
 		"@fastify/middie": "^9.3.3",
 		"@fastify/static": "^10.1.3",
 		"fastify": "^5.11.3",
-		"vite": "^8.2.1"
+		"vite": "^8.2.1",
+		"playwright": "^1.61.1"
 	},
 	"peerDependenciesMeta": {
 		"@fastify/middie": {
@@ -264,8 +359,14 @@
 		},
 		"vite": {
 			"optional": true
+		},
+		"playwright": {
+			"optional": true
 		}
 	},
+	"bugs": {
+		"url": "https://github.com/db3ai/framework/issues"
+	},
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"files": [

package/src/ai/AIErrors.ts

@@ -1,3 +1,5 @@
+import type { AIRequestErrorDiagnostics } from './contracts/AIRequestErrorDiagnostics.js';
+
 /**
  * Raised when an AI operation needs provider credentials but none are configured.
  */
@@ -13,18 +15,26 @@ export class AIConfigurationError extends Error {
  * Raised when the provider rejects a request or returns a payload without text.
  */
 export class AIRequestError extends Error {
+	/** HTTP response status; null when no provider response was received. */
+	readonly status: number | null;
+	/** Provider request identifier for support correlation, when supplied. */
+	readonly requestId: string | null;
 	/**
 	 * Creates a provider request failure.
 	 *
 	 * @param message - Human-readable provider failure message.
 	 * @param code - Stable provider error code, when supplied.
+	 * @param diagnostics - Response status and support identifier without the payload.
 	 */
 	constructor(
 		message = 'The AI provider did not return a valid response.',
 		readonly code: string | null = null,
+		diagnostics: AIRequestErrorDiagnostics = {},
 	) {
 		super(message);
 		this.name = 'AIRequestError';
+		this.status = diagnostics.status ?? null;
+		this.requestId = diagnostics.requestId ?? null;
 	}
 }
 

package/src/ai/AIFailover.ts

@@ -1,3 +1,4 @@
+import { AIProviderDeferredError, AIProviderStoppedError } from './AIProviderAdmission';
 import { AIRateLimitDeferredError } from './AIRateLimiter.js';
 import { openAIProviderError, isOpenAIQuotaError } from './OpenAIProviderError.js';
 
@@ -68,7 +69,7 @@ export function isFailoverableResponse(status: number, payload: unknown): boolea
  * @returns True when the next provider in the chain should be attempted.
  */
 export function isFailoverableFailure(error: unknown): boolean {
-	if (error instanceof AIRateLimitDeferredError) return true;
+	if (error instanceof AIRateLimitDeferredError || error instanceof AIProviderDeferredError || error instanceof AIProviderStoppedError) return true;
 	if (isNetworkFailure(error)) return true;
 
 	const details = openAIProviderError(error);
@@ -88,7 +89,7 @@ export function isFailoverableFailure(error: unknown): boolean {
  * @param error - Unknown thrown value.
  * @returns True when the failure happened before a provider response arrived.
  */
-function isNetworkFailure(error: unknown, depth = 0): boolean {
+export function isNetworkFailure(error: unknown, depth = 0): boolean {
 	if ((!(error instanceof Error) && !(error instanceof DOMException)) || depth > 4) return false;
 	if (NETWORK_ERROR_NAMES.has(error.name)) return true;
 	if (error instanceof TypeError && error.message.includes('fetch failed')) return true;