@atlas-id/contracts 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2024 Opendex, Inc.
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the 
+proprietary and confidential property of Opendex, Inc. ("Opendex").
+
+The Software is protected by copyright laws and international copyright 
+treaties, as well as other intellectual property laws and treaties.
+
+No part of this Software may be reproduced, distributed, transmitted, 
+displayed, published, or broadcast in any form or by any means, including 
+but not limited to electronic, mechanical, photocopying, recording, or 
+otherwise, without the prior written permission of Opendex.
+
+Unauthorized copying, modification, distribution, or use of this Software, 
+via any medium, is strictly prohibited and may result in severe civil and 
+criminal penalties, and will be prosecuted to the maximum extent possible 
+under the law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
+OPENDEX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, please contact: legal@opendex.com

package/README.md

@@ -0,0 +1,289 @@
+# 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
+
+```bash
+pnpm add @atlas-id/contracts
+```
+
+### Importación de Tipos
+
+```typescript
+import type {
+  EventEnvelope,
+  NotificationRequest,
+  OAuthConnection,
+  SemanticVersion,
+} from '@atlas-id/contracts';
+```
+
+### Uso de Contratos de Eventos
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+{
+  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:
+
+```typescript
+{
+  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:
+
+```typescript
+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
+
+## Propiedad y Licencia
+
+Copyright (c) 2024 Opendex, Inc. Todos los derechos reservados.
+
+Este software es propiedad exclusiva de Opendex, Inc. y no es de código abierto. 
+Está protegido por leyes de derechos de autor y otras leyes de propiedad intelectual.
+
+El uso, reproducción, distribución o modificación de este software sin el 
+consentimiento escrito previo de Opendex, Inc. está estrictamente prohibido.
+
+Para consultas sobre licencias, contactar: legal@opendex.com
+
+Ver archivo LICENSE para más detalles.

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@atlas-id/contracts",
+    "version": "0.1.0",
+    "license": "UNLICENSED",
+    "author": "Opendex, Inc.",
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "rimraf dist && tsup-node",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest watch",
+        "test:coverage": "vitest run --coverage",
+        "lint": "eslint --ext .ts .",
+        "lint:fix": "eslint --ext .ts . --fix",
+        "clean": "rimraf dist && rimraf node_modules",
+        "prebuild": "pnpm typecheck && pnpm lint && pnpm test"
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "require": {
+                "default": "./dist/index.js"
+            },
+            "default": "./dist/esm/index.js"
+        },
+        "./dist/*": {
+            "types": "./dist/*.d.ts",
+            "require": {
+                "default": "./dist/*.js"
+            },
+            "default": "./dist/esm/*.js"
+        }
+    },
+    "peerDependencies": {},
+    "dependencies": {
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@typescript-eslint/eslint-plugin": "^7.18.0",
+        "@typescript-eslint/parser": "^7.18.0",
+        "@vitest/coverage-v8": "^4.0.16",
+        "eslint": "^8.57.1",
+        "husky": "^9.0.11",
+        "rimraf": "^6.1.2",
+        "tsup": "^8.5.1",
+        "typescript": "5.3.3",
+        "vitest": "^4.0.16"
+    }
+}

package/src/contracts-validation.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { notificationEvents } from './notifications';
+import { oauthConnectionEvents } from './oauth-connections';
+import { isValidSemanticVersion } from './versioning';
+import {
+  createEventEnvelopeSchema,
+  notificationRequestSchema,
+  oauthConnectionSchema,
+  tokenSetSchema,
+} from './schemas';
+
+describe('contracts validation', () => {
+  describe('notificationEvents examples', () => {
+    it('debe validar el ejemplo de requested event', () => {
+      const contract = notificationEvents.requested;
+      const example = contract.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('notifications.requested');
+      expect(contract.schema).toBe('notifications.requested@1.0.0');
+      expect(example.meta.source).toBeDefined();
+      
+      // Type guard para acceder a las propiedades específicas
+      if ('notification' in example.payload) {
+        expect(example.payload.notification).toBeDefined();
+        expect(example.payload.notification.request.channel).toBe('email');
+      }
+    });
+
+    it('debe validar el ejemplo de dispatched event', () => {
+      const example = notificationEvents.dispatched.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('notifications.dispatched');
+      
+      if ('notificationId' in example.payload && 'channel' in example.payload && 'provider' in example.payload) {
+        expect(example.payload.notificationId).toBeDefined();
+        expect(example.payload.channel).toBeDefined();
+        expect(example.payload.provider).toBeDefined();
+      }
+    });
+
+    it('debe validar el ejemplo de delivered event', () => {
+      const example = notificationEvents.delivered.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('notifications.delivered');
+      
+      if ('notificationId' in example.payload && 'deliveredAt' in example.payload) {
+        expect(example.payload.notificationId).toBeDefined();
+        expect(example.payload.deliveredAt).toBeDefined();
+      }
+    });
+
+    it('debe validar el ejemplo de failed event', () => {
+      const example = notificationEvents.failed.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('notifications.failed');
+      
+      if ('notificationId' in example.payload && 'errorCode' in example.payload) {
+        expect(example.payload.notificationId).toBeDefined();
+        expect(example.payload.errorCode).toBeDefined();
+        expect(example.payload.retriable).toBeDefined();
+      }
+    });
+
+    it('los ejemplos deben pasar validación con Zod', () => {
+      const requestedPayloadSchema = z.object({
+        notification: z.object({
+          id: z.string(),
+          request: notificationRequestSchema,
+          status: z.string(),
+          createdAt: z.string(),
+          updatedAt: z.string(),
+        }),
+      });
+      
+      const requestedEnvelopeSchema = createEventEnvelopeSchema(requestedPayloadSchema);
+      
+      const result = requestedEnvelopeSchema.safeParse(notificationEvents.requested.example);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('oauthConnectionEvents examples', () => {
+    it('debe validar el ejemplo de linked event', () => {
+      const example = oauthConnectionEvents.linked.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('oauth.connection.linked');
+      
+      if ('connection' in example.payload && 'tokenSet' in example.payload) {
+        expect(example.payload.connection).toBeDefined();
+        expect(example.payload.tokenSet).toBeDefined();
+      }
+    });
+
+    it('debe validar el ejemplo de tokenRefreshed event', () => {
+      const example = oauthConnectionEvents.tokenRefreshed.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('oauth.connection.token_refreshed');
+      
+      if ('connectionId' in example.payload && 'tokenSet' in example.payload) {
+        expect(example.payload.connectionId).toBeDefined();
+        expect(example.payload.tokenSet).toBeDefined();
+      }
+    });
+
+    it('debe validar el ejemplo de revoked event', () => {
+      const example = oauthConnectionEvents.revoked.example;
+      
+      expect(isValidSemanticVersion(example.version)).toBe(true);
+      expect(example.type).toBe('oauth.connection.revoked');
+      
+      if ('connectionId' in example.payload && 'reason' in example.payload) {
+        expect(example.payload.connectionId).toBeDefined();
+        expect(example.payload.reason).toBeDefined();
+      }
+    });
+
+    it('los ejemplos deben pasar validación con Zod', () => {
+      const linkedPayloadSchema = z.object({
+        connection: oauthConnectionSchema,
+        tokenSet: tokenSetSchema,
+      });
+      
+      const linkedEnvelopeSchema = createEventEnvelopeSchema(linkedPayloadSchema);
+      
+      const result = linkedEnvelopeSchema.safeParse(oauthConnectionEvents.linked.example);
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/src/events.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import {
+  NOTIFICATION_EVENT_TYPES,
+  OAUTH_CONNECTION_EVENT_TYPES,
+  type EventEnvelope,
+  type EventMeta,
+} from './events';
+
+describe('events', () => {
+  describe('constants', () => {
+    it('NOTIFICATION_EVENT_TYPES debe tener todos los tipos', () => {
+      expect(NOTIFICATION_EVENT_TYPES.REQUESTED).toBe('notifications.requested');
+      expect(NOTIFICATION_EVENT_TYPES.DISPATCHED).toBe('notifications.dispatched');
+      expect(NOTIFICATION_EVENT_TYPES.DELIVERED).toBe('notifications.delivered');
+      expect(NOTIFICATION_EVENT_TYPES.FAILED).toBe('notifications.failed');
+    });
+
+    it('OAUTH_CONNECTION_EVENT_TYPES debe tener todos los tipos', () => {
+      expect(OAUTH_CONNECTION_EVENT_TYPES.LINKED).toBe('oauth.connection.linked');
+      expect(OAUTH_CONNECTION_EVENT_TYPES.TOKEN_REFRESHED).toBe('oauth.connection.token_refreshed');
+      expect(OAUTH_CONNECTION_EVENT_TYPES.REVOKED).toBe('oauth.connection.revoked');
+    });
+  });
+
+  describe('EventEnvelope', () => {
+    it('debe crear un envelope válido', () => {
+      const meta: EventMeta = {
+        source: 'test-service',
+        traceId: 'trace_123',
+      };
+
+      const envelope: EventEnvelope<{ data: string }> = {
+        id: 'evt_123',
+        type: 'test.event',
+        version: '1.0.0',
+        occurredAt: new Date().toISOString(),
+        payload: { data: 'test' },
+        meta,
+      };
+
+      expect(envelope.id).toBe('evt_123');
+      expect(envelope.type).toBe('test.event');
+      expect(envelope.version).toBe('1.0.0');
+      expect(envelope.payload.data).toBe('test');
+      expect(envelope.meta.source).toBe('test-service');
+    });
+  });
+});

package/src/events.ts

@@ -0,0 +1,85 @@
+import { SemanticVersion } from './versioning';
+
+/**
+ * Constantes para tipos de eventos del sistema de notificaciones.
+ * Centraliza los nombres de eventos para evitar errores de tipeo.
+ */
+export const NOTIFICATION_EVENT_TYPES = {
+  REQUESTED: 'notifications.requested',
+  DISPATCHED: 'notifications.dispatched',
+  DELIVERED: 'notifications.delivered',
+  FAILED: 'notifications.failed',
+} as const;
+
+/**
+ * Constantes para tipos de eventos de conexiones OAuth.
+ */
+export const OAUTH_CONNECTION_EVENT_TYPES = {
+  LINKED: 'oauth.connection.linked',
+  TOKEN_REFRESHED: 'oauth.connection.token_refreshed',
+  REVOKED: 'oauth.connection.revoked',
+} as const;
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export type EventContract<TPayload, TMeta extends EventMeta = EventMeta> = {
+  type: string;
+  version: SemanticVersion;
+  schema: string;
+  example: EventEnvelope<TPayload, TMeta>;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './events';
+export * from './notifications';
+export * from './oauth-connections';
+export * from './versioning';
+export * from './utils';
+export * from './schemas';