zeti-framework-backend 0.2.4

package/dist/config-VWgz0Iq_.d.ts

@@ -0,0 +1,647 @@
+import * as hono from 'hono';
+import { Context, Next } from 'hono';
+import Redis, { RedisOptions } from 'ioredis';
+import { HTTPException } from 'hono/http-exception';
+
+/**
+ * Tipo da função do Worker
+ * Recebe o db e opcionalmente o tenantId
+ */
+type WorkerFn = (db: any, tenantId?: string) => Promise<void> | void;
+/**
+ * Configuração de um Worker individual (quando precisa de opções extras)
+ */
+interface WorkerConfigObject {
+    /**
+     * Função que será executada periodicamente
+     */
+    fn: WorkerFn;
+    /**
+     * Intervalo de execução em segundos
+     * @default 30
+     */
+    intervalSeconds?: number;
+    /**
+     * Se true, executa para cada tenant separadamente (multi-tenant)
+     * @default false
+     */
+    multiTenant?: boolean;
+    /**
+     * Se true, executa imediatamente ao iniciar
+     * @default true
+     */
+    runImmediately?: boolean;
+}
+/**
+ * Worker pode ser apenas a função ou um objeto com configurações
+ *
+ * @example Apenas função (usa defaults)
+ * ```typescript
+ * workers: {
+ *   email: emailWorker,
+ * }
+ * ```
+ *
+ * @example Com configurações
+ * ```typescript
+ * workers: {
+ *   email: {
+ *     fn: emailWorker,
+ *     intervalSeconds: 60,
+ *   },
+ * }
+ * ```
+ */
+type WorkerConfig = WorkerFn | WorkerConfigObject;
+/**
+ * Configuração de workers no zetiConfig
+ *
+ * @example
+ * ```typescript
+ * workers: {
+ *   // Apenas a função (usa intervalSeconds: 30 por padrão)
+ *   email: emailWorker,
+ *
+ *   // Com configurações customizadas
+ *   sync: {
+ *     fn: syncWorker,
+ *     intervalSeconds: 60,
+ *     multiTenant: true,
+ *   },
+ * }
+ * ```
+ */
+type WorkersConfig = Record<string, WorkerConfig>;
+
+/**
+ * Redis Client para o Zeti Framework
+ *
+ * Fornece um cliente Redis singleton com configuração flexível
+ * e integração com o ciclo de vida do framework.
+ */
+
+interface RedisConfig {
+    /** URL de conexão Redis (ex: redis://localhost:6379) */
+    url?: string;
+    /** Host do Redis (default: localhost) */
+    host?: string;
+    /** Porta do Redis (default: 6379) */
+    port?: number;
+    /** Senha do Redis */
+    password?: string;
+    /** Número do database (default: 0) */
+    db?: number;
+    /** Prefixo para todas as chaves (ex: 'auth:') */
+    keyPrefix?: string;
+    /** Máximo de retries por request (default: 3) */
+    maxRetriesPerRequest?: number;
+    /** Verificar conexão ao iniciar (default: true) */
+    enableReadyCheck?: boolean;
+    /** Conectar sob demanda (default: false) */
+    lazyConnect?: boolean;
+    /** TLS options */
+    tls?: RedisOptions['tls'];
+}
+/**
+ * Inicializa o cliente Redis com a configuração fornecida.
+ *
+ * **Fail-Fast**: Se o Redis não conseguir conectar, a aplicação falha ao iniciar.
+ * Isso garante que se o Redis está configurado, ele DEVE estar disponível.
+ *
+ * @param config - Configuração do Redis
+ * @returns Promise com a instância do cliente Redis
+ * @throws Error se não conseguir conectar ao Redis
+ */
+declare function initRedis(config: RedisConfig): Promise<Redis>;
+/**
+ * Retorna o cliente Redis singleton.
+ *
+ * @throws Error se o Redis não foi inicializado
+ * @returns Instância do cliente Redis (ioredis)
+ */
+declare function getRedisClient(): Redis;
+/**
+ * Fecha a conexão Redis graciosamente.
+ */
+declare function closeRedis(): Promise<void>;
+/**
+ * Retorna a configuração atual do Redis.
+ */
+declare function getRedisConfig(): RedisConfig | null;
+
+/**
+ * Tipos próprios para Prisma
+ *
+ * Estes tipos são usados para evitar dependência direta de @prisma/client
+ * durante o build da biblioteca, já que Prisma é uma peer dependency.
+ *
+ * O usuário passa o PrismaClient real como generic, então o TypeScript
+ * vai inferir os tipos corretos em tempo de uso.
+ */
+type PrismaClientBase = {
+    $connect: () => Promise<void>;
+    $disconnect: () => Promise<void>;
+    $transaction: <T>(fn: (client: any) => Promise<T>) => Promise<T>;
+    $queryRaw: any;
+    $executeRaw: any;
+    [key: string]: any;
+};
+declare namespace Prisma {
+    interface PrismaClientKnownRequestError extends Error {
+        code: string;
+        meta?: any;
+        clientVersion?: string;
+    }
+    interface PrismaClientValidationError extends Error {
+        message: string;
+    }
+    interface PrismaClientInitializationError extends Error {
+        errorCode?: string;
+        clientVersion?: string;
+    }
+    interface PrismaClientRustPanicError extends Error {
+        requestId?: string;
+        clientVersion?: string;
+    }
+    type PrismaClientError = PrismaClientKnownRequestError | PrismaClientValidationError | PrismaClientInitializationError | PrismaClientRustPanicError;
+}
+
+interface ValidationError {
+    field: string;
+    errors: string[];
+}
+interface ErrorTrace {
+    path: string;
+    method: string;
+    timestamp: string;
+    errorType: string;
+    stack?: string;
+}
+interface ErrorResponse {
+    data: null;
+    status: number;
+    message: string;
+    validationErrors?: Record<string, {
+        errors: string[];
+    }>;
+    trace?: ErrorTrace;
+}
+interface ZetiErrorHandlerConfig {
+    formatError?: (error: any, context: Context) => ErrorResponse;
+    logError?: (error: any, context: Context) => void;
+    /** Incluir trace de erro na resposta (default: true em dev, false em prod) */
+    includeTrace?: boolean;
+    /** Incluir stack trace na resposta (default: false) */
+    includeStack?: boolean;
+}
+declare function createErrorHandler(config?: ZetiErrorHandlerConfig): (c: Context, next: () => Promise<void>) => Promise<(Response & hono.TypedResponse<{
+    data: null;
+    status: number;
+    message: string;
+    validationErrors?: {
+        [x: string]: {
+            errors: string[];
+        };
+    } | undefined;
+    trace?: {
+        path: string;
+        method: string;
+        timestamp: string;
+        errorType: string;
+        stack?: string | undefined;
+    } | undefined;
+}, any, "json">) | undefined>;
+declare function handleError(exception: Error | HTTPException | Prisma.PrismaClientKnownRequestError | ValidationError[] | any, config?: ZetiErrorHandlerConfig, trace?: ErrorTrace, context?: {
+    tenant?: string;
+}): ErrorResponse;
+
+type Middleware = (c: Context, next: Next) => Promise<Response | void> | Response | void;
+interface ZetiDatabaseConfig {
+    /**
+     * Conexões de banco de dados.
+     *
+     * Para single-tenant: { default: "connection_string" }
+     * Para multi-tenant: { tenantName: "connection_string", ... }
+     *
+     * O valor do header x-tenant (ou headerName configurado) é usado como chave.
+     *
+     * @example
+     * ```typescript
+     * connections: {
+     *   mulherdevalor: env("TENANT_MULHERDEVALOR_DATABASE_URL"),
+     *   outroTenant: env("TENANT_OUTRO_DATABASE_URL"),
+     * }
+     * ```
+     */
+    connections: Record<string, string>;
+    /**
+     * Resolver dinâmico para conexões não encontradas em `connections`.
+     * Útil para cenários onde os tenants são criados dinamicamente.
+     */
+    resolver?: (tenantId: string) => Promise<string> | string;
+    /** Configuração de cache de conexões */
+    cache?: {
+        maxClients?: number;
+        ttl?: number;
+        cleanupInterval?: number;
+    };
+}
+interface ZetiPrismaConfig {
+    adapter?: 'pg' | 'mysql' | 'sqlite' | 'custom';
+    logLevel?: ('query' | 'error' | 'warn')[];
+    connectionPool?: {
+        max?: number;
+        min?: number;
+        idleTimeoutMillis?: number;
+        connectionTimeoutMillis?: number;
+    };
+}
+/**
+ * Estratégia de conexão com o banco de dados.
+ *
+ * - `single`: Usa DATABASE_URL único, zero overhead de multi-tenancy
+ * - `dynamic`: Usa tenantSelector para resolver URL e tenantId por request
+ */
+type ConnectionStrategy = 'single' | 'dynamic';
+/**
+ * Resultado do tenantSelector.
+ *
+ * @example Row-level isolation (mesmo banco)
+ * ```typescript
+ * { tenantId: 'abc-123' }
+ * ```
+ *
+ * @example Database sharding (bancos diferentes)
+ * ```typescript
+ * { databaseUrl: process.env.DB_TENANT_A }
+ * ```
+ *
+ * @example Combinado
+ * ```typescript
+ * { tenantId: 'abc-123', databaseUrl: process.env.DB_TENANT_A }
+ * ```
+ */
+interface TenantSelection {
+    /** ID do tenant para filtro automático via $extends */
+    tenantId?: string;
+    /** URL do banco de dados (se diferente de DATABASE_URL) */
+    databaseUrl?: string;
+}
+/**
+ * Escopo de segurança definido pelo middleware.
+ *
+ * Quando definido via `context.set('securityScope', scope)`, o framework
+ * automaticamente aplica validações em todas as operações do Prisma:
+ *
+ * - **Leitura**: Adiciona campos ao WHERE (filtro automático)
+ * - **Criação**: VALIDA que os campos passados correspondem ao escopo
+ * - **Atualização/Deleção**: Adiciona campos ao WHERE (proteção)
+ *
+ * @example No middleware
+ * ```typescript
+ * context.set('securityScope', {
+ *   tenantId: tenant.id,
+ *   productId: product.id,
+ * });
+ * ```
+ *
+ * @example No controller (proteção automática)
+ * ```typescript
+ * // Isso vai FALHAR se tenantId for diferente do escopo:
+ * await db.role.create({ data: { name: 'Admin', tenantId: 'outro-tenant' } });
+ * // Error: [Zeti Security] Campo 'tenantId' inválido...
+ *
+ * // Isso funciona:
+ * await db.role.create({ data: { name: 'Admin', tenantId: scopeTenantId } });
+ * ```
+ */
+interface SecurityScope {
+    /** ID do tenant - obrigatório em creates, filtrado em reads */
+    tenantId?: string;
+    /** ID do produto - obrigatório em creates, filtrado em reads */
+    productId?: string;
+    /** Campos adicionais customizados */
+    [key: string]: string | undefined;
+}
+/**
+ * Configuração de conexão do Prisma com suporte a multi-tenancy.
+ *
+ * @example Single database (app simples)
+ * ```typescript
+ * prisma: {
+ *   client: PrismaClient,
+ *   connectionStrategy: 'single',
+ * }
+ * ```
+ *
+ * @example Multi-tenant com row-level isolation
+ * ```typescript
+ * prisma: {
+ *   client: PrismaClient,
+ *   connectionStrategy: 'dynamic',
+ *   tenantSelector: (context) => ({
+ *     tenantId: context.req.header('x-tenant-id'),
+ *   }),
+ * }
+ * ```
+ *
+ * @example Multi-database (sharding)
+ * ```typescript
+ * prisma: {
+ *   client: PrismaClient,
+ *   connectionStrategy: 'dynamic',
+ *   tenantSelector: (context) => {
+ *     const product = context.req.header('x-product-name');
+ *     return {
+ *       tenantId: context.req.header('x-tenant-id'),
+ *       databaseUrl: process.env[`DB_${product?.toUpperCase()}`],
+ *     };
+ *   },
+ * }
+ * ```
+ */
+interface ZetiPrismaConnectionConfig<TPrisma = any> {
+    /** Classe do PrismaClient do projeto */
+    client: new (...args: any[]) => TPrisma;
+    /**
+     * Estratégia de conexão.
+     * - `single`: Usa DATABASE_URL, sem multi-tenancy
+     * - `dynamic`: Usa tenantSelector para resolver conexão
+     * @default 'single'
+     */
+    connectionStrategy?: ConnectionStrategy;
+    /**
+     * Função que resolve tenantId e/ou databaseUrl por request.
+     * Obrigatório se connectionStrategy = 'dynamic'.
+     */
+    tenantSelector?: (context: Context) => TenantSelection | Promise<TenantSelection>;
+    /**
+     * Extension customizada aplicada após o filtro de tenant.
+     * Permite encadear $extends adicionais.
+     */
+    customExtension?: (baseClient: TPrisma, selection: TenantSelection) => TPrisma;
+}
+interface ZetiCorsConfig {
+    enabled?: boolean;
+    origin?: string | string[] | ((origin: string) => boolean);
+    allowMethods?: string[];
+    allowHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+interface ZetiSwaggerHeaderParam {
+    name: string;
+    description?: string;
+    required?: boolean;
+    example?: string;
+}
+interface ZetiSwaggerConfig {
+    enabled?: boolean;
+    title: string;
+    version?: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    outputPath?: string;
+    generateOnBuild?: boolean;
+    uiPath?: string;
+    docPath?: string;
+    globalHeaders?: ZetiSwaggerHeaderParam[];
+}
+/**
+ * Configuração de headers customizados.
+ *
+ * Cada header declarado aqui:
+ * - Será acessível via `c.req.header(name)`
+ * - Aparecerá automaticamente como parâmetro opcional no Swagger
+ *
+ * @example
+ * ```typescript
+ * headers: {
+ *   tenant: "x-tenant",           // Header para multi-tenancy
+ *   timezone: "timezone",         // Header de timezone
+ *   apiKey: "x-internal-api-key", // Header customizado
+ * }
+ * ```
+ */
+interface ZetiHeadersConfig {
+    /** Header de tenant para multi-tenancy. Default: "x-tenant" */
+    tenant?: string;
+    /** Header de timezone. Default: "timezone" */
+    timezone?: string;
+    /** Permite qualquer header customizado adicional */
+    [key: string]: string | undefined;
+}
+interface ZetiTenantConfig {
+    enabled?: boolean;
+    required?: boolean;
+    headerName?: string;
+    defaultDatabase?: string;
+}
+interface ZetiMiddlewareConfig {
+    global?: Middleware[];
+    named?: Record<string, Middleware | ((...args: any[]) => Middleware)>;
+}
+/** Configuração de desenvolvimento do projeto */
+interface ZetiDevConfig {
+    /** Porta do servidor. Default: 3333 */
+    port?: number;
+    /** Caminho do docker-compose. Default: "../infra/local/docker-compose.yaml" */
+    dockerCompose?: string;
+    /** Portas para limpar antes de iniciar. Default: [3333, 5432] */
+    ports?: number[];
+    /** Configuração do framework local (para desenvolvimento) */
+    framework?: {
+        /** Caminho do framework. Default: "../_developer/_npm" */
+        path?: string;
+        /** Observar mudanças no framework. Default: true */
+        watch?: boolean;
+    };
+}
+
+/** Configuração interna completa do Zeti (após normalização) */
+interface ZetiConfigInternal<TPrisma = any> {
+    databases: ZetiDatabaseConfig;
+    specialDatabases?: Record<string, string>;
+    prisma: ZetiPrismaConfig;
+    /** Nova configuração de conexão Prisma com modos de operação */
+    prismaConnection?: ZetiPrismaConnectionConfig<TPrisma>;
+    swagger: Required<Omit<ZetiSwaggerConfig, 'globalHeaders' | 'description'>> & {
+        globalHeaders?: ZetiSwaggerHeaderParam[];
+        description?: string;
+    };
+    tenant?: ZetiTenantConfig;
+    cors: Required<Omit<ZetiCorsConfig, 'maxAge'>> & {
+        maxAge?: number;
+    };
+    logger: boolean;
+    debug: boolean;
+    headers?: ZetiHeadersConfig;
+    middlewares: ZetiMiddlewareConfig;
+    errorHandler: ZetiErrorHandlerConfig | boolean;
+    hooks?: {
+        onRouteRegister?: (route: any) => void;
+        onRequest?: (context: any) => void | Promise<void>;
+        onResponse?: (context: any, response: any) => any;
+    };
+    dev: Required<ZetiDevConfig>;
+    workers?: WorkersConfig;
+}
+/**
+ * Configuração do Zeti Framework.
+ *
+ * A maioria das opções tem defaults sensatos - você só precisa configurar o que for diferente.
+ *
+ * @example Configuração mínima
+ * ```typescript
+ * defineZetiConfig({
+ *   swagger: { title: "My API" },
+ * });
+ * ```
+ */
+interface ZetiConfig {
+    /**
+     * URL de conexão do banco de dados (para apps single-tenant).
+     * Se não informado, usa DATABASE_URL do .env automaticamente.
+     */
+    databaseUrl?: string;
+    /**
+     * Configuração de databases (para apps multi-tenant).
+     * Se não informado, o framework usa databaseUrl ou DATABASE_URL do .env.
+     */
+    databases?: ZetiDatabaseConfig;
+    specialDatabases?: Record<string, string>;
+    /** Configuração do Prisma. Opcional - usa defaults sensatos. */
+    prisma?: ZetiPrismaConfig;
+    /**
+     * Configuração do Swagger. Apenas `title` é obrigatório.
+     * Defaults: enabled=true, version="1.0.0", uiPath="/swagger", docPath="/swagger/doc"
+     */
+    swagger: {
+        /** Título da API (obrigatório) */
+        title: string;
+        /** Versão da API. Default: "1.0.0" */
+        version?: string;
+        /** Descrição da API */
+        description?: string;
+        /** Servidores. Default: [{ url: "http://localhost:{port}" }] */
+        servers?: Array<{
+            url: string;
+            description?: string;
+        }>;
+        /** Habilitar Swagger UI. Default: true */
+        enabled?: boolean;
+        /** Caminho do arquivo de schemas. Default: "./.zeti/generated/swagger-schemas.ts" */
+        outputPath?: string;
+        /** Gerar schemas no build. Default: true */
+        generateOnBuild?: boolean;
+        /** Caminho da UI. Default: "/swagger" */
+        uiPath?: string;
+        /** Caminho do JSON. Default: "/swagger/doc" */
+        docPath?: string;
+        /** Headers globais */
+        globalHeaders?: ZetiSwaggerHeaderParam[];
+    };
+    /** Configuração de multi-tenancy. Se não informado, tenant fica desabilitado. */
+    tenant?: ZetiTenantConfig;
+    /**
+     * Configuração de CORS. Opcional - usa defaults permissivos para desenvolvimento.
+     * Defaults: enabled=true, origin="*", credentials=true, allowHeaders=["*"]
+     */
+    cors?: ZetiCorsConfig;
+    /** Habilitar logger de requisições. Default: true */
+    logger?: boolean;
+    /** Habilitar logs de debug. Default: false */
+    debug?: boolean;
+    /** Configuração de headers customizados */
+    headers?: ZetiHeadersConfig;
+    /** Configuração de middlewares */
+    middlewares?: ZetiMiddlewareConfig;
+    /** Configuração do error handler. Default: {} (habilitado com defaults) */
+    errorHandler?: ZetiErrorHandlerConfig | boolean;
+    /** Hooks do ciclo de vida */
+    hooks?: {
+        onRouteRegister?: (route: any) => void;
+        onRequest?: (context: any) => void | Promise<void>;
+        onResponse?: (context: any, response: any) => any;
+    };
+    /**
+     * Configuração de desenvolvimento (usado pelo CLI `zeti dev`).
+     * Opcional - usa defaults sensatos.
+     */
+    dev?: ZetiDevConfig;
+    /**
+     * Workers que serão iniciados automaticamente com o servidor.
+     *
+     * @example
+     * ```typescript
+     * workers: {
+     *   email: {
+     *     fn: async (db) => {
+     *       const emails = await db.email.findMany({ where: { status: 'PENDING' } });
+     *       // processar...
+     *     },
+     *     intervalSeconds: 30,
+     *   },
+     *   sync: {
+     *     fn: async (db, tenantId) => {
+     *       // sincroniza dados do tenant
+     *     },
+     *     intervalSeconds: 60,
+     *     multiTenant: true,
+     *   },
+     * }
+     * ```
+     */
+    workers?: WorkersConfig;
+    /**
+     * Configuração do Redis.
+     *
+     * Se fornecido, o cliente Redis será inicializado automaticamente
+     * e disponibilizado via `import { redis } from '@zeti/app'`.
+     *
+     * @example
+     * ```typescript
+     * redis: {
+     *   host: process.env.REDIS_HOST ?? 'localhost',
+     *   port: parseInt(process.env.REDIS_PORT ?? '6379'),
+     *   keyPrefix: 'myapp:',
+     * }
+     * ```
+     */
+    redis?: RedisConfig;
+}
+
+/**
+ * Define a configuração do Zeti Framework.
+ *
+ * Detecta automaticamente se é single-tenant ou multi-tenant e aplica defaults sensatos.
+ *
+ * @example Configuração mínima (single-tenant)
+ * ```typescript
+ * export const zetiConfig = defineZetiConfig({
+ *   swagger: { title: "My API" },
+ * });
+ * ```
+ *
+ * @example Multi-tenant
+ * ```typescript
+ * export const zetiConfig = defineZetiConfig({
+ *   databases: {
+ *     connections: {
+ *       mulherdevalor: env("TENANT_MULHERDEVALOR_DATABASE_URL"),
+ *       outroTenant: env("TENANT_OUTRO_DATABASE_URL"),
+ *     },
+ *   },
+ *   tenant: { enabled: true, required: true },
+ *   swagger: { title: "Multi-tenant API" },
+ * });
+ * ```
+ */
+declare function defineZetiConfig(config: ZetiConfig, options?: {
+    port?: number;
+}): ZetiConfigInternal;
+
+export { type ConnectionStrategy as C, type ErrorResponse as E, type Middleware as M, Prisma as P, type RedisConfig as R, type SecurityScope as S, type TenantSelection as T, type ValidationError as V, type WorkerConfig as W, type ZetiSwaggerConfig as Z, type ZetiConfigInternal as a, type ZetiPrismaConnectionConfig as b, type ErrorTrace as c, type PrismaClientBase as d, type WorkersConfig as e, type ZetiConfig as f, type ZetiCorsConfig as g, type ZetiDatabaseConfig as h, type ZetiDevConfig as i, type ZetiErrorHandlerConfig as j, type ZetiHeadersConfig as k, type ZetiMiddlewareConfig as l, type ZetiPrismaConfig as m, type ZetiSwaggerHeaderParam as n, type ZetiTenantConfig as o, closeRedis as p, createErrorHandler as q, defineZetiConfig as r, getRedisClient as s, getRedisConfig as t, handleError as u, initRedis as v };