appos 0.3.5-0 → 0.3.6-0

package/dist/exports/cli/index.d.mts

@@ -1,3 +1,2143 @@
-import { CommandContext } from "./context.mjs";
-import { Command, defineCommand } from "./command.mjs";
+import { n as __export, r as __reExport } from "./chunk-B36mNPO4.mjs";
+import { z } from "zod";
+import { CorsOptions } from "cors";
+import { Options } from "express-rate-limit";
+import { HelmetOptions } from "helmet";
+import { i18n } from "i18next";
+import { betterAuth } from "better-auth";
+import { Role, createAccessControl } from "better-auth/plugins/access";
+import * as drizzle_orm2 from "drizzle-orm";
+import { AnyRelations, EmptyRelations, ExtractTablesWithRelations } from "drizzle-orm";
+import * as drizzle_orm_node_postgres0 from "drizzle-orm/node-postgres";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import * as pg0 from "pg";
+import pg, { Pool } from "pg";
+import * as drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+import { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas } from "drizzle-orm/pg-core";
+import pino, { LoggerOptions } from "pino";
+import * as _keyv_redis0 from "@keyv/redis";
+import { KeyvRedisOptions } from "@keyv/redis";
+import Mail from "nodemailer/lib/mailer/index.ts";
+import { JSX } from "react";
+import { DriveManager } from "flydrive";
+import { FSDriverOptions } from "flydrive/drivers/fs/types";
+import { S3DriverOptions } from "flydrive/drivers/s3/types";
+import "@dbos-inc/dbos-sdk";
+import * as p from "@clack/prompts";
+
+//#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
+//#region src/api/database.d.ts
+type PoolConfig = pg.PoolConfig;
+/**
+ * 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];
+/**
+ * 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>>;
+/**
+ * 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: pg0.Pool;
+}>;
+//#endregion
+//#region src/api/auth.d.ts
+/**
+ * Type for access controller created via createAccessControl().
+ * Used for RBAC on both server and client.
+ */
+type AccessController = ReturnType<typeof createAccessControl>;
+/**
+ * Type for roles created via ac.newRole().
+ * Uses Role type from better-auth for compatibility.
+ */
+type AccessControlRoles = Record<string, Role>;
+/**
+ * Type-safe audit log options for defineAuth().
+ * Generic over db object to provide autocomplete for excludeTables.
+ *
+ * @template TDb - Database record type for table name inference
+ */
+type AuditLogOptions<TDb> = {
+  /**
+   * Tables to exclude from audit logging.
+   */
+  excludeTables?: QualifiedTableNames<TDb>[];
+  /**
+   * Cron expression for purge schedule.
+   *
+   * @default "0 0 * * *"
+   */
+  purgeCron?: string;
+  /**
+   * Retention period in days. Audit logs older than this are auto-deleted.
+   * @default 90
+   */
+  retentionDays?: number;
+};
+/**
+ * Neutral auth configuration - shared between server and client.
+ * Contains ONLY fields that affect both sides (UI + server features).
+ *
+ * PRESENCE-BASED CONFIG: If a key exists, it's enabled. No redundant `enabled` fields.
+ * Server-only fields (appName, session) are passed via DefineAuthOptions.
+ */
+interface AuthConfig {
+  /**
+   * Base URL where auth server is hosted.
+   *
+   * @default "" (same origin - client uses relative URLs)
+   * @example "http://localhost:8000" for cross-origin
+   */
+  baseURL?: string;
+  /**
+   * Base path for auth routes.
+   *
+   * @default "/auth"
+   */
+  basePath?: string;
+  /** Authentication methods - if defined, it's enabled */
+  methods?: {
+    /** Email/password auth. If defined, enabled. */
+    emailPassword?: {
+      requireEmailVerification?: boolean;
+      minPasswordLength?: number;
+      maxPasswordLength?: number;
+    };
+    /** Magic link auth. If defined, enabled. */
+    magicLink?: {
+      expiresIn?: number;
+    };
+    /** Passkey auth. If defined (even as empty object), enabled. */
+    passkey?: Record<string, never>;
+    /** Phone OTP auth. If defined, enabled. */
+    phoneOtp?: {
+      otpLength?: number;
+      expiresIn?: number;
+    };
+    /** Email OTP auth. If defined, enabled. */
+    emailOtp?: {
+      otpLength?: number;
+      expiresIn?: number;
+    };
+  };
+  /** OAuth providers - true = enabled, undefined/false = disabled */
+  oauth?: {
+    google?: boolean;
+    github?: boolean;
+    apple?: boolean;
+    facebook?: boolean;
+  };
+  /** Plugins - if defined, it's enabled */
+  plugins?: {
+    /** Admin plugin. If defined, enabled. Includes RBAC for both server and client. */
+    admin?: {
+      defaultRole?: string;
+      adminRoles?: string[];
+      /** Access controller created via createAccessControl() - shared between server and client */
+      ac: AccessController;
+      /** Role definitions created via ac.newRole() - shared between server and client */
+      roles: AccessControlRoles;
+    };
+    /** API key plugin. If defined, enabled. */
+    apiKey?: {
+      defaultPrefix?: string;
+      defaultKeyLength?: number;
+      rateLimit?: {
+        maxRequests?: number;
+        timeWindow?: number;
+      };
+    };
+    /** Two-factor plugin. If defined, enabled. Sub-features also presence-based. */
+    twoFactor?: {
+      issuer?: string;
+      totp?: {
+        digits?: 6 | 8;
+        period?: number;
+      };
+      otp?: boolean;
+      backupCodes?: {
+        amount?: number;
+        length?: number;
+      };
+    };
+    /** Multi-session plugin. If defined, enabled. */
+    multiSession?: {
+      maximumSessions?: number;
+    };
+    /** Username plugin. If defined, enabled. */
+    username?: {
+      minUsernameLength?: number;
+      maxUsernameLength?: number;
+    };
+    /** Anonymous auth plugin. If defined, enabled. */
+    anonymous?: {
+      emailDomainName?: string;
+    };
+    /** SSO plugin. If defined, enabled. Import from @better-auth/sso */
+    sso?: {
+      providersLimit?: number;
+      trustEmailVerified?: boolean;
+      domainVerification?: boolean;
+    };
+  };
+}
+/** Base hook types for reference */
+type EmailHook = (params: {
+  email: string;
+  url: string;
+  token: string;
+}) => Promise<void>;
+type OtpHook = (params: {
+  email: string;
+  otp: string;
+}) => Promise<void>;
+type PhoneOtpHook = (params: {
+  phoneNumber: string;
+  otp: string;
+}) => Promise<void>;
+/**
+ * Conditionally required hooks based on config.
+ * Uses PRESENCE-BASED detection - if key exists, hook is REQUIRED.
+ */
+type RequiredHooks<T extends AuthConfig> = (T["methods"] extends {
+  emailPassword: {
+    requireEmailVerification: true;
+  };
+} ? {
+  sendVerificationEmail: EmailHook;
+} : {
+  sendVerificationEmail?: EmailHook;
+}) & (T["methods"] extends {
+  emailPassword: object;
+} ? {
+  sendResetPasswordEmail: EmailHook;
+} : {
+  sendResetPasswordEmail?: EmailHook;
+}) & (T["methods"] extends {
+  magicLink: object;
+} ? {
+  sendMagicLink: EmailHook;
+} : {
+  sendMagicLink?: EmailHook;
+}) & (T["methods"] extends {
+  emailOtp: object;
+} ? {
+  sendEmailOTP: OtpHook;
+} : {
+  sendEmailOTP?: OtpHook;
+}) & (T["methods"] extends {
+  phoneOtp: object;
+} ? {
+  sendPhoneOTP: PhoneOtpHook;
+} : {
+  sendPhoneOTP?: PhoneOtpHook;
+}) & (T["plugins"] extends {
+  twoFactor: {
+    otp: true;
+  };
+} ? {
+  send2FAOTP: OtpHook;
+} : {
+  send2FAOTP?: OtpHook;
+});
+/**
+ * Conditionally required OAuth credentials based on config.
+ * If an OAuth provider is enabled in config, its credentials are REQUIRED.
+ */
+type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
+  google: true;
+} ? {
+  google: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  google?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  github: true;
+} ? {
+  github: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  github?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  apple: true;
+} ? {
+  apple: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  apple?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  facebook: true;
+} ? {
+  facebook: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  facebook?: {
+    clientId: string;
+    clientSecret: string;
+  };
+});
+/** Check if any OAuth provider is enabled */
+type HasOAuthEnabled<T extends AuthConfig> = T["oauth"] extends {
+  google: true;
+} | {
+  github: true;
+} | {
+  apple: true;
+} | {
+  facebook: true;
+} ? true : false;
+/** Check if passkey is enabled */
+type HasPasskeyEnabled<T extends AuthConfig> = T["methods"] extends {
+  passkey: object;
+} ? true : false;
+/**
+ * Server-only session configuration.
+ */
+interface AuthSessionConfig {
+  /**
+   * Session duration in seconds.
+   *
+   * @default 604800 (7 days)
+   */
+  expiresIn?: number;
+  /**
+   * How often to update session in seconds.
+   *
+   * @default 86400 (1 day)
+   */
+  updateAge?: number;
+  /**
+   * Session freshness in seconds for sensitive ops.
+   *
+   * @default 86400 (1 day)
+   */
+  freshAge?: number;
+}
+/**
+ * Server-only passkey configuration (required if passkey is enabled).
+ */
+interface AuthPasskeyConfig {
+  /**
+   * Relying Party ID - domain for passkey (e.g., "example.com" or "localhost").
+   */
+  rpID: string;
+  /**
+   * Origin URL for passkey verification (e.g., "http://localhost:8000").
+   */
+  origin: string;
+}
+/**
+ * Fully type-safe options for defineAuth().
+ *
+ * Server-only fields:
+ * - `appName` - Application name for passkey rpName, TOTP issuer, emails
+ * - `auditLog` - Audit logging configuration
+ * - `session` - Session duration and freshness settings
+ *
+ * Conditional requirements:
+ * - If config has `oauth.google: true`, then `oauth.google` credentials are REQUIRED
+ * - If config has `methods.magicLink` defined, then `hooks.sendMagicLink` is REQUIRED
+ *
+ * @template T - Auth config type
+ * @template TDb - Database record type for type-safe excludeTables
+ */
+type DefineAuthOptions<T extends AuthConfig, TDb = unknown> = {
+  /**
+   * The application name.
+   */
+  appName: string;
+  /**
+   * Audit logging configuration (server-only). Use qualified table names: "dbName.tableName".
+   */
+  auditLog?: AuditLogOptions<TDb>;
+  /**
+   * The neutral auth configuration.
+   */
+  config: T;
+  /**
+   * Full db object (container.db) for type inference.
+   */
+  db: TDb;
+  /**
+   * Primary database for Better Auth storage.
+   */
+  database: Database;
+  /**
+   * Hooks for email sending and OTP delivery.
+   */
+  hooks: RequiredHooks<T>;
+  /**
+   * Secret key for signing tokens and cookies.
+   */
+  secret: string;
+  /**
+   * Session configuration.
+   */
+  session?: AuthSessionConfig;
+} & (HasOAuthEnabled<T> extends true ? {
+  oauth: RequiredOAuth<T>;
+} : {
+  oauth?: RequiredOAuth<T>;
+}) & (HasPasskeyEnabled<T> extends true ? {
+  passkey: AuthPasskeyConfig;
+} : {
+  passkey?: AuthPasskeyConfig;
+});
+/**
+ * Defines Better Auth instance from neutral config + server dependencies.
+ */
+declare function defineAuth<T extends AuthConfig, TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>>(opts: DefineAuthOptions<T, TDb>): ReturnType<typeof betterAuth> & {
+  auditLog?: AuditLogOptions<TDb>;
+  shouldAudit(tableName: QualifiedTableNames<TDb>): boolean;
+};
+/**
+ * The auth instance type.
+ */
+type Auth<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> = ReturnType<typeof defineAuth<AuthConfig, TDb>>;
+//#endregion
+//#region src/api/cache.d.ts
+/**
+ * The cache instance type.
+ */
+type Cache = ReturnType<typeof defineCache>;
+/**
+ * Options for defining the cache.
+ */
+type DefineCacheOptions = {
+  /**
+   * Redis URL(s). Single or comma-separated for cluster.
+   */
+  url: string;
+  /**
+   * The logger instance.
+   */
+  logger: Logger;
+  /**
+   * The Keyv Redis options.
+   */
+  options?: KeyvRedisOptions;
+};
+/**
+ * Define the cache instance using shared Redis client.
+ * Connection is lazy - only connects when first cache operation is performed.
+ *
+ * Algorithm:
+ * 1. Create Redis client using defineRedisClient() (lazy connection)
+ * 2. Pass client to createKeyv() - connection happens on first use
+ *
+ * @param opts - The options for defining the cache.
+ * @returns The cache instance.
+ */
+declare function defineCache({
+  url,
+  logger,
+  options
+}: DefineCacheOptions): _keyv_redis0.Keyv<any>;
+//#endregion
+//#region src/api/config.d.ts
+/**
+ * The config base schema.
+ */
+declare const baseSchema: z.ZodObject<{
+  APP_NAME: z.ZodDefault<z.ZodString>;
+  APP_DESC: z.ZodDefault<z.ZodString>;
+  APP_VERSION: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The configuration type inferred from the merged schema.
+ */
+type Config<T extends z.ZodRawShape = {}> = z.infer<ReturnType<typeof baseSchema.extend<T>>>;
+//#endregion
+//#region src/api/event.d.ts
+/**
+ * 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>;
+};
+//#endregion
+//#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>;
+};
+declare namespace orm_d_exports {
+  export { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas };
+}
+import * as import_drizzle_orm from "drizzle-orm";
+import * as import_drizzle_seed from "drizzle-seed";
+//#endregion
+//#region src/api/storage-schema.d.ts
+/**
+ * Defines the storage schema for file attachments and blob management.
+ *
+ * @returns An object containing the schema and relations for the storage tables.
+ */
+declare function defineStorageSchema(): {
+  tables: {
+    storageBlobs: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_blobs";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        key: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        filename: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        contentType: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        metadata: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "object json";
+          data: unknown;
+          driverParam: unknown;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        serviceName: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        byteSize: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "number int53";
+          data: number;
+          driverParam: string | number;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        checksum: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+    storageAttachments: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_attachments";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        name: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        recordType: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        recordId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        blobId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+    storageVariantRecords: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_variant_records";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        blobId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        variationDigest: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+  };
+  relations: (r: orm_d_exports.RelationsBuilder<{
+    storageBlobs: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_blobs";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        key: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        filename: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        contentType: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        metadata: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "object json";
+          data: unknown;
+          driverParam: unknown;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        serviceName: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        byteSize: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "number int53";
+          data: number;
+          driverParam: string | number;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        checksum: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: false;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_blobs";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+    storageAttachments: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_attachments";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        name: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        recordType: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        recordId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        blobId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_attachments";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+    storageVariantRecords: drizzle_orm_pg_core0.PgTableWithColumns<{
+      name: "storage_variant_records";
+      schema: undefined;
+      columns: {
+        id: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: true;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        blobId: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        variationDigest: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: false;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: [string, ...string[]];
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+        createdAt: drizzle_orm_pg_core0.PgColumn<{
+          name: string;
+          tableName: "storage_variant_records";
+          dataType: "string timestamp";
+          data: string;
+          driverParam: string;
+          notNull: true;
+          hasDefault: true;
+          isPrimaryKey: false;
+          isAutoincrement: false;
+          hasRuntimeDefault: false;
+          enumValues: undefined;
+          baseColumn: never;
+          identity: undefined;
+          generated: undefined;
+        }, {}>;
+      };
+      dialect: "pg";
+    }>;
+  }>) => {
+    storageBlobs: {
+      attachments: drizzle_orm2.Many<"storageAttachments">;
+      variantRecords: drizzle_orm2.Many<"storageVariantRecords">;
+    };
+    storageAttachments: {
+      blob: drizzle_orm2.One<"storageBlobs", true>;
+    };
+    storageVariantRecords: {
+      blob: drizzle_orm2.One<"storageBlobs", true>;
+    };
+  };
+};
+/**
+ * Create a schema instance for type inference and exports.
+ */
+type StorageSchema = ReturnType<typeof defineStorageSchema>;
+/**
+ * Type for storage tables.
+ */
+type StorageTables = StorageSchema["tables"];
+/**
+ * Type for storage relations.
+ */
+type StorageRelations = ReturnType<StorageSchema["relations"]>;
+type StorageBlob = StorageTables["storageBlobs"]["$inferSelect"];
+/**
+ * Type for the storage relations config (result of defineRelations).
+ * Computed at type-level without runtime call.
+ */
+type StorageRelationsConfig = ExtractTablesWithRelations<StorageRelations, StorageTables>;
+//#endregion
+//#region src/api/workflows/generate-image-variant.d.ts
+/**
+ * Image transformations schema.
+ * Supports resize, rotate, flip, flop, sharpen, blur, grayscale, format conversion.
+ */
+declare const transformationsSchema: z.ZodObject<{
+  resize: z.ZodOptional<z.ZodObject<{
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    fit: z.ZodOptional<z.ZodEnum<{
+      fill: "fill";
+      cover: "cover";
+      contain: "contain";
+      inside: "inside";
+      outside: "outside";
+    }>>;
+    position: z.ZodOptional<z.ZodEnum<{
+      left: "left";
+      right: "right";
+      top: "top";
+      "right top": "right top";
+      "right bottom": "right bottom";
+      bottom: "bottom";
+      "left bottom": "left bottom";
+      "left top": "left top";
+      centre: "centre";
+    }>>;
+    kernel: z.ZodOptional<z.ZodEnum<{
+      nearest: "nearest";
+      linear: "linear";
+      cubic: "cubic";
+      mitchell: "mitchell";
+      lanczos2: "lanczos2";
+      lanczos3: "lanczos3";
+    }>>;
+  }, z.core.$strip>>;
+  rotate: z.ZodOptional<z.ZodNumber>;
+  flip: z.ZodOptional<z.ZodBoolean>;
+  flop: z.ZodOptional<z.ZodBoolean>;
+  sharpen: z.ZodOptional<z.ZodBoolean>;
+  blur: z.ZodOptional<z.ZodNumber>;
+  grayscale: z.ZodOptional<z.ZodBoolean>;
+  format: z.ZodOptional<z.ZodEnum<{
+    jpeg: "jpeg";
+    png: "png";
+    webp: "webp";
+    avif: "avif";
+    gif: "gif";
+  }>>;
+  quality: z.ZodOptional<z.ZodNumber>;
+  preview: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+/**
+ * Types for image transformations.
+ */
+type ImageTransformations = z.infer<typeof transformationsSchema>;
+//#endregion
+//#region src/api/storage.d.ts
+/**
+ * Database type with storage schema and relations.
+ */
+type DatabaseWithStorage = NodePgDatabase<StorageTables, StorageRelationsConfig> & {
+  $client: Pool;
+};
+/**
+ * Type of the storage service instance.
+ */
+type Storage<TDisks extends Record<string, FSDriverOptions | S3DriverOptions> = Record<string, FSDriverOptions | S3DriverOptions>, TTableNames extends string = string, TAttachments extends Partial<Record<TTableNames, readonly string[]>> = Record<never, never>> = StorageService<Extract<keyof TDisks, string>, TTableNames, TAttachments>;
+/**
+ * Helper type to extract attachment name for a specific table.
+ */
+type AttachmentName<TAttachments extends Partial<Record<string, readonly string[]>>, TTable extends string> = TTable extends keyof TAttachments ? TAttachments[TTable] extends readonly (infer N)[] ? N : string : string;
+/**
+ * Storage service for blob operations.
+ *
+ * This service uses a dual-drive architecture when configured:
+ * - `drive`: For actual file operations (upload, delete, read) using internal endpoints
+ * - `signedUrlDrive`: For generating browser-accessible signed URLs with public endpoints
+ *
+ * This allows containers to use fast internal network for operations while
+ * generating URLs that work in end-user browsers.
+ *
+ * @template TDiskNames - Union of disk names (e.g., "private" | "public")
+ * @template TTableNames - Union of table names for type-safe attachment methods
+ * @template TAttachments - Mapping of table names to valid attachment names
+ */
+declare class StorageService<TDiskNames extends string = string, TTableNames extends string = string, TAttachments extends Partial<Record<TTableNames, readonly string[]>> = Record<never, never>> {
+  /**
+   * The drive manager for file operations.
+   */
+  readonly drive: DriveManager<any>;
+  /**
+   * The database instance with storage schema and relations.
+   */
+  readonly db: DatabaseWithStorage;
+  /**
+   * The default disk name.
+   */
+  readonly defaultDisk: TDiskNames;
+  /**
+   * Cron expression for unattached blob purge schedule.
+   *
+   * @default "0 0 * * *"
+   */
+  readonly purgeCron?: string;
+  /**
+   * Secret key for signing blob IDs.
+   */
+  readonly secret?: string;
+  /**
+   * Drive manager for generating signed URLs (public endpoint).
+   */
+  readonly signedUrlDrive: DriveManager<any>;
+  constructor(drive: DriveManager<any>, db: DatabaseWithStorage, defaultDisk: TDiskNames, signedUrlDrive: DriveManager<any>, purgeCron?: string, secret?: string);
+  /**
+   * Create a blob record and upload file.
+   */
+  createBlob(file: Buffer | Uint8Array, options: {
+    filename: string;
+    contentType?: string;
+    metadata?: Record<string, any>;
+    serviceName?: TDiskNames;
+    prefix?: string;
+  }): Promise<StorageBlob>;
+  /**
+   * Get blob by ID.
+   */
+  getBlob(id: string): Promise<StorageBlob | null>;
+  /**
+   * Download blob content.
+   */
+  downloadBlob(id: string): Promise<Buffer | null>;
+  /**
+   * Delete blob and its content.
+   */
+  deleteBlob(id: string): Promise<boolean>;
+  /**
+   * Get signed URL for blob. If blob is on public service, returns permanent
+   * URL instead.
+   */
+  getSignedUrl(id: string, options?: {
+    expiresIn?: number;
+    disposition?: "inline" | "attachment";
+    filename?: string;
+  }): Promise<string | null>;
+  /**
+   * Get permanent public URL (no expiration).
+   * Works for blobs on public storage service.
+   */
+  getPublicUrl(id: string): Promise<string | null>;
+  /**
+   * Create attachment between a record and blob.
+   *
+   * @param recordType - The table name (e.g., 'users')
+   * @param recordId - The record ID
+   * @param blobId - The blob ID to attach
+   * @param name - The attachment name (e.g., 'avatar')
+   * @param replaceExisting - If true, replaces existing attachment with same name (for one-to-one)
+   */
+  createAttachment(recordType: string, recordId: string, blobId: string, name: string, replaceExisting?: boolean): Promise<{
+    id: string;
+    createdAt: string;
+    name: string;
+    recordType: string;
+    recordId: string;
+    blobId: string;
+  }>;
+  /**
+   * Get attachments for a record with their associated blobs.
+   */
+  getAttachments(recordType: string, recordId: string, name?: string): Promise<{
+    id: string;
+    createdAt: string;
+    name: string;
+    recordType: string;
+    recordId: string;
+    blobId: string;
+    blob: {
+      id: string;
+      key: string;
+      filename: string;
+      contentType: string | null;
+      metadata: unknown;
+      serviceName: string;
+      byteSize: number;
+      checksum: string | null;
+      createdAt: string;
+    } | null;
+  }[]>;
+  /**
+   * Get attachments by their IDs with associated blobs.
+   *
+   * @param attachmentIds - Array of attachment IDs to fetch.
+   */
+  getAttachmentsByIds(attachmentIds: string[]): Promise<{
+    id: string;
+    createdAt: string;
+    name: string;
+    recordType: string;
+    recordId: string;
+    blobId: string;
+    blob: {
+      id: string;
+      key: string;
+      filename: string;
+      contentType: string | null;
+      metadata: unknown;
+      serviceName: string;
+      byteSize: number;
+      checksum: string | null;
+      createdAt: string;
+    } | null;
+  }[]>;
+  /**
+   * Delete a single attachment by ID.
+   */
+  deleteAttachment(attachmentId: string): Promise<boolean>;
+  /**
+   * Delete attachments for a record (without deleting the blobs).
+   */
+  deleteAttachments(recordType: string, recordId: string, name?: string): Promise<number>;
+  /**
+   * Get direct upload credentials (for S3). Also creates a pending blob record
+   * that will be finalized after upload.
+   */
+  getDirectUploadUrl(options: {
+    contentType?: string;
+    expiresIn?: number;
+    filename: string;
+    metadata?: Record<string, any>;
+    serviceName?: TDiskNames;
+  }): Promise<{
+    blobId: string;
+    headers?: Record<string, string>;
+    key: string;
+    url: string;
+  } | null>;
+  /**
+   * Finalize a direct upload by updating blob metadata. Call this after the
+   * client has uploaded to S3.
+   */
+  finalizeDirectUpload(blobId: string, actualSize: number): Promise<void>;
+  /**
+   * Update blob metadata (for automatic extraction).
+   */
+  updateBlobMetadata(blobId: string, metadata: Record<string, any>): Promise<void>;
+  /**
+   * Get existing variant or return null.
+   */
+  getVariant(blobId: string, transformations: ImageTransformations): Promise<StorageBlob | null>;
+  /**
+   * Create variant blob and record.
+   */
+  createVariant(blobId: string, transformations: ImageTransformations, variantBuffer: Buffer): Promise<StorageBlob>;
+  /**
+   * Get blobs that have no attachments (orphaned). Useful for cleanup jobs.
+   */
+  getUnattachedBlobs(options?: {
+    olderThan?: string;
+    limit?: number;
+  }): Promise<StorageBlob[]>;
+  /**
+   * Get pending blobs that were never finalized (stuck direct uploads).
+   */
+  getPendingBlobs(olderThan?: string): Promise<StorageBlob[]>;
+  /**
+   * Purge unattached blobs.
+   */
+  purgeUnattached(olderThan?: string): Promise<number>;
+  /**
+   * Create a signed, tamper-proof reference to a blob.
+   * Use findSigned() to resolve back to blob.
+   *
+   * Algorithm:
+   * 1. Create payload with blobId and expiration timestamp
+   * 2. JSON stringify and base64url encode the payload
+   * 3. Create HMAC-SHA256 signature of the encoded payload
+   * 4. Return payload.signature format
+   */
+  signedId(blobId: string, expiresIn?: number): string;
+  /**
+   * Find blob by signed ID. Returns null if invalid or expired.
+   * Uses constant-time comparison to prevent timing attacks.
+   *
+   * Algorithm:
+   * 1. Split signed ID into payload and signature
+   * 2. Decode and recompute expected signature
+   * 3. Use timingSafeEqual for constant-time comparison
+   * 4. Check expiration timestamp
+   * 5. Return blob if valid, null otherwise
+   */
+  findSigned(signedId: string): Promise<StorageBlob | null>;
+  /**
+   * Get a single attachment handle (one-to-one relationship).
+   * Similar to Rails' `has_one_attached :avatar`.
+   *
+   * Algorithm:
+   * Returns an object with methods to manage a single attachment:
+   * - attach(): Replace existing attachment with new blob
+   * - get(): Get attached blob or null
+   * - url(): Get signed URL
+   * - variant(): Get/generate image variant
+   * - purge(): Delete attachment and blob
+   *
+   * @template TTable - The table name (must be in TTableNames)
+   */
+  one<TTable extends TTableNames>(recordType: TTable, recordId: string, name: AttachmentName<TAttachments, TTable>): {
+    /**
+     * Attach a blob to this record (replaces existing).
+     * Auto-triggers extractBlobMetadata workflow.
+     */
+    attach(blobId: string): Promise<{
+      id: string;
+      createdAt: string;
+      name: string;
+      recordType: string;
+      recordId: string;
+      blobId: string;
+    }>;
+    /** Get the attached blob or null. */
+    get(): Promise<StorageBlob | null>;
+    /** Check if a blob is attached. */
+    attached(): Promise<boolean>;
+    /** Get signed URL or null. */
+    url(options?: {
+      expiresIn?: number;
+      disposition?: "inline" | "attachment";
+    }): Promise<string | null>;
+    /** Get permanent public URL or null. */
+    publicUrl(): Promise<string | null>;
+    /** Get blob metadata or null. */
+    metadata(): Promise<Record<string, unknown> | null>;
+    /** Check if metadata has been extracted. */
+    analyzed(): Promise<boolean>;
+    /** Check if blob supports preview/variant generation. */
+    representable(): Promise<boolean>;
+    /**
+     * Get variant URL. Auto-enqueues generation if not ready.
+     * Returns URL if variant exists, null if generating.
+     */
+    variant(transformations: ImageTransformations, expiresIn?: number): Promise<string | null>;
+    /**
+     * Get preview URL. Auto-enqueues generation if not ready.
+     * Returns URL if preview exists, null if generating.
+     */
+    preview(expiresIn?: number, timeInSeconds?: number): Promise<string | null>;
+    /** Detach blob from record (keeps blob for reuse). */
+    detach(): Promise<boolean>;
+    /** Delete attachment AND blob immediately. */
+    purge(): Promise<boolean>;
+    /** Enqueue attachment and blob deletion in background. */
+    purgeLater(): Promise<boolean>;
+    /** Download blob content as Buffer. */
+    download(): Promise<Buffer | null>;
+    /** Download to temp file, run callback, auto-cleanup. */
+    open<T>(callback: (filePath: string) => Promise<T> | T): Promise<T | null>;
+    /**
+     * Smart representation - variant for images, preview for videos/PDFs.
+     * Auto-enqueues generation if not ready.
+     */
+    representation(transformations: ImageTransformations, expiresIn?: number): Promise<string | null>;
+    /** Get blob's byte size. */
+    byteSize(): Promise<number | null>;
+    /** Get blob's content type. */
+    contentType(): Promise<string | null>;
+    /** Get blob's filename. */
+    filename(): Promise<string | null>;
+    /** Get signed, tamper-proof ID for the blob. */
+    signedId(expiresIn?: number): Promise<string | null>;
+  };
+  /**
+   * Get a multiple attachment handle (one-to-many relationship).
+   * Similar to Rails' `has_many_attached :images`.
+   *
+   * Algorithm:
+   * Returns an object with methods to manage multiple attachments:
+   * - attach(): Add blobs (doesn't replace existing)
+   * - list(): Get all attached blobs
+   * - urls(): Get signed URLs for all
+   * - variants(): Get/generate variants for all
+   * - purge(): Delete all or specific attachment
+   *
+   * @template TTable - The table name (must be in TTableNames)
+   */
+  many<TTable extends TTableNames>(recordType: TTable, recordId: string, name: AttachmentName<TAttachments, TTable>): {
+    /**
+     * Attach one or more blobs (adds to existing, doesn't replace).
+     * Auto-triggers extractBlobMetadata for each blob.
+     */
+    attach(blobIds: string | string[]): Promise<{
+      id: string;
+      createdAt: string;
+      name: string;
+      recordType: string;
+      recordId: string;
+      blobId: string;
+    }[]>;
+    /** Get all attached blobs. */
+    list(): Promise<StorageBlob[]>;
+    /** Count attached blobs. */
+    count(): Promise<number>;
+    /** Get signed URLs for all blobs. */
+    urls(options?: {
+      expiresIn?: number;
+    }): Promise<string[]>;
+    /** Get public URLs for all blobs. */
+    publicUrls(): Promise<(string | null)[]>;
+    /** Get metadata for all blobs. */
+    metadata(): Promise<(Record<string, unknown> | null)[]>;
+    /** Check which blobs have been analyzed. */
+    analyzed(): Promise<boolean[]>;
+    /** Check which blobs support preview/variants. */
+    representable(): Promise<boolean[]>;
+    /** Get variant URLs for all blobs. Auto-enqueues if not ready. */
+    variants(transformations: ImageTransformations, expiresIn?: number): Promise<(string | null)[]>;
+    /** Get preview URLs for all blobs. Auto-enqueues if not ready. */
+    previews(expiresIn?: number, timeInSeconds?: number): Promise<(string | null)[]>;
+    /** Detach specific blob or all blobs (keeps blobs for reuse). */
+    detach(blobId?: string): Promise<number>;
+    /** Delete specific or all attachments AND blobs immediately. */
+    purge(blobId?: string): Promise<number>;
+    /** Enqueue specific or all attachments for background deletion. */
+    purgeLater(blobId?: string): Promise<number>;
+    /** Download all blobs as Buffers. */
+    download(): Promise<Buffer[]>;
+    /** Download each blob to temp file, run callback for each. */
+    open<T>(callback: (filePath: string, blob: StorageBlob) => Promise<T> | T): Promise<T[]>;
+    /**
+     * Smart representations - variant for images, preview for videos/PDFs.
+     * Auto-enqueues generation if not ready.
+     */
+    representations(transformations: ImageTransformations, expiresIn?: number): Promise<(string | null)[]>;
+    /** Get byte sizes for all blobs. */
+    byteSizes(): Promise<number[]>;
+    /** Get content types for all blobs. */
+    contentTypes(): Promise<(string | null)[]>;
+    /** Get filenames for all blobs. */
+    filenames(): Promise<string[]>;
+    /** Get signed IDs for all blobs. */
+    signedIds(expiresIn?: number): Promise<string[]>;
+  };
+}
+//#endregion
+//#region src/api/container.d.ts
+/**
+ * Server configuration for the HTTP server.
+ */
+interface ServerConfig {
+  /**
+   * The host address the server will bind to.
+   *
+   * @default "0.0.0.0"
+   */
+  host?: string;
+  /**
+   * The port number the server will listen on.
+   */
+  port: number;
+  /**
+   * Request timeout in milliseconds. Requests exceeding this duration
+   * will receive a 408 Request Timeout response.
+   *
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * Maximum request body size for JSON and URL-encoded payloads.
+   * Supports bytes.js format strings (e.g., "1mb", "500kb", "10mb").
+   *
+   * @default "1mb"
+   */
+  bodyLimit?: string;
+  /**
+   * The path for the health check endpoint.
+   *
+   * @default "/health"
+   */
+  healthPath?: string;
+  /**
+   * CORS configuration. Omit or set to undefined to disable.
+   *
+   * @example
+   * cors: { origin: "https://example.com", credentials: true }
+   */
+  cors?: CorsOptions;
+  /**
+   * Security headers configuration (via helmet). Omit or set to undefined to disable.
+   * Recommended for production deployments.
+   *
+   * @example
+   * helmet: { contentSecurityPolicy: false }  // Enable with CSP disabled
+   * helmet: {}  // Enable with all defaults
+   */
+  helmet?: HelmetOptions;
+  /**
+   * Rate limiting configuration. Array of express-rate-limit options.
+   * Each config is applied as a separate middleware - use `skip` function for path-specific limits.
+   * Redis store is automatically configured if `redisUrl` is provided.
+   *
+   * @example
+   * // Global rate limit
+   * rateLimit: [{ windowMs: 60000, limit: 100 }]
+   *
+   * @example
+   * // Path-specific rate limits
+   * rateLimit: [
+   *   { windowMs: 900000, limit: 5, skip: (req) => !req.path.startsWith("/api/auth") },
+   *   { windowMs: 60000, limit: 100 },  // Default for all other routes
+   * ]
+   */
+  rateLimit?: Options[];
+  /**
+   * Redis URL for rate limiting store (for multi-instance deployments).
+   * Server auto-connects and cleans up on shutdown.
+   * If omitted, uses in-memory store (not suitable for production clusters).
+   *
+   * @example
+   * redisUrl: "redis://localhost:6379"
+   */
+  redisUrl?: string;
+}
+/**
+ * Worker configuration for the DBOS workflow worker.
+ */
+interface WorkerConfig {
+  /**
+   * The system database URL for DBOS.
+   */
+  dbUrl: string;
+}
+/**
+ * The base application container type that holds required services like
+ * config, databases, and caches.
+ */
+interface AppContainer<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> {
+  /**
+   * The application auth configuration.
+   */
+  auth: Auth<TDb>;
+  /**
+   * A map of caches available in the application.
+   */
+  cache: Record<string, Cache>;
+  /**
+   * The application configuration.
+   */
+  config: Config;
+  /**
+   * A map of databases available in the application.
+   */
+  db: TDb;
+  /**
+   * The i18n instance for internationalization.
+   */
+  i18n: i18n;
+  /**
+   * The logger instance for logging messages.
+   */
+  logger: Logger;
+  /**
+   * The event bus for in-memory and Redis pub/sub messaging.
+   */
+  eventBus: EventBus;
+  /**
+   * The mailer instance for sending emails.
+   */
+  mailer: Mailer;
+  /**
+   * Server configuration for the HTTP server.
+   */
+  server: ServerConfig;
+  /**
+   * A map of storage services available in the application.
+   */
+  storage: Record<"primary", Storage> & Record<string, Storage>;
+  /**
+   * Worker configuration for the DBOS workflow worker.
+   */
+  worker: WorkerConfig;
+}
+/**
+ * Global namespace for user container augmentation.
+ * Users can extend Container interface in their container.ts file.
+ */
+declare global {
+  namespace AppOS {
+    interface Container {}
+  }
+}
+/**
+ * The container type used throughout the application.
+ * Merges base AppContainer with user's custom Container augmentations.
+ */
+type Container = AppContainer & AppOS.Container;
+//#endregion
+//#region src/cli/context.d.ts
+/**
+ * Command context providing beautiful output, prompts, and utilities.
+ * Uses @clack/prompts for consistent, professional CLI formatting.
+ *
+ * @template C - Container type (defaults to base Container)
+ * @template A - Arguments type inferred from command's Zod args schema
+ * @template O - Options type inferred from command's Zod opts schema
+ */
+interface CommandContext<C extends Container = Container, A = readonly unknown[], O = Record<string, unknown>> {
+  /**
+   * The parsed command-line arguments.
+   * Type is inferred from the command's Zod args schema.
+   */
+  readonly args: A;
+  /**
+   * Prompts the user for single-line text input.
+   * @see https://www.clack.cc for prompt options
+   */
+  ask: typeof p.text;
+  /**
+   * Displays a cancellation message and exits the process with code 0.
+   * @param message - Optional cancellation message (defaults to "Cancelled")
+   */
+  cancel(message?: string): never;
+  /**
+   * Prompts the user for dropdown selection from a list of options.
+   * @see https://www.clack.cc for prompt options
+   */
+  choice: typeof p.select;
+  /**
+   * Releases all container resources including database connections and cache clients.
+   * Must be called before the command exits to prevent resource leaks.
+   */
+  cleanup(): Promise<void>;
+  /**
+   * Displays a dimmed comment line for secondary information.
+   * @param message - The comment text to display
+   */
+  comment(message: string): void;
+  /**
+   * Prompts the user for yes/no confirmation.
+   * @see https://www.clack.cc for prompt options
+   */
+  confirm: typeof p.confirm;
+  /**
+   * The dependency injection container providing access to services.
+   * Includes database connections, cache clients, logger, mailer, and configuration.
+   */
+  readonly container: C;
+  /**
+   * Displays an error message with the error symbol.
+   * @param message - The error message to display
+   */
+  error(message: string): void;
+  /**
+   * Executes a shell command asynchronously.
+   * @param command - The command to execute
+   * @param args - Array of command arguments
+   * @throws Error if the command exits with a non-zero code
+   */
+  exec(command: string, args: string[]): Promise<void>;
+  /**
+   * Displays an error message and terminates the process with exit code 1.
+   * @param message - The error message to display before exiting
+   */
+  fail(message: string): never;
+  /**
+   * Groups multiple prompts together for sequential execution.
+   * @see https://www.clack.cc for group options
+   */
+  group: typeof p.group;
+  /**
+   * Displays an informational message with the info symbol.
+   * @param message - The info message to display
+   */
+  info(message: string): void;
+  /**
+   * Displays the command intro header.
+   * @param title - The command name or title to display
+   */
+  intro(title: string): void;
+  /**
+   * Checks if a prompt result indicates user cancellation (Ctrl+C).
+   * @param value - The prompt result to check
+   * @returns True if the user cancelled the prompt
+   */
+  isCancel: typeof p.isCancel;
+  /**
+   * Displays a plain text line.
+   * @param message - The text to display
+   */
+  line(message: string): void;
+  /**
+   * Prompts the user to select multiple options from a list.
+   * @see https://www.clack.cc for multiselect options
+   */
+  multiselect: typeof p.multiselect;
+  /**
+   * Displays a formatted note box with optional title.
+   * @param message - The note content
+   * @param title - Optional title for the note
+   */
+  note(message: string, title?: string): void;
+  /**
+   * The parsed command-line options.
+   * Type is inferred from the command's Zod opts schema.
+   */
+  readonly opts: O;
+  /**
+   * Displays the command outro footer.
+   * @param message - Optional completion message (defaults to "Done")
+   */
+  outro(message?: string): void;
+  /**
+   * Prompts the user for password input with hidden characters.
+   * @see https://www.clack.cc for prompt options
+   */
+  secret: typeof p.password;
+  /**
+   * Executes an async function while displaying an animated spinner.
+   * Use for long-running operations like starting containers.
+   * @template T - Return type of the task function
+   * @param message - Message to display while spinning
+   * @param fn - Async function to execute
+   * @returns The result of the task function
+   */
+  spinner<T>(message: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Displays a step message indicating progress.
+   * @param message - The step description
+   */
+  step(message: string): void;
+  /**
+   * Displays a success message with the success symbol.
+   * @param message - The success message to display
+   */
+  success(message: string): void;
+  /**
+   * Displays data in a formatted note box as a table.
+   * @param headers - Array of column header strings
+   * @param rows - 2D array of cell values
+   */
+  table(headers: string[], rows: string[][]): void;
+  /**
+   * Executes an async function and displays the result with timing.
+   * @template T - Return type of the task function
+   * @param name - Display name for the task
+   * @param fn - Async function to execute
+   * @returns The result of the task function
+   */
+  task<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Displays a task status line without executing any function.
+   * @param name - Display name for the task
+   * @param status - Status text to display
+   */
+  taskStatus(name: string, status: string): void;
+  /**
+   * Displays a warning message with the warning symbol.
+   * @param message - The warning message to display
+   */
+  warn(message: string): void;
+}
+//#endregion
+//#region src/cli/command.d.ts
+/**
+ * The command interface.
+ */
+interface Command<C extends Container, A = readonly unknown[], O = Record<string, unknown>> {
+  aliases: string[];
+  description: string;
+  devOnly: boolean;
+  args: z.ZodTuple<readonly [z.ZodTypeAny, ...z.ZodTypeAny[]], z.ZodTypeAny | null> | z.ZodArray<z.ZodTypeAny>;
+  opts: z.ZodObject<z.ZodRawShape>;
+  run: (ctx: CommandContext<C, A, O>) => Promise<void>;
+}
+/**
+ * Define a CLI command with type-safe arguments and options.
+ *
+ * The command name is automatically derived from the filename relative to the commands directory:
+ * - `<APPOS_DIR>/<COMMANDS_DIR>/db/push.ts` → `db:push`
+ * - `<APPOS_DIR>/<COMMANDS_DIR>/dev.ts` → `dev`
+ *
+ * Where:
+ * - `APPOS_DIR` defaults to "appos" (see constants.ts)
+ * - `COMMANDS_DIR` defaults to "commands" (see constants.ts)
+ *
+ * @example
+ * ```typescript
+ * // appos/commands/db/migrate.ts
+ * import { defineCommand } from "appos/cli";
+ * import { z } from "appos/zod";
+ *
+ * export default defineCommand({
+ *   description: "Run database migrations",
+ *   args: z.tuple([]),
+ *   opts: z.object({
+ *     dry: z.boolean().default(false)
+ *   }),
+ *   async run(args, opts, container) {
+ *     await container.db.primary.migrate({ dryRun: opts.dry });
+ *   }
+ * });
+ * ```
+ */
+declare function defineCommand<C extends Container = Container, ASchema extends z.ZodSchema<unknown> | undefined = undefined, OSchema extends z.ZodSchema<unknown> | undefined = undefined>(def: {
+  aliases?: string[];
+  description: string;
+  devOnly?: boolean;
+  args: ASchema;
+  opts: OSchema;
+  run: (ctx: CommandContext<C, ASchema extends z.ZodSchema<infer A> ? A : readonly unknown[], OSchema extends z.ZodSchema<infer O> ? O : Record<string, unknown>>) => Promise<void>;
+}): Command<C, ASchema extends z.ZodSchema<infer A> ? A : readonly unknown[], OSchema extends z.ZodSchema<infer O> ? O : Record<string, unknown>>;
+//#endregion
 export { type Command, type CommandContext, defineCommand };