appos 0.2.1 → 0.2.3-0

package/dist/exports/tests/packages/appos/src/api/database.d.mts

@@ -0,0 +1,99 @@
+import { Logger } from "./logger.mjs";
+import * as drizzle_orm0 from "drizzle-orm";
+import { AnyRelations, EmptyRelations } from "drizzle-orm";
+import * as drizzle_orm_node_postgres0 from "drizzle-orm/node-postgres";
+import { Pool, PoolConfig } from "pg";
+import { PgTable } from "drizzle-orm/pg-core";
+import { MigrationConfig } from "drizzle-orm/migrator";
+
+//#region src/api/database.d.ts
+/**
+ * Extract qualified table names from db object.
+ */
+type QualifiedTableNames<TDb> = { [K in keyof TDb]: TDb[K] extends {
+  _: {
+    fullSchema: infer S;
+  };
+} ? `${K & string}.${keyof S & string}` : never }[keyof TDb];
+/**
+ * The schema used for migrations.
+ */
+declare const migrationsSchema = "public";
+/**
+ * The type of migration (schema or data).
+ */
+type MigrationType = "schema" | "data";
+/**
+ * Get the migration options for a specific database.
+ *
+ * @param name Name of the database to get migration options for
+ * @param type Type of migration (schema or data), defaults to "schema"
+ * @returns Migration configuration for drizzle-orm
+ */
+declare function defineMigrationOpts(name: string, type?: MigrationType): MigrationConfig;
+/**
+ * Options for defining the database.
+ */
+interface DefineDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
+  logger: Logger;
+  poolConfig: PoolConfig;
+  relations?: TRelations;
+  schema?: TSchema;
+}
+/**
+ * The database type.
+ */
+type Database = Awaited<ReturnType<typeof defineDatabase>>;
+/**
+ * Generate old and new row JSONB representations for delete/insert/update queries.
+ * Uses PostgreSQL 18's OLD/NEW support in RETURNING clause.
+ *
+ * @param table The table to generate changes for.
+ * @returns Object containing `_table`, `old` and `new` JSONB columns.
+ */
+declare function dbChanges<T extends PgTable>(table: T): {
+  _table: drizzle_orm0.SQL.Aliased<string>;
+  old: drizzle_orm0.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_1 ? { [K in keyof T_1]: T_1[K] } : never) | null>;
+  new: drizzle_orm0.SQL.Aliased<({ [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true ? T["_"]["columns"][Key]["_"]["data"] : T["_"]["columns"][Key]["_"]["data"] | null } extends infer T_2 ? { [K in keyof T_2]: T_2[K] } : never) | null>;
+};
+/**
+ * Define the database with the provided options.
+ *
+ * Algorithm:
+ * 1. Create a connection pool with sensible defaults
+ * 2. Initialize drizzle ORM with schema and relations
+ *
+ * @param opts The options for defining the database, including pool configuration, relations, and schema.
+ * @template TSchema The schema type for the database.
+ * @template TRelations The relations type for the database.
+ * @returns The defined database instance.
+ */
+declare function defineDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineDatabaseOptions<TSchema, TRelations>): Promise<drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
+  $client: Pool;
+}>;
+/**
+ * Options for defining a test database.
+ */
+interface DefineTestDatabaseOptions<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations> {
+  connectionString: string;
+  logger: Logger;
+  name: string;
+  schema: TSchema;
+  relations: TRelations;
+}
+/**
+ * Create a single test database with isolated schema.
+ *
+ * @param connectionString - Database connection string
+ * @param name - Name of the test database
+ * @returns Test database instance and cleanup function
+ */
+declare function defineTestDatabase<TSchema extends Record<string, unknown> = Record<string, never>, TRelations extends AnyRelations = EmptyRelations>(opts: DefineTestDatabaseOptions<TSchema, TRelations>): Promise<{
+  cleanUp: () => Promise<void>;
+  db: drizzle_orm_node_postgres0.NodePgDatabase<TSchema, TRelations> & {
+    $client: Pool;
+  };
+  dbName: string;
+}>;
+//#endregion
+export { Database, DefineDatabaseOptions, DefineTestDatabaseOptions, MigrationType, QualifiedTableNames, dbChanges, defineDatabase, defineMigrationOpts, defineTestDatabase, migrationsSchema };

package/dist/exports/tests/packages/appos/src/api/database.mjs

@@ -0,0 +1 @@
+import{APPOS_DIR as e,DATABASES_DIR as t}from"../constants.mjs";import{join as n}from"node:path";import{sql as r}from"drizzle-orm";import{drizzle as i}from"drizzle-orm/node-postgres";import{migrate as a}from"drizzle-orm/node-postgres/migrator";import{Client as o,Pool as s}from"pg";function c(r,i=`schema`){let a=i===`schema`?`schema-migrations`:`data-migrations`,o=i===`schema`?`schema-migrations`:`data-migrations`;return{migrationsFolder:`${n(e,t)}/${r}/${a}`,migrationsSchema:`public`,migrationsTable:o}}var l=class{#e;constructor(e){this.#e=e}logQuery(e,t){this.#e.info(t,e)}};async function u(e){let t=`test_w${process.env.VITEST_POOL_ID||`0`}_${Date.now()}_${Math.random().toString(36).substring(2,8)}`;await h(e.connectionString,e.name,e.logger);let n=`${e.name}_test_template`,r=p(e.connectionString),a=new o({connectionString:r});await a.connect();try{await a.query(`CREATE DATABASE ${t} WITH TEMPLATE ${n}`)}finally{await a.end()}let c=d(e.connectionString);c.database=t;let u=new s({connectionString:f(c)});return{cleanUp:async()=>{await u.end();let e=new o({connectionString:r});await e.connect();try{await e.query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1`,[t]),await e.query(`DROP DATABASE IF EXISTS ${t}`)}catch(e){console.error(`Could not drop test database:`,e)}finally{await e.end()}},db:i({client:u,logger:e.logger?new l(e.logger):void 0,relations:e.relations,schema:e.schema}),dbName:t}}function d(e){let t=new URL(e);return{database:t.pathname.slice(1)||`postgres`,host:t.hostname,password:decodeURIComponent(t.password),port:Number.parseInt(t.port||`5432`,10),user:decodeURIComponent(t.username)}}function f(e){let{user:t,password:n,host:r,port:i,database:a}=e;return`postgresql://${encodeURIComponent(t)}:${encodeURIComponent(n)}@${r}:${i}/${a}`}function p(e){let t=d(e);return t.database=`postgres`,f(t)}function m(e){let t=0;for(let n=0;n<e.length;n++){let r=e.charCodeAt(n);t=(t<<5)-t+r,t&=t}return Math.abs(t)}async function h(e,t,n){let r=`${t}_test_template`,u=new o({connectionString:p(e)});await u.connect();let h=m(r);try{if(await u.query(`SELECT pg_advisory_lock($1)`,[h]),(await u.query(`SELECT 1 FROM pg_database WHERE datname = $1`,[r])).rowCount===0){await u.query(`CREATE DATABASE ${r} WITH IS_TEMPLATE = true`);let o=d(e);o.database=r;let p=new s({connectionString:f(o)});try{await a(i({client:p,logger:n?new l(n):void 0}),c(t))}finally{await p.end()}}}finally{await u.query(`SELECT pg_advisory_unlock($1)`,[h]),await u.end()}}export{u as defineTestDatabase};

package/dist/exports/tests/packages/appos/src/api/event.d.mts

@@ -0,0 +1,235 @@
+import { Logger } from "./logger.mjs";
+import { Container } from "./container.mjs";
+import { z } from "zod";
+
+//#region src/api/event.d.ts
+
+/**
+ * Context available to event handlers.
+ */
+interface EventContext<TInput> {
+  /**
+   * The application container with access to db, mailer, logger, etc.
+   */
+  container: Container;
+  /**
+   * The validated input passed to this event.
+   */
+  input: TInput;
+}
+/**
+ * Options for defining an event bus.
+ */
+interface DefineEventBusOptions {
+  /**
+   * Redis URL for pub/sub.
+   */
+  dbUrl: string;
+  /**
+   * Logger instance for error reporting.
+   */
+  logger: Logger;
+}
+/**
+ * The event bus type for container.
+ */
+type EventBus = ReturnType<typeof defineEventBus>;
+/**
+ * Defines the event bus for pub/sub messaging.
+ * Uses Redis for cross-server communication.
+ *
+ * Algorithm:
+ * 1. Create lazy Redis publisher client
+ * 2. Create lazy Redis subscriber client
+ * 3. Manage subscriptions via callback registry
+ * 4. Provide publish/subscribe/close methods
+ *
+ * @param opts - Event bus configuration
+ * @returns Event bus instance
+ */
+declare function defineEventBus(opts: DefineEventBusOptions): {
+  /**
+   * Publish a message to a channel.
+   * Auto-connects on first call if not already connected.
+   *
+   * @param channel - Channel name
+   * @param message - Message payload (will be JSON stringified)
+   */
+  publish(channel: string, message: unknown): Promise<void>;
+  /**
+   * Subscribe to a channel. Returns unsubscribe function.
+   * Uses single connection with callback management.
+   *
+   * @param channel - Channel name
+   * @param callback - Callback for received messages
+   * @returns Unsubscribe function
+   */
+  subscribe(channel: string, callback: (message: unknown) => void): Promise<() => void>;
+  /**
+   * Check if a channel has any subscribers.
+   *
+   * @param channel - Channel name
+   * @returns true if channel has subscribers
+   */
+  hasSubscribers(channel: string): boolean;
+  /**
+   * Close the Redis connections.
+   */
+  close(): Promise<void>;
+};
+/**
+ * Options for defining an event.
+ */
+interface DefineEventOptions<TInput extends z.ZodType> {
+  /**
+   * Zod schema for validating event input.
+   */
+  input: TInput;
+  /**
+   * In-memory handler that runs only on the emitting server.
+   *
+   * @param ctx - Event context with container and input
+   */
+  run: (ctx: EventContext<z.infer<TInput>>) => Promise<void>;
+}
+/**
+ * Event object returned by defineEvent.
+ */
+interface Event<TInput> {
+  /**
+   * The event name (set during registration from filename).
+   */
+  readonly name: string | null;
+  /**
+   * Emit this event with the given input.
+   * Runs in-memory handler, then publishes to Redis (fire-and-forget).
+   *
+   * @param input - Input matching the event's input schema.
+   */
+  emit(input: TInput): Promise<void>;
+  /**
+   * The Zod schema for validating input.
+   */
+  inputSchema: z.ZodType<TInput>;
+  /**
+   * Register this event with the container. Called by the event loader.
+   *
+   * @param container - The application container
+   * @param name - The event name (derived from filename)
+   */
+  register(container: Container, name: string): void;
+  /**
+   * Subscribe to this event via Redis pub/sub.
+   * Use for tRPC subscriptions, SSE, WebSockets.
+   *
+   * @param handler - Handler called when event is emitted on any server
+   * @returns Unsubscribe function to cleanup the subscription
+   */
+  subscribe(handler: (ctx: EventContext<TInput>) => Promise<void>): Promise<() => void>;
+}
+/**
+ * Defines a type-safe event with in-memory and Redis pub/sub support.
+ *
+ * Algorithm:
+ * 1. Define event with input schema and in-memory run handler
+ * 2. On emit(): validate input, run in-memory handler, publish to Redis (fire-and-forget)
+ * 3. .subscribe() creates Redis subscription for tRPC/SSE/WebSocket handlers
+ *
+ * @example
+ * ```typescript
+ * // api/events/order-status.ts
+ * export default defineEvent({
+ *   input: z.object({
+ *     orderId: z.string(),
+ *     status: z.enum(["pending", "shipped", "delivered"]),
+ *   }),
+ *   async run(ctx) {
+ *     ctx.container.logger.info(`Order ${ctx.input.orderId} is ${ctx.input.status}`);
+ *   },
+ * });
+ *
+ * // Emit from anywhere
+ * await orderStatus.emit({ orderId: "123", status: "shipped" });
+ *
+ * // Subscribe (e.g., in tRPC router)
+ * const unsubscribe = await orderStatus.subscribe(async (ctx) => {
+ *   // Push to client via SSE/WebSocket
+ * });
+ * // Cleanup when client disconnects
+ * unsubscribe();
+ * ```
+ */
+declare function defineEvent<TInput extends z.ZodType>(options: DefineEventOptions<TInput>): Event<z.infer<TInput>>;
+/**
+ * Input schema for dbChangesEvent.
+ */
+declare const dbChangeInputSchema: z.ZodObject<{
+  action: z.ZodEnum<{
+    DELETE: "DELETE";
+    INSERT: "INSERT";
+    UPDATE: "UPDATE";
+  }>;
+  newData: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  oldData: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  organizationId: z.ZodNullable<z.ZodString>;
+  tableName: z.ZodString;
+  timestamp: z.ZodString;
+  userId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Type for dbChangesEvent input.
+ */
+type DbChangeInput = z.infer<typeof dbChangeInputSchema>;
+/**
+ * Built-in event for database changes.
+ * Emitted by trackDbChanges workflow.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to DB changes (e.g., in tRPC subscription)
+ * import { dbChangesEvent } from "appos/api";
+ *
+ * const unsubscribe = await dbChangesEvent.subscribe(async (ctx) => {
+ *   wsServer.publish("db-changes", JSON.stringify(ctx.input));
+ * });
+ *
+ * // Cleanup when done
+ * unsubscribe();
+ * ```
+ */
+declare const dbChangesEvent: Event<{
+  action: "DELETE" | "INSERT" | "UPDATE";
+  newData: Record<string, unknown> | null;
+  oldData: Record<string, unknown> | null;
+  organizationId: string | null;
+  tableName: string;
+  timestamp: string;
+  userId: string | null;
+}>;
+/**
+ * Options for loading events.
+ */
+interface LoadEventsOptions {
+  /**
+   * The application container.
+   */
+  container: Container;
+  /**
+   * Optional custom events directory path.
+   */
+  eventsDir?: string;
+}
+/**
+ * Auto-discovers and registers all events from the given directory.
+ *
+ * Algorithm:
+ * 1. Register built-in dbChangesEvent
+ * 2. Glob all .ts files in the directory (excluding test files)
+ * 3. Import each module's default export
+ * 4. If it's an Event (has emit + subscribe), call register(container, name)
+ *
+ * @param opts - Load events options
+ */
+declare function loadEvents(opts: LoadEventsOptions): Promise<void>;
+//#endregion
+export { DbChangeInput, DefineEventBusOptions, Event, EventBus, EventContext, dbChangeInputSchema, dbChangesEvent, defineEvent, defineEventBus, loadEvents };

package/dist/exports/tests/packages/appos/src/api/event.mjs

@@ -0,0 +1 @@
+import"./redis.mjs";import{glob as e}from"node:fs/promises";import{basename as t,join as n}from"node:path";import{z as r}from"zod";import"es-toolkit";function i(e){let t=null,n=null;return{inputSchema:e.input,get name(){return n},register(e,r){t=e,n=r},async emit(r){if(!t||!n)throw Error(`Event not registered. Ensure the worker is started before emitting events.`);let i=e.input.parse(r),a={container:t,input:i};await e.run(a),t.eventBus.publish(n,i).catch(e=>{t.logger.error({err:e,event:n},`Redis publish failed`)})},async subscribe(r){if(!t||!n)throw Error(`Event not registered. Ensure the worker is started before subscribing.`);return t.eventBus.subscribe(n,async i=>{let a=e.input.parse(i),o={container:t,input:a};try{await r(o)}catch(e){t.logger.error({err:e,event:n},`Event subscription handler error`)}})}}}const a=i({input:r.object({action:r.enum([`INSERT`,`UPDATE`,`DELETE`]),newData:r.record(r.string(),r.unknown()).nullable(),oldData:r.record(r.string(),r.unknown()).nullable(),organizationId:r.string().nullable(),tableName:r.string(),timestamp:r.string(),userId:r.string().nullable()}),async run(){}});export{a as dbChangesEvent};

package/dist/exports/tests/packages/appos/src/api/i18n.d.mts

@@ -0,0 +1,34 @@
+import { InitOptions, i18n, i18n as i18n$1 } from "i18next";
+
+//#region src/api/i18n.d.ts
+
+/**
+ * i18n initialization options extending i18next's InitOptions.
+ * Used for both server and client initialization.
+ */
+interface I18nInitOptions extends InitOptions {}
+/**
+ * Type-safe default options for i18n.
+ * Apps should spread these and override as needed.
+ */
+declare const defaultI18nOptions: {
+  readonly fallbackLng: "en";
+  readonly supportedLngs: readonly ["en"];
+  readonly defaultNS: "translation";
+  readonly ns: readonly ["translation"];
+  readonly interpolation: {
+    readonly escapeValue: false;
+  };
+  readonly react: {
+    readonly useSuspense: false;
+  };
+};
+/**
+ * Initializes i18next for server-side with filesystem backend.
+ *
+ * @param opts - Initialization options for i18next.
+ * @returns A promise that resolves to the initialized i18next instance.
+ */
+declare function defineI18n(opts: I18nInitOptions): Promise<i18n>;
+//#endregion
+export { I18nInitOptions, defaultI18nOptions, defineI18n, type i18n$1 as i18n };

package/dist/exports/tests/packages/appos/src/api/index.d.mts

@@ -0,0 +1,27 @@
+import { DefineLoggerOptions, Logger, defineLogger } from "./logger.mjs";
+import { Database, DefineDatabaseOptions, DefineTestDatabaseOptions, MigrationType, QualifiedTableNames, dbChanges, defineDatabase, defineMigrationOpts, defineTestDatabase, migrationsSchema } from "./database.mjs";
+import { AccessControlRoles, AccessController, AuditAction, Auth, AuthConfig, AuthPasskeyConfig, AuthSessionConfig, DefineAuthOptions, Role, auditActionSchema, createAccessControl, defineAuth } from "./auth.mjs";
+import { Cache, DefineCacheOptions, defineCache } from "./cache.mjs";
+import { Config, baseSchema, defineConfig } from "./config.mjs";
+import { DbChangeInput, DefineEventBusOptions, Event, EventBus, EventContext, dbChangeInputSchema, dbChangesEvent, defineEvent, defineEventBus, loadEvents } from "./event.mjs";
+import { DefineMailerOptions, Mailer, MailerPayload, MailerPayloadHtml, MailerPayloadReact, defineMailer } from "./mailer.mjs";
+import { NewStorageAttachment, NewStorageBlob, NewStorageVariantRecord, StorageAttachment, StorageBlob, StorageRelations, StorageRelationsConfig, StorageTables, StorageVariantRecord, defineStorageSchema } from "./storage-schema.mjs";
+import { ScheduledWorkflowContext, WorkflowContext, WorkflowHandle, defineScheduledWorkflow, defineWorkflow, loadWorkflows } from "./workflow.mjs";
+import { ImageTransformations, ResizeOptions, resizeSchema, transformationsSchema } from "./workflows/generate-image-variant.mjs";
+import { DatabaseWithStorage, DefineS3DiskOptions, DefineStorageOptions, Storage, StorageService, defineS3Disk, defineStorage } from "./storage.mjs";
+import { AppContainer, Container, ServerConfig, WorkerConfig, defineAppContainer } from "./container.mjs";
+import { AppContext, DefineAppContextOpts, SessionData, defineAppContext } from "./app-context.mjs";
+import { defineAuthSchema } from "./auth-schema.mjs";
+import { I18nInitOptions, defaultI18nOptions, defineI18n, i18n as i18n$1 } from "./i18n.mjs";
+import { Middleware, defineMiddleware, loadMiddleware } from "./middleware.mjs";
+import { DefineOpenAPIConfig, DefineOpenAPIConfigInput, DefineOpenAPIReturn, HandlerParams, OpenAPIMethodSpec, OpenAPIObjectConfigV31, OpenAPIRegistration, RouteModule, ValidationErrorResponse, appDir, defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineTypedResponses, generateOpenAPIDocument, loadAndRegisterAPIRoutes, registerRoutes, scanAPIRoutes, writeOpenAPISpecs } from "./openapi.mjs";
+import { withOtelSpan } from "./otel.mjs";
+import { DefineRedisClientOptions, RedisClient, defineRedisClient } from "./redis.mjs";
+import { CustomTypeOptions } from "i18next";
+
+//#region src/api/index.d.ts
+declare namespace index_d_exports {
+  export { AccessControlRoles, AccessController, AppContainer, AppContext, AuditAction, Auth, AuthConfig, AuthPasskeyConfig, AuthSessionConfig, Cache, Config, Container, CustomTypeOptions, Database, DatabaseWithStorage, DbChangeInput, DefineAppContextOpts, DefineAuthOptions, DefineCacheOptions, DefineDatabaseOptions, DefineEventBusOptions, DefineLoggerOptions, DefineMailerOptions, DefineOpenAPIConfig, DefineOpenAPIConfigInput, DefineOpenAPIReturn, DefineRedisClientOptions, DefineS3DiskOptions, DefineStorageOptions, DefineTestDatabaseOptions, Event, EventBus, EventContext, HandlerParams, I18nInitOptions, ImageTransformations, Logger, Mailer, MailerPayload, MailerPayloadHtml, MailerPayloadReact, Middleware, MigrationType, NewStorageAttachment, NewStorageBlob, NewStorageVariantRecord, OpenAPIMethodSpec, OpenAPIObjectConfigV31, OpenAPIRegistration, QualifiedTableNames, RedisClient, ResizeOptions, Role, RouteModule, ScheduledWorkflowContext, ServerConfig, SessionData, Storage, StorageAttachment, StorageBlob, StorageRelations, StorageRelationsConfig, StorageService, StorageTables, StorageVariantRecord, ValidationErrorResponse, WorkerConfig, WorkflowContext, WorkflowHandle, appDir, auditActionSchema, baseSchema, createAccessControl, dbChangeInputSchema, dbChanges, dbChangesEvent, defaultI18nOptions, defineAppContainer, defineAppContext, defineAuth, defineAuthSchema, defineCache, defineConfig, defineDatabase, defineEvent, defineEventBus, defineI18n, defineLogger, defineMailer, defineMiddleware, defineMigrationOpts, defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineRedisClient, defineS3Disk, defineScheduledWorkflow, defineStorage, defineStorageSchema, defineTestDatabase, defineTypedResponses, defineWorkflow, generateOpenAPIDocument, i18n$1 as i18n, loadAndRegisterAPIRoutes, loadEvents, loadMiddleware, loadWorkflows, migrationsSchema, registerRoutes, resizeSchema, scanAPIRoutes, transformationsSchema, withOtelSpan, writeOpenAPISpecs };
+}
+//#endregion
+export { index_d_exports };

package/dist/exports/tests/packages/appos/src/api/logger.d.mts

@@ -0,0 +1,21 @@
+import pino, { LoggerOptions } from "pino";
+
+//#region src/api/logger.d.ts
+
+/**
+ * Extended logger options with OpenTelemetry support.
+ */
+interface DefineLoggerOptions extends LoggerOptions {}
+/**
+ * The logger instance type.
+ */
+type Logger = Awaited<ReturnType<typeof defineLogger>>;
+/**
+ * Define the logger instance.
+ *
+ * @param opts - The options.
+ * @returns The logger.
+ */
+declare function defineLogger(opts: DefineLoggerOptions): Promise<pino.Logger<never, boolean>>;
+//#endregion
+export { DefineLoggerOptions, Logger, defineLogger };

package/dist/exports/tests/packages/appos/src/api/mailer.d.mts

@@ -0,0 +1,70 @@
+import Mail from "nodemailer/lib/mailer/index.ts";
+import { JSX } from "react";
+
+//#region src/api/mailer.d.ts
+
+/**
+ * The mailer type.
+ */
+type Mailer = ReturnType<typeof defineMailer>;
+/**
+ * The mailer payload type with React component.
+ */
+type MailerPayloadReact = Omit<Mail.Options, "from" | "html" | "text"> & {
+  /**
+   * The email address to send the email from.
+   */
+  from?: string;
+  /**
+   * The React component to render as the email body.
+   */
+  react: JSX.Element;
+};
+/**
+ * The mailer payload type with direct HTML and text.
+ */
+type MailerPayloadHtml = Omit<Mail.Options, "from"> & {
+  /**
+   * The email address to send the email from.
+   */
+  from?: string;
+  /**
+   * The HTML content of the email.
+   */
+  html: string;
+  /**
+   * The plain text content of the email.
+   */
+  text: string;
+};
+/**
+ * The mailer payload type - supports either React component or direct HTML+text.
+ */
+type MailerPayload = MailerPayloadReact | MailerPayloadHtml;
+/**
+ * Define the options for the mailer.
+ */
+interface DefineMailerOptions {
+  /**
+   * The default email address to use as the sender.
+   */
+  from: string;
+  /**
+   * The SMTP URL to use for sending emails.
+   */
+  smtpUrl: string;
+}
+/**
+ * Define the mailer.
+ *
+ * @param env - The environment variables.
+ * @returns The mailer.
+ */
+declare function defineMailer({
+  from,
+  smtpUrl
+}: DefineMailerOptions): {
+  send(payload: MailerPayload): Promise<void>;
+};
+//#endregion
+export { DefineMailerOptions, Mailer, MailerPayload, MailerPayloadHtml, MailerPayloadReact, defineMailer };

package/dist/exports/tests/packages/appos/src/api/middleware/error-handler.mjs

@@ -0,0 +1 @@
+function e(e){if(e&&typeof e==`object`&&`status`in e){let t=e.status;if(typeof t==`number`)return t}return e instanceof SyntaxError?400:500}function t(t){return(n,r,i,a)=>{let o=r.headers[`user-agent`];if(t.error({error:n.message,stack:n.stack,url:r.url,method:r.method,userAgent:typeof o==`string`?o:o?.[0],ip:r.ip},`Unhandled request error`),i.headersSent)return a(n);let s=process.env.NODE_ENV!==`production`;i.status(e(n)).json({error:`Internal server error`,...s&&{message:n.message,stack:n.stack}})}}export{t as defineErrorHandlerMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/health.mjs

@@ -0,0 +1 @@
+function e(e=`/health`){return(t,n,r)=>{if(t.path!==e)return r();n.status(200).json({status:`healthy`,timestamp:new Date().toISOString(),uptime:process.uptime()})}}export{e as defineHealthMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/i18n.mjs

@@ -0,0 +1 @@
+function e(e){return(t,n,r)=>{let i=t.headers[`accept-language`],a=`en`;if(i){let e=i.split(`,`)[0].split(`;`)[0].trim();e&&e.length>0&&(a=e)}t.dir=e.dir(a),t.language=a,t.languages=e.languages,t.t=e.getFixedT(a),r()}}export{e as defineI18nMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/request-logger.d.mts

@@ -0,0 +1,24 @@
+import "../logger.mjs";
+import { RequestHandler } from "ultimate-express";
+
+//#region src/api/middleware/request-logger.d.ts
+
+/**
+ * Metadata about the HTTP request.
+ */
+interface RequestMetadata {
+  /**
+   * Client's IP address from X-Forwarded-For or RemoteAddr.
+   */
+  ipAddress: string;
+  /**
+   * Client's User-Agent header.
+   */
+  userAgent: string;
+  /**
+   * Client IP's country from CF-IPCountry header.
+   */
+  country: string;
+}
+//#endregion
+export { RequestMetadata };

package/dist/exports/tests/packages/appos/src/api/middleware/request-logger.mjs

@@ -0,0 +1 @@
+import{instrumentation_exports as e}from"../../instrumentation.mjs";const t=`cf-ipcountry`;function n(e,n){n?.injectCountry&&!e.headers[t]&&(e.headers[t]=n.injectCountry);let r=e.headers[`x-forwarded-for`],i;i=typeof r==`string`?r.split(`,`)[0].trim():Array.isArray(r)&&r.length>0?r[0].split(`,`)[0].trim():e.socket.remoteAddress||``;let a=e.headers[`user-agent`]||``,o=e.headers[t]||``;return{ipAddress:i,userAgent:a,country:o}}function r(t,r){let i;try{i=e.trace.getTracer(`request-logger`)}catch(e){t.warn({error:e},`Failed to initialize OpenTelemetry tracer`),i=null}return(a,o,s)=>{let c=n(a,r);a.metadata=c;let l=Date.now(),u=null,d;if(i)try{u=i.startSpan(`${a.method} ${a.path}`,{kind:e.SpanKind.SERVER,attributes:{"http.method":a.method,"http.url":a.url,"http.target":a.path,"http.host":(typeof a.headers.host==`string`?a.headers.host:a.headers[`:authority`])||`unknown`,"http.scheme":a.protocol,"http.user_agent":c.userAgent||`unknown`,"http.client_ip":c.ipAddress,"http.client_country":c.country}}),d=u.spanContext().traceId}catch(e){t.warn({error:e},`Failed to create OpenTelemetry span`),u=null,d=crypto.randomUUID()}else t.info(`OpenTelemetry tracer not available, skipping span creation`),u=null,d=crypto.randomUUID();let f=u?e.trace.setSpan(e.context.active(),u):e.context.active(),p=(e=>e.startsWith(`/@`)||e.startsWith(`/node_modules/`)||e.startsWith(`/assets/`)||e.startsWith(`/public/`)||e.match(/\.(js|css|ico|png|jpg|jpeg|gif|svg|woff|woff2|ttf|eot|map)$/)||e.includes(`/locales/`)||e.endsWith(`.ts`)||e.endsWith(`.tsx`)||e.endsWith(`.json`))(a.path);o.setHeader(`X-Request-Id`,d),a.requestId=d,o.on(`finish`,()=>{let n=Date.now()-l;if(u)try{u.setAttributes({"http.status_code":o.statusCode,"http.response_content_length":o.get(`content-length`)||0}),o.statusCode>=400?u.setStatus({code:e.SpanStatusCode.ERROR,message:`HTTP ${o.statusCode}`}):u.setStatus({code:e.SpanStatusCode.OK}),u.end()}catch(e){t.warn({error:e},`Failed to update OpenTelemetry span`)}p||e.context.with(f,()=>{t.info({requestId:d,method:a.method,url:a.path,status:o.statusCode,duration:`${n}ms`},`Request completed`)})}),o.on(`close`,()=>{if(!(o.writableEnded||o.finished)){let n=Date.now()-l;if(u)try{u.setStatus({code:e.SpanStatusCode.ERROR,message:`Request closed unexpectedly`}),u.end()}catch(e){t.warn({error:e},`Failed to update OpenTelemetry span`)}p||e.context.with(f,()=>{t.warn({requestId:d,method:a.method,url:a.path,duration:`${n}ms`},`Request closed unexpectedly`)})}});let m=s;s=n=>{if(n){let r=Date.now()-l;if(u)try{u.recordException(n),u.setStatus({code:e.SpanStatusCode.ERROR,message:n instanceof Error?n.message:String(n)}),u.end()}catch(e){t.warn({error:e},`Failed to record exception in span`)}p||e.context.with(f,()=>{t.error({requestId:d,method:a.method,url:a.path,status:o.statusCode||500,duration:`${r}ms`,error:n instanceof Error?n.message:String(n)},`Request failed`)})}m(n)},e.context.with(f,()=>s())}}export{r as defineRequestLoggerMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/shutdown.mjs

@@ -0,0 +1 @@
+function e(e,t){return(n,r,i)=>{if(t()){e.info({url:n.url,method:n.method},`Rejecting request during shutdown`),r.status(503).set(`Connection`,`close`).json({error:`Server is shutting down`});return}i()}}export{e as defineShutdownMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/timeout.mjs

@@ -0,0 +1 @@
+function e(e,t=3e4){return(n,r,i)=>{let a=!1,o=setTimeout(()=>{a=!0,e.warn({url:n.url,method:n.method,timeout:t},`Request timeout`),r.headersSent||r.status(408).json({error:`Request timeout`}),r.removeListener(`finish`,s),r.removeListener(`close`,s)},t),s=()=>{a||clearTimeout(o)};r.on(`finish`,s),r.on(`close`,s),i()}}export{e as defineTimeoutMiddleware};

package/dist/exports/tests/packages/appos/src/api/middleware/youch-handler.mjs

@@ -0,0 +1 @@
+function e(e){if(e&&typeof e==`object`&&`status`in e){let t=e.status;if(typeof t==`number`)return t}return e instanceof SyntaxError?400:500}function t(t,n={}){return async(r,i,a,o)=>{if(process.env.NODE_ENV===`production`)return o(r);try{let{default:t}=await import(`youch`),o=new t(r,i);o.addLink(e=>`<a href="${`https://stackoverflow.com/search?q=${encodeURIComponent(e)}`}" target="_blank" title="Search on StackOverflow">Search Stack Overflow</a>`),o.addLink(e=>`<a href="${`https://www.google.com/search?q=${encodeURIComponent(e)}`}" target="_blank" title="Search on Google">Search Google</a>`);let s=await o.toHTML().then(e=>n.theme===`dark`?e.replace(`<style>`,`<style>body { background: #1a1a1a; color: #f0f0f0; }`):e);a.writeHead(e(r),{"content-type":`text/html`}),a.end(s)}catch(n){t.error({error:n instanceof Error?n.message:n,originalError:r instanceof Error?r.message:r},`Failed to render Youch error page`),a.status(e(r)).json({error:{message:r instanceof Error?r.message:`Internal server error`,...process.env.NODE_ENV!==`production`&&{stack:r instanceof Error?r.stack:void 0}}})}}}export{t as defineYouchErrorHandler};

package/dist/exports/tests/packages/appos/src/api/middleware.d.mts

@@ -0,0 +1,39 @@
+import { AppContainer } from "./container.mjs";
+import { Express, RequestHandler } from "ultimate-express";
+
+//#region src/api/middleware.d.ts
+interface Middleware {
+  name: string | null;
+  handler: (container: AppContainer) => RequestHandler;
+}
+/**
+ * Defines a user middleware loaded from api/middleware/ directory.
+ *
+ * Use numeric prefixes (000_, 001_, etc.) to control load order.
+ *
+ * @example
+ * // api/middleware/000_custom-auth.ts
+ * export default defineMiddleware({
+ *   handler: (container) => (req, res, next) => {
+ *     // Custom logic using container
+ *     next();
+ *   },
+ * });
+ */
+declare function defineMiddleware(config: {
+  name?: string;
+  handler: (container: AppContainer) => RequestHandler;
+}): Middleware;
+/**
+ * Loads user middleware from a directory and registers them with the app.
+ *
+ * Middleware files are loaded in alphabetical order by filename.
+ * Use numeric prefixes (000_, 001_, etc.) to control the load order.
+ *
+ * @param middlewareDir - The directory containing middleware files
+ * @param container - The application container
+ * @param app - The Express application instance
+ */
+declare function loadMiddleware(middlewareDir: string, container: AppContainer, app: Express): Promise<void>;
+//#endregion
+export { Middleware, defineMiddleware, loadMiddleware };

package/dist/exports/tests/packages/appos/src/api/middleware.mjs

@@ -0,0 +1 @@
+import{camelCase as e}from"../../../../node_modules/.bun/change-case@5.4.4/node_modules/change-case/dist/index.mjs";import t,{glob as n}from"node:fs/promises";import{basename as r}from"node:path";function i(t){return e(r(t,`.ts`).replace(/^\d+_/,``))}async function a(e,a,o){try{await t.access(e)}catch{return}let s=[];for await(let t of n(`${e}/**/*.ts`))!t.endsWith(`.test.ts`)&&!t.endsWith(`.spec.ts`)&&s.push(t);s.sort((e,t)=>r(e).localeCompare(r(t)));for(let e of s)try{let t=(await import(e)).default;if(t&&typeof t.handler==`function`){let n=t.name??i(e);a.logger.debug({name:n,file:e},`Loading user middleware`),o.use(t.handler(a))}else a.logger.warn({file:e},`Middleware file missing default export with handler function`)}catch(t){throw a.logger.error({file:e,error:t instanceof Error?t.message:t},`Failed to load middleware`),t}}export{a as loadMiddleware};