@atlas-id/contracts 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,911 @@
+import { z } from 'zod';
+
+/**
+ * Representa una versión semántica en formato MAJOR.MINOR.PATCH
+ *
+ * @example
+ * ```typescript
+ * const version: SemanticVersion = '1.2.3';
+ * ```
+ */
+type SemanticVersion = `${number}.${number}.${number}`;
+/**
+ * Estructura que contiene un payload con su versión asociada.
+ * Útil para versionado de datos y compatibilidad entre versiones.
+ *
+ * @template TPayload - Tipo del payload versionado
+ */
+type Versioned<TPayload> = {
+    version: SemanticVersion;
+    payload: TPayload;
+};
+/**
+ * Valida si una cadena de texto cumple con el formato de versión semántica.
+ *
+ * @param version - Cadena a validar
+ * @returns true si es una versión semántica válida, false en caso contrario
+ *
+ * @example
+ * ```typescript
+ * isValidSemanticVersion('1.2.3'); // true
+ * isValidSemanticVersion('1.2'); // false
+ * isValidSemanticVersion('invalid'); // false
+ * ```
+ */
+declare function isValidSemanticVersion(version: string): version is SemanticVersion;
+/**
+ * Parsea una versión semántica y retorna sus componentes numéricos.
+ *
+ * @param version - Versión semántica a parsear
+ * @returns Objeto con major, minor y patch, o null si la versión es inválida
+ *
+ * @example
+ * ```typescript
+ * parseSemanticVersion('1.2.3'); // { major: 1, minor: 2, patch: 3 }
+ * parseSemanticVersion('invalid'); // null
+ * ```
+ */
+declare function parseSemanticVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+} | null;
+/**
+ * Compara dos versiones semánticas.
+ *
+ * @param version1 - Primera versión a comparar
+ * @param version2 - Segunda versión a comparar
+ * @returns -1 si version1 < version2, 0 si son iguales, 1 si version1 > version2
+ * @throws Error si alguna de las versiones es inválida
+ *
+ * @example
+ * ```typescript
+ * compareSemanticVersions('1.2.3', '1.2.4'); // -1
+ * compareSemanticVersions('2.0.0', '1.9.9'); // 1
+ * compareSemanticVersions('1.0.0', '1.0.0'); // 0
+ * ```
+ */
+declare function compareSemanticVersions(version1: string, version2: string): number;
+/**
+ * Verifica si una versión es mayor que otra.
+ *
+ * @param version1 - Versión a comparar
+ * @param version2 - Versión de referencia
+ * @returns true si version1 > version2
+ *
+ * @example
+ * ```typescript
+ * isVersionGreaterThan('2.0.0', '1.9.9'); // true
+ * isVersionGreaterThan('1.0.0', '1.0.0'); // false
+ * ```
+ */
+declare function isVersionGreaterThan(version1: string, version2: string): boolean;
+/**
+ * Verifica si una versión es menor que otra.
+ *
+ * @param version1 - Versión a comparar
+ * @param version2 - Versión de referencia
+ * @returns true si version1 < version2
+ *
+ * @example
+ * ```typescript
+ * isVersionLessThan('1.0.0', '2.0.0'); // true
+ * ```
+ */
+declare function isVersionLessThan(version1: string, version2: string): boolean;
+/**
+ * Verifica si una versión es mayor o igual que otra.
+ *
+ * @param version1 - Versión a comparar
+ * @param version2 - Versión de referencia
+ * @returns true si version1 >= version2
+ */
+declare function isVersionGreaterOrEqual(version1: string, version2: string): boolean;
+/**
+ * Verifica si una versión es menor o igual que otra.
+ *
+ * @param version1 - Versión a comparar
+ * @param version2 - Versión de referencia
+ * @returns true si version1 <= version2
+ */
+declare function isVersionLessOrEqual(version1: string, version2: string): boolean;
+
+/**
+ * Constantes para tipos de eventos del sistema de notificaciones.
+ * Centraliza los nombres de eventos para evitar errores de tipeo.
+ */
+declare const NOTIFICATION_EVENT_TYPES: {
+    readonly REQUESTED: "notifications.requested";
+    readonly DISPATCHED: "notifications.dispatched";
+    readonly DELIVERED: "notifications.delivered";
+    readonly FAILED: "notifications.failed";
+};
+/**
+ * Constantes para tipos de eventos de conexiones OAuth.
+ */
+declare const OAUTH_CONNECTION_EVENT_TYPES: {
+    readonly LINKED: "oauth.connection.linked";
+    readonly TOKEN_REFRESHED: "oauth.connection.token_refreshed";
+    readonly REVOKED: "oauth.connection.revoked";
+};
+/**
+ * Metadata asociada a un evento para trazabilidad y correlación en sistemas distribuidos.
+ *
+ * @property traceId - ID de traza para distributed tracing (OpenTelemetry, etc.)
+ * @property spanId - ID de span dentro de la traza
+ * @property correlationId - ID para correlacionar eventos relacionados en un flujo de negocio
+ * @property causationId - ID del evento que causó este evento (event sourcing)
+ * @property tenantId - ID del tenant en arquitecturas multi-tenant
+ * @property projectId - ID del proyecto asociado
+ * @property source - Nombre del servicio o componente que originó el evento
+ */
+type EventMeta = {
+    traceId?: string;
+    spanId?: string;
+    correlationId?: string;
+    causationId?: string;
+    tenantId?: string;
+    projectId?: string;
+    source: string;
+};
+/**
+ * Envelope que envuelve un evento con toda su metadata y información de versionado.
+ * Esta estructura permite la serialización, transmisión y procesamiento de eventos
+ * en sistemas distribuidos con garantías de trazabilidad.
+ *
+ * @template TPayload - Tipo del payload específico del evento
+ * @template TMeta - Tipo de metadata (por defecto EventMeta)
+ *
+ * @property id - Identificador único del evento (recomendado: UUID v4)
+ * @property type - Tipo del evento (ej: 'notifications.requested')
+ * @property version - Versión semántica del contrato del evento
+ * @property occurredAt - Timestamp ISO 8601 de cuándo ocurrió el evento
+ * @property payload - Datos específicos del evento
+ * @property meta - Metadata de trazabilidad y contexto
+ */
+type EventEnvelope<TPayload, TMeta extends EventMeta = EventMeta> = {
+    id: string;
+    type: string;
+    version: SemanticVersion;
+    occurredAt: string;
+    payload: TPayload;
+    meta: TMeta;
+};
+/**
+ * Contrato que define la estructura y versión de un tipo de evento.
+ * Incluye un ejemplo para documentación y validación.
+ *
+ * @template TPayload - Tipo del payload del evento
+ * @template TMeta - Tipo de metadata del evento
+ *
+ * @property type - Tipo del evento
+ * @property version - Versión semántica del contrato
+ * @property schema - Identificador del esquema (formato: tipo@version)
+ * @property example - Ejemplo completo de un evento de este tipo
+ */
+type EventContract<TPayload, TMeta extends EventMeta = EventMeta> = {
+    type: string;
+    version: SemanticVersion;
+    schema: string;
+    example: EventEnvelope<TPayload, TMeta>;
+};
+
+/**
+ * Canales disponibles para el envío de notificaciones.
+ */
+type NotificationChannel = 'email' | 'sms' | 'webhook';
+/**
+ * Base común para todas las solicitudes de notificación.
+ * Contiene campos compartidos entre todos los tipos de canales.
+ *
+ * @property channel - Canal de notificación a utilizar
+ * @property projectId - ID del proyecto que solicita la notificación
+ * @property tenantId - ID del tenant (opcional, para multi-tenancy)
+ * @property locale - Código de idioma para localización (ej: 'es-ES', 'en-US')
+ * @property deduplicationKey - Clave opcional para prevenir duplicados
+ * @property expiresAt - Timestamp ISO 8601 de expiración de la notificación
+ * @property metadata - Metadatos adicionales como pares clave-valor
+ */
+type BaseNotificationRequest = {
+    channel: NotificationChannel;
+    projectId: string;
+    tenantId?: string;
+    locale?: string;
+    deduplicationKey?: string;
+    expiresAt?: string;
+    metadata?: Record<string, string>;
+};
+/**
+ * Solicitud de notificación por correo electrónico.
+ *
+ * @property channel - Debe ser 'email'
+ * @property to - Dirección de correo electrónico del destinatario
+ * @property templateId - ID del template de email a utilizar
+ * @property variables - Variables para reemplazar en el template
+ * @property cc - Lista opcional de direcciones en copia
+ * @property bcc - Lista opcional de direcciones en copia oculta
+ * @property replyTo - Dirección de respuesta opcional
+ */
+type EmailNotificationRequest = BaseNotificationRequest & {
+    channel: 'email';
+    to: string;
+    templateId: string;
+    variables?: Record<string, string | number | boolean | null>;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+};
+/**
+ * Solicitud de notificación por SMS.
+ *
+ * @property channel - Debe ser 'sms'
+ * @property to - Número de teléfono del destinatario (formato E.164 recomendado)
+ * @property templateId - ID del template de SMS a utilizar
+ * @property variables - Variables para reemplazar en el template
+ */
+type SmsNotificationRequest = BaseNotificationRequest & {
+    channel: 'sms';
+    to: string;
+    templateId: string;
+    variables?: Record<string, string | number | boolean | null>;
+};
+/**
+ * Solicitud de notificación por webhook.
+ *
+ * @property channel - Debe ser 'webhook'
+ * @property url - URL del endpoint que recibirá el webhook
+ * @property signatureVersion - Versión del algoritmo de firma para verificación
+ * @property body - Cuerpo del webhook (estructura libre)
+ */
+type WebhookNotificationRequest = BaseNotificationRequest & {
+    channel: 'webhook';
+    url: string;
+    signatureVersion: SemanticVersion;
+    body: unknown;
+};
+/**
+ * Unión de todos los tipos de solicitudes de notificación.
+ * Utiliza discriminated union basado en el campo 'channel'.
+ */
+type NotificationRequest = EmailNotificationRequest | SmsNotificationRequest | WebhookNotificationRequest;
+/**
+ * Estados posibles de una notificación en su ciclo de vida.
+ *
+ * - requested: Solicitud creada, pendiente de procesamiento
+ * - scheduled: Programada para envío futuro
+ * - dispatched: Enviada al proveedor externo
+ * - delivered: Confirmada como entregada por el proveedor
+ * - failed: Falló el envío o entrega
+ * - cancelled: Cancelada antes de ser enviada
+ */
+type NotificationStatus = 'requested' | 'scheduled' | 'dispatched' | 'delivered' | 'failed' | 'cancelled';
+/**
+ * Envelope que contiene una notificación con su estado y metadata.
+ *
+ * @property id - Identificador único de la notificación
+ * @property request - Solicitud original de la notificación
+ * @property status - Estado actual de la notificación
+ * @property createdAt - Timestamp ISO 8601 de creación
+ * @property updatedAt - Timestamp ISO 8601 de última actualización
+ * @property lastError - Información del último error si el estado es 'failed'
+ * @property providerResponseId - ID de respuesta del proveedor externo
+ */
+type NotificationEnvelope = {
+    id: string;
+    request: NotificationRequest;
+    status: NotificationStatus;
+    createdAt: string;
+    updatedAt: string;
+    lastError?: {
+        code: string;
+        message: string;
+        retriable: boolean;
+    };
+    providerResponseId?: string;
+};
+/**
+ * Type guard para verificar si una solicitud es de tipo email.
+ *
+ * @param request - Solicitud a verificar
+ * @returns true si es EmailNotificationRequest
+ */
+declare function isEmailNotificationRequest(request: NotificationRequest): request is EmailNotificationRequest;
+/**
+ * Type guard para verificar si una solicitud es de tipo SMS.
+ *
+ * @param request - Solicitud a verificar
+ * @returns true si es SmsNotificationRequest
+ */
+declare function isSmsNotificationRequest(request: NotificationRequest): request is SmsNotificationRequest;
+/**
+ * Type guard para verificar si una solicitud es de tipo webhook.
+ *
+ * @param request - Solicitud a verificar
+ * @returns true si es WebhookNotificationRequest
+ */
+declare function isWebhookNotificationRequest(request: NotificationRequest): request is WebhookNotificationRequest;
+type RequestedPayload = {
+    notification: NotificationEnvelope;
+};
+type DispatchedPayload = {
+    notificationId: string;
+    channel: NotificationChannel;
+    provider: string;
+    providerMessageId?: string;
+};
+type DeliveredPayload = {
+    notificationId: string;
+    deliveredAt: string;
+};
+type FailedPayload = {
+    notificationId: string;
+    failedAt: string;
+    errorCode: string;
+    message: string;
+    retriable: boolean;
+};
+/**
+ * Contratos de eventos para el sistema de notificaciones.
+ * Define los eventos que se emiten durante el ciclo de vida de una notificación.
+ */
+declare const notificationEvents: Record<'requested' | 'dispatched' | 'delivered' | 'failed', EventContract<RequestedPayload | DispatchedPayload | DeliveredPayload | FailedPayload>>;
+/**
+ * Unión de todos los tipos de eventos de notificaciones.
+ */
+type NotificationEvent = EventEnvelope<RequestedPayload> | EventEnvelope<DispatchedPayload> | EventEnvelope<DeliveredPayload> | EventEnvelope<FailedPayload>;
+
+/**
+ * Categorías de proveedores OAuth soportados.
+ *
+ * - oauth2: OAuth 2.0 estándar
+ * - oidc: OpenID Connect (extensión de OAuth 2.0)
+ * - saml: Security Assertion Markup Language
+ */
+type OAuthProviderCategory = 'oauth2' | 'oidc' | 'saml';
+/**
+ * Definición de un proveedor OAuth configurado en el sistema.
+ *
+ * @property id - Identificador único del proveedor (ej: 'google', 'github')
+ * @property name - Nombre legible del proveedor
+ * @property category - Categoría del protocolo OAuth
+ * @property authorizationUrl - URL del endpoint de autorización
+ * @property tokenUrl - URL del endpoint de intercambio de tokens
+ * @property scopes - Lista de scopes soportados por el proveedor
+ * @property supportsPkce - Indica si el proveedor soporta PKCE (Proof Key for Code Exchange)
+ * @property requiresWebhookForRefresh - Indica si requiere webhook para refrescar tokens
+ */
+type OAuthProvider = {
+    id: string;
+    name: string;
+    category: OAuthProviderCategory;
+    authorizationUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    supportsPkce: boolean;
+    requiresWebhookForRefresh?: boolean;
+};
+/**
+ * Conexión OAuth establecida entre un usuario y un proveedor.
+ * Representa la autorización activa de un usuario para acceder a recursos del proveedor.
+ *
+ * @property id - Identificador único de la conexión
+ * @property providerId - ID del proveedor OAuth
+ * @property projectId - ID del proyecto asociado
+ * @property tenantId - ID del tenant (opcional, para multi-tenancy)
+ * @property userId - ID del usuario que autorizó la conexión
+ * @property scope - Lista de scopes autorizados en esta conexión
+ * @property expiresAt - Timestamp ISO 8601 de expiración de la conexión
+ * @property createdAt - Timestamp ISO 8601 de creación
+ * @property updatedAt - Timestamp ISO 8601 de última actualización
+ * @property status - Estado actual de la conexión
+ */
+type OAuthConnection = {
+    id: string;
+    providerId: string;
+    projectId: string;
+    tenantId?: string;
+    userId: string;
+    scope: string[];
+    expiresAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    status: 'active' | 'refreshing' | 'revoked' | 'expired';
+};
+/**
+ * Conjunto de tokens OAuth obtenidos de un proveedor.
+ *
+ * @property accessToken - Token de acceso para autenticación
+ * @property refreshToken - Token para refrescar el access token (opcional)
+ * @property expiresIn - Tiempo de expiración en segundos (opcional)
+ * @property tokenType - Tipo de token (generalmente 'Bearer')
+ * @property issuedAt - Timestamp ISO 8601 de emisión
+ * @property expiresAt - Timestamp ISO 8601 de expiración calculado
+ * @property idToken - ID Token para OIDC (opcional)
+ */
+type TokenSet = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+    issuedAt: string;
+    expiresAt?: string;
+    idToken?: string;
+};
+/**
+ * Type guard para verificar si una conexión está activa.
+ *
+ * @param connection - Conexión a verificar
+ * @returns true si el estado es 'active'
+ */
+declare function isActiveConnection(connection: OAuthConnection): boolean;
+/**
+ * Type guard para verificar si una conexión está revocada.
+ *
+ * @param connection - Conexión a verificar
+ * @returns true si el estado es 'revoked'
+ */
+declare function isRevokedConnection(connection: OAuthConnection): boolean;
+/**
+ * Type guard para verificar si una conexión está expirada.
+ *
+ * @param connection - Conexión a verificar
+ * @returns true si el estado es 'expired' o si expiresAt está en el pasado
+ */
+declare function isExpiredConnection(connection: OAuthConnection): boolean;
+type ConnectionLinkedPayload = {
+    connection: OAuthConnection;
+    tokenSet: TokenSet;
+};
+type TokenRefreshedPayload = {
+    connectionId: string;
+    tokenSet: TokenSet;
+};
+type ConnectionRevokedPayload = {
+    connectionId: string;
+    reason: 'user' | 'provider' | 'security';
+};
+/**
+ * Contratos de eventos para el sistema de conexiones OAuth.
+ * Define los eventos que se emiten durante el ciclo de vida de una conexión OAuth.
+ */
+declare const oauthConnectionEvents: Record<'linked' | 'tokenRefreshed' | 'revoked', EventContract<ConnectionLinkedPayload | TokenRefreshedPayload | ConnectionRevokedPayload>>;
+/**
+ * Unión de todos los tipos de eventos de conexiones OAuth.
+ */
+type OAuthConnectionEvent = EventEnvelope<ConnectionLinkedPayload> | EventEnvelope<TokenRefreshedPayload> | EventEnvelope<ConnectionRevokedPayload>;
+
+/**
+ * Utilidades de validación para formatos comunes utilizados en los contratos.
+ */
+/**
+ * Valida si una cadena tiene formato UUID v4.
+ *
+ * @param value - Cadena a validar
+ * @returns true si es un UUID v4 válido
+ *
+ * @example
+ * ```typescript
+ * isValidUuid('550e8400-e29b-41d4-a716-446655440000'); // true
+ * isValidUuid('invalid'); // false
+ * ```
+ */
+declare function isValidUuid(value: string): boolean;
+/**
+ * Valida si una cadena tiene formato de email básico.
+ *
+ * @param value - Cadena a validar
+ * @returns true si tiene formato de email válido
+ *
+ * @example
+ * ```typescript
+ * isValidEmail('user@example.com'); // true
+ * isValidEmail('invalid'); // false
+ * ```
+ */
+declare function isValidEmail(value: string): boolean;
+/**
+ * Valida si una cadena tiene formato de URL válido.
+ *
+ * @param value - Cadena a validar
+ * @returns true si es una URL válida
+ *
+ * @example
+ * ```typescript
+ * isValidUrl('https://example.com'); // true
+ * isValidUrl('not-a-url'); // false
+ * ```
+ */
+declare function isValidUrl(value: string): boolean;
+/**
+ * Valida si una cadena tiene formato de teléfono E.164.
+ *
+ * @param value - Cadena a validar
+ * @returns true si tiene formato E.164 válido
+ *
+ * @example
+ * ```typescript
+ * isValidE164Phone('+1234567890'); // true
+ * isValidE164Phone('1234567890'); // false
+ * ```
+ */
+declare function isValidE164Phone(value: string): boolean;
+/**
+ * Valida si una cadena es un timestamp ISO 8601 válido.
+ *
+ * @param value - Cadena a validar
+ * @returns true si es un timestamp ISO 8601 válido
+ *
+ * @example
+ * ```typescript
+ * isValidIso8601('2024-01-01T00:00:00.000Z'); // true
+ * isValidIso8601('invalid'); // false
+ * ```
+ */
+declare function isValidIso8601(value: string): boolean;
+/**
+ * Valida si un objeto tiene todas las propiedades requeridas.
+ *
+ * @param obj - Objeto a validar
+ * @param requiredKeys - Array de claves requeridas
+ * @returns true si todas las claves están presentes
+ *
+ * @example
+ * ```typescript
+ * hasRequiredKeys({ a: 1, b: 2 }, ['a', 'b']); // true
+ * hasRequiredKeys({ a: 1 }, ['a', 'b']); // false
+ * ```
+ */
+declare function hasRequiredKeys<T extends Record<string, unknown>>(obj: T, requiredKeys: (keyof T)[]): boolean;
+
+/**
+ * Esquemas de validación en runtime usando Zod.
+ * Estos esquemas permiten validar datos en tiempo de ejecución,
+ * no solo en tiempo de compilación con TypeScript.
+ *
+ * Nota: Requiere instalar zod como dependencia.
+ */
+
+/**
+ * Esquema para validar versiones semánticas.
+ */
+declare const semanticVersionSchema: z.ZodEffects<z.ZodString, `${number}.${number}.${number}`, string>;
+/**
+ * Esquema para validar metadata de eventos.
+ */
+declare const eventMetaSchema: z.ZodObject<{
+    traceId: z.ZodOptional<z.ZodString>;
+    spanId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    causationId: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    traceId?: string | undefined;
+    spanId?: string | undefined;
+    correlationId?: string | undefined;
+    causationId?: string | undefined;
+    tenantId?: string | undefined;
+    projectId?: string | undefined;
+}, {
+    source: string;
+    traceId?: string | undefined;
+    spanId?: string | undefined;
+    correlationId?: string | undefined;
+    causationId?: string | undefined;
+    tenantId?: string | undefined;
+    projectId?: string | undefined;
+}>;
+/**
+ * Esquema genérico para validar envelopes de eventos.
+ *
+ * @template TPayload - Tipo del payload (debe ser un esquema Zod)
+ */
+declare function createEventEnvelopeSchema<TPayload extends z.ZodTypeAny>(payloadSchema: TPayload): z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    version: typeof semanticVersionSchema;
+    occurredAt: z.ZodString;
+    payload: TPayload;
+    meta: typeof eventMetaSchema;
+}>;
+/**
+ * Esquema para validar solicitudes de notificación por email.
+ */
+declare const emailNotificationRequestSchema: z.ZodObject<{
+    channel: z.ZodLiteral<"email">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    to: z.ZodString;
+    templateId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    cc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    bcc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    replyTo: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    to: string;
+    templateId: string;
+    channel: "email";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    replyTo?: string | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    to: string;
+    templateId: string;
+    channel: "email";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    replyTo?: string | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}>;
+/**
+ * Esquema para validar solicitudes de notificación por SMS.
+ */
+declare const smsNotificationRequestSchema: z.ZodObject<{
+    channel: z.ZodLiteral<"sms">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    to: z.ZodString;
+    templateId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, "strip", z.ZodTypeAny, {
+    to: string;
+    templateId: string;
+    channel: "sms";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    to: string;
+    templateId: string;
+    channel: "sms";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}>;
+/**
+ * Esquema para validar solicitudes de notificación por webhook.
+ */
+declare const webhookNotificationRequestSchema: z.ZodObject<{
+    channel: z.ZodLiteral<"webhook">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    url: z.ZodString;
+    signatureVersion: z.ZodEffects<z.ZodString, `${number}.${number}.${number}`, string>;
+    body: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    channel: "webhook";
+    projectId: string;
+    url: string;
+    signatureVersion: `${number}.${number}.${number}`;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    body?: unknown;
+}, {
+    channel: "webhook";
+    projectId: string;
+    url: string;
+    signatureVersion: string;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    body?: unknown;
+}>;
+/**
+ * Esquema para validar cualquier solicitud de notificación.
+ */
+declare const notificationRequestSchema: z.ZodDiscriminatedUnion<"channel", [z.ZodObject<{
+    channel: z.ZodLiteral<"email">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    to: z.ZodString;
+    templateId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    cc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    bcc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    replyTo: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    to: string;
+    templateId: string;
+    channel: "email";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    replyTo?: string | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    to: string;
+    templateId: string;
+    channel: "email";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    replyTo?: string | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}>, z.ZodObject<{
+    channel: z.ZodLiteral<"sms">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    to: z.ZodString;
+    templateId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, "strip", z.ZodTypeAny, {
+    to: string;
+    templateId: string;
+    channel: "sms";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    to: string;
+    templateId: string;
+    channel: "sms";
+    projectId: string;
+    variables?: Record<string, string | number | boolean | null> | undefined;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}>, z.ZodObject<{
+    channel: z.ZodLiteral<"webhook">;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    deduplicationKey: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    url: z.ZodString;
+    signatureVersion: z.ZodEffects<z.ZodString, `${number}.${number}.${number}`, string>;
+    body: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    channel: "webhook";
+    projectId: string;
+    url: string;
+    signatureVersion: `${number}.${number}.${number}`;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    body?: unknown;
+}, {
+    channel: "webhook";
+    projectId: string;
+    url: string;
+    signatureVersion: string;
+    tenantId?: string | undefined;
+    locale?: string | undefined;
+    deduplicationKey?: string | undefined;
+    expiresAt?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    body?: unknown;
+}>]>;
+/**
+ * Esquema para validar conexiones OAuth.
+ */
+declare const oauthConnectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    providerId: z.ZodString;
+    projectId: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    scope: z.ZodArray<z.ZodString, "many">;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    status: z.ZodEnum<["active", "refreshing", "revoked", "expired"]>;
+}, "strip", z.ZodTypeAny, {
+    projectId: string;
+    status: "active" | "refreshing" | "revoked" | "expired";
+    id: string;
+    providerId: string;
+    userId: string;
+    scope: string[];
+    createdAt: string;
+    updatedAt: string;
+    tenantId?: string | undefined;
+    expiresAt?: string | undefined;
+}, {
+    projectId: string;
+    status: "active" | "refreshing" | "revoked" | "expired";
+    id: string;
+    providerId: string;
+    userId: string;
+    scope: string[];
+    createdAt: string;
+    updatedAt: string;
+    tenantId?: string | undefined;
+    expiresAt?: string | undefined;
+}>;
+/**
+ * Esquema para validar conjuntos de tokens OAuth.
+ */
+declare const tokenSetSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    expiresIn: z.ZodOptional<z.ZodNumber>;
+    tokenType: z.ZodOptional<z.ZodString>;
+    issuedAt: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    idToken: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    accessToken: string;
+    issuedAt: string;
+    expiresAt?: string | undefined;
+    refreshToken?: string | undefined;
+    expiresIn?: number | undefined;
+    tokenType?: string | undefined;
+    idToken?: string | undefined;
+}, {
+    accessToken: string;
+    issuedAt: string;
+    expiresAt?: string | undefined;
+    refreshToken?: string | undefined;
+    expiresIn?: number | undefined;
+    tokenType?: string | undefined;
+    idToken?: string | undefined;
+}>;
+
+export { type BaseNotificationRequest, type EmailNotificationRequest, type EventContract, type EventEnvelope, type EventMeta, NOTIFICATION_EVENT_TYPES, type NotificationChannel, type NotificationEnvelope, type NotificationEvent, type NotificationRequest, type NotificationStatus, OAUTH_CONNECTION_EVENT_TYPES, type OAuthConnection, type OAuthConnectionEvent, type OAuthProvider, type OAuthProviderCategory, type SemanticVersion, type SmsNotificationRequest, type TokenSet, type Versioned, type WebhookNotificationRequest, compareSemanticVersions, createEventEnvelopeSchema, emailNotificationRequestSchema, eventMetaSchema, hasRequiredKeys, isActiveConnection, isEmailNotificationRequest, isExpiredConnection, isRevokedConnection, isSmsNotificationRequest, isValidE164Phone, isValidEmail, isValidIso8601, isValidSemanticVersion, isValidUrl, isValidUuid, isVersionGreaterOrEqual, isVersionGreaterThan, isVersionLessOrEqual, isVersionLessThan, isWebhookNotificationRequest, notificationEvents, notificationRequestSchema, oauthConnectionEvents, oauthConnectionSchema, parseSemanticVersion, semanticVersionSchema, smsNotificationRequestSchema, tokenSetSchema, webhookNotificationRequestSchema };