Opendex Atlas ID Contracts

Biblioteca de contratos TypeScript compartidos para el ecosistema de servicios de Atlas ID. Define los tipos, estructuras de datos y contratos de eventos utilizados para la comunicación entre servicios en arquitecturas distribuidas.

Propiedad de Opendex, Inc. - Este software es propietario y no es de código abierto.

Función Principal

Este paquete proporciona contratos tipados y versionados que garantizan la consistencia y compatibilidad entre los diferentes servicios del sistema IAM. Actúa como la fuente única de verdad para:

• Definiciones de tipos TypeScript para eventos, notificaciones y conexiones OAuth
• Contratos de eventos con versionado semántico
• Esquemas de validación en runtime
• Utilidades de validación y type guards

Arquitectura

El proyecto está organizado en módulos especializados:

Eventos

Define la estructura base para eventos en sistemas distribuidos con soporte para:

• Versionado semántico de contratos
• Metadata de trazabilidad (traceId, spanId, correlationId, causationId)
• Soporte para multi-tenancy (tenantId, projectId)
• Identificación de origen (source)

Notificaciones

Contratos para el sistema de notificaciones que soporta múltiples canales:

• Email con soporte para templates, variables, CC, BCC y reply-to
• SMS con templates y variables
• Webhooks con versionado de firmas y payloads personalizados

Incluye estados del ciclo de vida: requested, scheduled, dispatched, delivered, failed, cancelled.

Conexiones OAuth

Contratos para gestión de conexiones OAuth con soporte para:

• Múltiples protocolos: OAuth2, OIDC, SAML
• Gestión de tokens (access, refresh, ID tokens)
• Estados de conexión: active, refreshing, revoked, expired
• Soporte para PKCE y webhooks de refresh

Versionado

Utilidades para trabajar con versionado semántico:

• Validación de formato de versiones
• Parsing y comparación de versiones
• Funciones de comparación (mayor que, menor que, igual)

Uso

Instalación

pnpm add @atlas-id/contracts

Importación de Tipos

import type {
  EventEnvelope,
  NotificationRequest,
  OAuthConnection,
  SemanticVersion,
} from '@atlas-id/contracts';

Uso de Contratos de Eventos

import { notificationEvents } from '@atlas-id/contracts';

// El contrato incluye el tipo, versión, schema y un ejemplo
const event = {
  ...notificationEvents.requested.example,
  id: 'evt_custom_123',
  occurredAt: new Date().toISOString(),
  payload: {
    notification: {
      // ... datos de la notificación
    },
  },
};

Validación en Runtime

import {
  notificationRequestSchema,
  createEventEnvelopeSchema,
} from '@atlas-id/contracts';

// Validar una solicitud de notificación
const result = notificationRequestSchema.safeParse(requestData);
if (result.success) {
  // requestData es válido
} else {
  // result.error contiene los errores de validación
}

Type Guards

import {
  isEmailNotificationRequest,
  isSmsNotificationRequest,
  isWebhookNotificationRequest,
} from '@atlas-id/contracts';

function processNotification(request: NotificationRequest) {
  if (isEmailNotificationRequest(request)) {
    // TypeScript sabe que request es EmailNotificationRequest
    console.log(request.to);
  } else if (isSmsNotificationRequest(request)) {
    // TypeScript sabe que request es SmsNotificationRequest
    console.log(request.to);
  }
}

Utilidades de Validación

import {
  isValidUuid,
  isValidEmail,
  isValidUrl,
  isValidE164Phone,
  isValidIso8601,
} from '@atlas-id/contracts';

if (isValidUuid(userId)) {
  // userId es un UUID válido
}

if (isValidEmail(email)) {
  // email tiene formato válido
}

Versionado Semántico

import {
  isValidSemanticVersion,
  parseSemanticVersion,
  compareSemanticVersions,
  isVersionGreaterThan,
} from '@atlas-id/contracts';

if (isValidSemanticVersion('1.2.3')) {
  const parsed = parseSemanticVersion('1.2.3');
  // { major: 1, minor: 2, patch: 3 }
}

if (isVersionGreaterThan('2.0.0', '1.9.9')) {
  // La versión 2.0.0 es mayor que 1.9.9
}

Estructura de Contratos

Cada contrato de evento sigue la estructura:

{
  type: string;           // Tipo del evento (ej: 'notifications.requested')
  version: SemanticVersion; // Versión semántica del contrato
  schema: string;         // Identificador del schema (tipo@version)
  example: EventEnvelope; // Ejemplo completo del evento
}

Los eventos incluyen metadata de trazabilidad:

{
  traceId?: string;        // ID de traza para distributed tracing
  spanId?: string;         // ID de span dentro de la traza
  correlationId?: string;  // ID para correlacionar eventos relacionados
  causationId?: string;    // ID del evento que causó este evento
  tenantId?: string;       // ID del tenant (multi-tenancy)
  projectId?: string;      // ID del proyecto
  source: string;          // Servicio que originó el evento
}

Validación

El paquete proporciona validación en dos niveles:

1. Compilación: TypeScript valida los tipos en tiempo de compilación
2. Runtime: Zod valida los datos en tiempo de ejecución

Los esquemas de Zod están disponibles para validar:

• Event envelopes
• Notification requests
• OAuth connections
• Token sets
• Versiones semánticas

Constantes

Los tipos de eventos están centralizados en constantes para evitar errores de tipeo:

import {
  NOTIFICATION_EVENT_TYPES,
  OAUTH_CONNECTION_EVENT_TYPES,
} from '@atlas-id/contracts';

// En lugar de 'notifications.requested'
const eventType = NOTIFICATION_EVENT_TYPES.REQUESTED;

Desarrollo

Scripts Disponibles

• pnpm build: Compila el proyecto TypeScript
• pnpm typecheck: Valida tipos sin compilar
• pnpm test: Ejecuta tests unitarios
• pnpm test:watch: Ejecuta tests en modo watch
• pnpm test:coverage: Genera reporte de cobertura
• pnpm lint: Ejecuta ESLint
• pnpm lint:fix: Ejecuta ESLint y corrige errores automáticamente
• pnpm clean: Limpia directorios de build y node_modules

Estructura del Proyecto

src/
  events.ts              # Tipos y contratos base de eventos
  notifications.ts       # Contratos de notificaciones
  oauth-connections.ts   # Contratos de conexiones OAuth
  versioning.ts          # Utilidades de versionado semántico
  utils/
    validation.ts        # Utilidades de validación
  schemas/
    index.ts             # Esquemas Zod para validación runtime
  *.test.ts              # Tests unitarios

Tests

Los tests validan:

• Funcionalidad de utilidades de versionado
• Type guards y discriminación de tipos
• Validación de formatos (UUID, email, URL, etc.)
• Estructura y validez de ejemplos en contratos
• Esquemas de validación Zod

Contribución

Al agregar nuevos contratos o modificar existentes:

1. Actualizar los tipos TypeScript
2. Agregar documentación JSDoc
3. Crear o actualizar esquemas Zod
4. Agregar ejemplos en los contratos
5. Escribir tests unitarios
6. Actualizar el CHANGELOG.md

Los cambios que modifiquen la estructura de contratos existentes deben incrementar la versión semántica del contrato afectado.

Compatibilidad

• Node.js: 18+
• TypeScript: 5.3+
• ESM y CommonJS soportados