@atlas-id/contracts 0.1.0

package/src/notifications.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isEmailNotificationRequest,
+  isSmsNotificationRequest,
+  isWebhookNotificationRequest,
+  notificationEvents,
+  type EmailNotificationRequest,
+  type SmsNotificationRequest,
+  type WebhookNotificationRequest,
+} from './notifications';
+
+describe('notifications', () => {
+  describe('type guards', () => {
+    const emailRequest: EmailNotificationRequest = {
+      channel: 'email',
+      projectId: 'proj_123',
+      to: 'user@example.com',
+      templateId: 'tmpl_welcome',
+    };
+
+    const smsRequest: SmsNotificationRequest = {
+      channel: 'sms',
+      projectId: 'proj_123',
+      to: '+1234567890',
+      templateId: 'tmpl_sms',
+    };
+
+    const webhookRequest: WebhookNotificationRequest = {
+      channel: 'webhook',
+      projectId: 'proj_123',
+      url: 'https://example.com/webhook',
+      signatureVersion: '1.0.0',
+      body: { data: 'test' },
+    };
+
+    it('isEmailNotificationRequest debe identificar requests de email', () => {
+      expect(isEmailNotificationRequest(emailRequest)).toBe(true);
+      expect(isEmailNotificationRequest(smsRequest)).toBe(false);
+      expect(isEmailNotificationRequest(webhookRequest)).toBe(false);
+    });
+
+    it('isSmsNotificationRequest debe identificar requests de SMS', () => {
+      expect(isSmsNotificationRequest(smsRequest)).toBe(true);
+      expect(isSmsNotificationRequest(emailRequest)).toBe(false);
+      expect(isSmsNotificationRequest(webhookRequest)).toBe(false);
+    });
+
+    it('isWebhookNotificationRequest debe identificar requests de webhook', () => {
+      expect(isWebhookNotificationRequest(webhookRequest)).toBe(true);
+      expect(isWebhookNotificationRequest(emailRequest)).toBe(false);
+      expect(isWebhookNotificationRequest(smsRequest)).toBe(false);
+    });
+  });
+
+  describe('notificationEvents contracts', () => {
+    it('debe tener todos los eventos definidos', () => {
+      expect(notificationEvents.requested).toBeDefined();
+      expect(notificationEvents.dispatched).toBeDefined();
+      expect(notificationEvents.delivered).toBeDefined();
+      expect(notificationEvents.failed).toBeDefined();
+    });
+
+    it('los ejemplos deben tener la estructura correcta', () => {
+      const requestedExample = notificationEvents.requested.example;
+      expect(requestedExample.id).toBeDefined();
+      expect(requestedExample.type).toBe('notifications.requested');
+      expect(requestedExample.version).toBe('1.0.0');
+      expect(requestedExample.payload).toBeDefined();
+      expect(requestedExample.meta).toBeDefined();
+      expect(requestedExample.meta.source).toBeDefined();
+    });
+
+    it('los schemas deben seguir el formato tipo@version', () => {
+      expect(notificationEvents.requested.schema).toBe('notifications.requested@1.0.0');
+      expect(notificationEvents.dispatched.schema).toBe('notifications.dispatched@1.0.0');
+      expect(notificationEvents.delivered.schema).toBe('notifications.delivered@1.0.0');
+      expect(notificationEvents.failed.schema).toBe('notifications.failed@1.0.0');
+    });
+  });
+});

package/src/notifications.ts

@@ -0,0 +1,298 @@
+import { EventContract, EventEnvelope, NOTIFICATION_EVENT_TYPES } from './events';
+import { SemanticVersion } from './versioning';
+
+/**
+ * Canales disponibles para el envío de notificaciones.
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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)
+ */
+export 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'.
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export function isEmailNotificationRequest(
+  request: NotificationRequest
+): request is EmailNotificationRequest {
+  return request.channel === 'email';
+}
+
+/**
+ * Type guard para verificar si una solicitud es de tipo SMS.
+ * 
+ * @param request - Solicitud a verificar
+ * @returns true si es SmsNotificationRequest
+ */
+export function isSmsNotificationRequest(
+  request: NotificationRequest
+): request is SmsNotificationRequest {
+  return request.channel === 'sms';
+}
+
+/**
+ * Type guard para verificar si una solicitud es de tipo webhook.
+ * 
+ * @param request - Solicitud a verificar
+ * @returns true si es WebhookNotificationRequest
+ */
+export function isWebhookNotificationRequest(
+  request: NotificationRequest
+): request is WebhookNotificationRequest {
+  return request.channel === 'webhook';
+}
+
+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.
+ */
+export const notificationEvents: Record<
+  'requested' | 'dispatched' | 'delivered' | 'failed',
+  EventContract<RequestedPayload | DispatchedPayload | DeliveredPayload | FailedPayload>
+> = {
+  requested: {
+    type: NOTIFICATION_EVENT_TYPES.REQUESTED,
+    version: '1.0.0',
+    schema: 'notifications.requested@1.0.0',
+    example: {
+      id: 'evt_123',
+      type: NOTIFICATION_EVENT_TYPES.REQUESTED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        notification: {
+          id: 'ntf_123',
+          request: {
+            channel: 'email',
+            projectId: 'proj_123',
+            to: 'user@example.com',
+            templateId: 'tmpl_welcome',
+          },
+          status: 'requested',
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+      },
+      meta: {
+        source: 'notifications-service',
+      },
+    },
+  },
+  dispatched: {
+    type: NOTIFICATION_EVENT_TYPES.DISPATCHED,
+    version: '1.0.0',
+    schema: 'notifications.dispatched@1.0.0',
+    example: {
+      id: 'evt_124',
+      type: NOTIFICATION_EVENT_TYPES.DISPATCHED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        notificationId: 'ntf_123',
+        channel: 'email',
+        provider: 'postmark',
+        providerMessageId: 'msg_abc',
+      },
+      meta: {
+        source: 'notifications-service',
+      },
+    },
+  },
+  delivered: {
+    type: NOTIFICATION_EVENT_TYPES.DELIVERED,
+    version: '1.0.0',
+    schema: 'notifications.delivered@1.0.0',
+    example: {
+      id: 'evt_125',
+      type: NOTIFICATION_EVENT_TYPES.DELIVERED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        notificationId: 'ntf_123',
+        deliveredAt: new Date().toISOString(),
+      },
+      meta: {
+        source: 'notifications-service',
+      },
+    },
+  },
+  failed: {
+    type: NOTIFICATION_EVENT_TYPES.FAILED,
+    version: '1.0.0',
+    schema: 'notifications.failed@1.0.0',
+    example: {
+      id: 'evt_126',
+      type: NOTIFICATION_EVENT_TYPES.FAILED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        notificationId: 'ntf_123',
+        failedAt: new Date().toISOString(),
+        errorCode: 'bounce',
+        message: 'Mailbox unreachable',
+        retriable: false,
+      },
+      meta: {
+        source: 'notifications-service',
+      },
+    },
+  },
+};
+
+/**
+ * Unión de todos los tipos de eventos de notificaciones.
+ */
+export type NotificationEvent =
+  | EventEnvelope<RequestedPayload>
+  | EventEnvelope<DispatchedPayload>
+  | EventEnvelope<DeliveredPayload>
+  | EventEnvelope<FailedPayload>;

package/src/oauth-connections.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isActiveConnection,
+  isRevokedConnection,
+  isExpiredConnection,
+  oauthConnectionEvents,
+  type OAuthConnection,
+} from './oauth-connections';
+
+describe('oauth-connections', () => {
+  describe('type guards', () => {
+    const activeConnection: OAuthConnection = {
+      id: 'conn_1',
+      providerId: 'google',
+      projectId: 'proj_123',
+      userId: 'user_123',
+      scope: ['calendar'],
+      status: 'active',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    const revokedConnection: OAuthConnection = {
+      ...activeConnection,
+      id: 'conn_2',
+      status: 'revoked',
+    };
+
+    const expiredConnection: OAuthConnection = {
+      ...activeConnection,
+      id: 'conn_3',
+      status: 'expired',
+      expiresAt: new Date(Date.now() - 1000).toISOString(),
+    };
+
+    it('isActiveConnection debe identificar conexiones activas', () => {
+      expect(isActiveConnection(activeConnection)).toBe(true);
+      expect(isActiveConnection(revokedConnection)).toBe(false);
+    });
+
+    it('isRevokedConnection debe identificar conexiones revocadas', () => {
+      expect(isRevokedConnection(revokedConnection)).toBe(true);
+      expect(isRevokedConnection(activeConnection)).toBe(false);
+    });
+
+    it('isExpiredConnection debe identificar conexiones expiradas', () => {
+      expect(isExpiredConnection(expiredConnection)).toBe(true);
+      expect(isExpiredConnection(activeConnection)).toBe(false);
+      
+      const connectionWithPastExpiry: OAuthConnection = {
+        ...activeConnection,
+        expiresAt: new Date(Date.now() - 1000).toISOString(),
+      };
+      expect(isExpiredConnection(connectionWithPastExpiry)).toBe(true);
+    });
+  });
+
+  describe('oauthConnectionEvents contracts', () => {
+    it('debe tener todos los eventos definidos', () => {
+      expect(oauthConnectionEvents.linked).toBeDefined();
+      expect(oauthConnectionEvents.tokenRefreshed).toBeDefined();
+      expect(oauthConnectionEvents.revoked).toBeDefined();
+    });
+
+    it('los ejemplos deben tener la estructura correcta', () => {
+      const linkedExample = oauthConnectionEvents.linked.example;
+      expect(linkedExample.id).toBeDefined();
+      expect(linkedExample.type).toBe('oauth.connection.linked');
+      expect(linkedExample.version).toBe('1.0.0');
+      expect(linkedExample.payload).toBeDefined();
+      expect(linkedExample.meta).toBeDefined();
+    });
+
+    it('los schemas deben seguir el formato tipo@version', () => {
+      expect(oauthConnectionEvents.linked.schema).toBe('oauth.connection.linked@1.0.0');
+      expect(oauthConnectionEvents.tokenRefreshed.schema).toBe('oauth.connection.token_refreshed@1.0.0');
+      expect(oauthConnectionEvents.revoked.schema).toBe('oauth.connection.revoked@1.0.0');
+    });
+  });
+});

package/src/oauth-connections.ts

@@ -0,0 +1,220 @@
+import { EventContract, EventEnvelope, OAUTH_CONNECTION_EVENT_TYPES } from './events';
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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)
+ */
+export 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'
+ */
+export function isActiveConnection(connection: OAuthConnection): boolean {
+  return connection.status === 'active';
+}
+
+/**
+ * Type guard para verificar si una conexión está revocada.
+ * 
+ * @param connection - Conexión a verificar
+ * @returns true si el estado es 'revoked'
+ */
+export function isRevokedConnection(connection: OAuthConnection): boolean {
+  return connection.status === 'revoked';
+}
+
+/**
+ * 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
+ */
+export function isExpiredConnection(connection: OAuthConnection): boolean {
+  if (connection.status === 'expired') return true;
+  if (!connection.expiresAt) return false;
+  return new Date(connection.expiresAt) < new Date();
+}
+
+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.
+ */
+export const oauthConnectionEvents: Record<
+  'linked' | 'tokenRefreshed' | 'revoked',
+  EventContract<ConnectionLinkedPayload | TokenRefreshedPayload | ConnectionRevokedPayload>
+> = {
+  linked: {
+    type: OAUTH_CONNECTION_EVENT_TYPES.LINKED,
+    version: '1.0.0',
+    schema: 'oauth.connection.linked@1.0.0',
+    example: {
+      id: 'evt_conn_1',
+      type: OAUTH_CONNECTION_EVENT_TYPES.LINKED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        connection: {
+          id: 'conn_123',
+          providerId: 'google',
+          projectId: 'proj_123',
+          userId: 'user_123',
+          scope: ['calendar', 'email'],
+          status: 'active',
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+        tokenSet: {
+          accessToken: 'access-token',
+          refreshToken: 'refresh-token',
+          issuedAt: new Date().toISOString(),
+          expiresIn: 3600,
+        },
+      },
+      meta: {
+        source: 'oauth-connections-service',
+      },
+    },
+  },
+  tokenRefreshed: {
+    type: OAUTH_CONNECTION_EVENT_TYPES.TOKEN_REFRESHED,
+    version: '1.0.0',
+    schema: 'oauth.connection.token_refreshed@1.0.0',
+    example: {
+      id: 'evt_conn_2',
+      type: OAUTH_CONNECTION_EVENT_TYPES.TOKEN_REFRESHED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        connectionId: 'conn_123',
+        tokenSet: {
+          accessToken: 'access-token-2',
+          refreshToken: 'refresh-token',
+          issuedAt: new Date().toISOString(),
+          expiresIn: 3600,
+        },
+      },
+      meta: {
+        source: 'oauth-connections-service',
+      },
+    },
+  },
+  revoked: {
+    type: OAUTH_CONNECTION_EVENT_TYPES.REVOKED,
+    version: '1.0.0',
+    schema: 'oauth.connection.revoked@1.0.0',
+    example: {
+      id: 'evt_conn_3',
+      type: OAUTH_CONNECTION_EVENT_TYPES.REVOKED,
+      version: '1.0.0',
+      occurredAt: new Date().toISOString(),
+      payload: {
+        connectionId: 'conn_123',
+        reason: 'security',
+      },
+      meta: {
+        source: 'oauth-connections-service',
+      },
+    },
+  },
+};
+
+/**
+ * Unión de todos los tipos de eventos de conexiones OAuth.
+ */
+export type OAuthConnectionEvent =
+  | EventEnvelope<ConnectionLinkedPayload>
+  | EventEnvelope<TokenRefreshedPayload>
+  | EventEnvelope<ConnectionRevokedPayload>;