@atlas-id/contracts 0.1.0

package/src/schemas/index.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+import { z } from 'zod';
+import { isValidSemanticVersion } from '../versioning';
+
+/**
+ * Esquema para validar versiones semánticas.
+ */
+export const semanticVersionSchema = z.string().refine(
+  isValidSemanticVersion,
+  { message: 'Debe ser una versión semántica válida (MAJOR.MINOR.PATCH)' }
+);
+
+/**
+ * Esquema para validar metadata de eventos.
+ */
+export const eventMetaSchema = z.object({
+  traceId: z.string().optional(),
+  spanId: z.string().optional(),
+  correlationId: z.string().optional(),
+  causationId: z.string().optional(),
+  tenantId: z.string().optional(),
+  projectId: z.string().optional(),
+  source: z.string().min(1),
+});
+
+/**
+ * Esquema genérico para validar envelopes de eventos.
+ * 
+ * @template TPayload - Tipo del payload (debe ser un esquema Zod)
+ */
+export function createEventEnvelopeSchema<TPayload extends z.ZodTypeAny>(
+  payloadSchema: TPayload
+) {
+  return z.object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    version: semanticVersionSchema,
+    occurredAt: z.string().datetime(),
+    payload: payloadSchema,
+    meta: eventMetaSchema,
+  });
+}
+
+/**
+ * Esquema para validar solicitudes de notificación por email.
+ */
+export const emailNotificationRequestSchema = z.object({
+  channel: z.literal('email'),
+  projectId: z.string().min(1),
+  tenantId: z.string().optional(),
+  locale: z.string().optional(),
+  deduplicationKey: z.string().optional(),
+  expiresAt: z.string().datetime().optional(),
+  metadata: z.record(z.string()).optional(),
+  to: z.string().email(),
+  templateId: z.string().min(1),
+  variables: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+  cc: z.array(z.string().email()).optional(),
+  bcc: z.array(z.string().email()).optional(),
+  replyTo: z.string().email().optional(),
+});
+
+/**
+ * Esquema para validar solicitudes de notificación por SMS.
+ */
+export const smsNotificationRequestSchema = z.object({
+  channel: z.literal('sms'),
+  projectId: z.string().min(1),
+  tenantId: z.string().optional(),
+  locale: z.string().optional(),
+  deduplicationKey: z.string().optional(),
+  expiresAt: z.string().datetime().optional(),
+  metadata: z.record(z.string()).optional(),
+  to: z.string().min(1),
+  templateId: z.string().min(1),
+  variables: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+});
+
+/**
+ * Esquema para validar solicitudes de notificación por webhook.
+ */
+export const webhookNotificationRequestSchema = z.object({
+  channel: z.literal('webhook'),
+  projectId: z.string().min(1),
+  tenantId: z.string().optional(),
+  locale: z.string().optional(),
+  deduplicationKey: z.string().optional(),
+  expiresAt: z.string().datetime().optional(),
+  metadata: z.record(z.string()).optional(),
+  url: z.string().url(),
+  signatureVersion: semanticVersionSchema,
+  body: z.unknown(),
+});
+
+/**
+ * Esquema para validar cualquier solicitud de notificación.
+ */
+export const notificationRequestSchema = z.discriminatedUnion('channel', [
+  emailNotificationRequestSchema,
+  smsNotificationRequestSchema,
+  webhookNotificationRequestSchema,
+]);
+
+/**
+ * Esquema para validar conexiones OAuth.
+ */
+export const oauthConnectionSchema = z.object({
+  id: z.string().min(1),
+  providerId: z.string().min(1),
+  projectId: z.string().min(1),
+  tenantId: z.string().optional(),
+  userId: z.string().min(1),
+  scope: z.array(z.string()),
+  expiresAt: z.string().datetime().optional(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  status: z.enum(['active', 'refreshing', 'revoked', 'expired']),
+});
+
+/**
+ * Esquema para validar conjuntos de tokens OAuth.
+ */
+export const tokenSetSchema = z.object({
+  accessToken: z.string().min(1),
+  refreshToken: z.string().optional(),
+  expiresIn: z.number().positive().optional(),
+  tokenType: z.string().optional(),
+  issuedAt: z.string().datetime(),
+  expiresAt: z.string().datetime().optional(),
+  idToken: z.string().optional(),
+});

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './validation';

package/src/utils/validation.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isValidUuid,
+  isValidEmail,
+  isValidUrl,
+  isValidE164Phone,
+  isValidIso8601,
+  hasRequiredKeys,
+} from './validation';
+
+describe('validation utils', () => {
+  describe('isValidUuid', () => {
+    it('debe validar UUIDs v4 correctos', () => {
+      expect(isValidUuid('550e8400-e29b-41d4-a716-446655440000')).toBe(true);
+      // UUID v4 válido (el segundo ejemplo es UUID v1, no v4)
+      expect(isValidUuid('f47ac10b-58cc-4372-a567-0e02b2c3d479')).toBe(true);
+      expect(isValidUuid('a1b2c3d4-e5f6-4789-a012-3456789abcde')).toBe(true);
+    });
+
+    it('debe rechazar UUIDs inválidos', () => {
+      expect(isValidUuid('invalid')).toBe(false);
+      expect(isValidUuid('550e8400-e29b-41d4-a716')).toBe(false);
+      expect(isValidUuid('')).toBe(false);
+    });
+  });
+
+  describe('isValidEmail', () => {
+    it('debe validar emails correctos', () => {
+      expect(isValidEmail('user@example.com')).toBe(true);
+      expect(isValidEmail('test.user+tag@example.co.uk')).toBe(true);
+    });
+
+    it('debe rechazar emails inválidos', () => {
+      expect(isValidEmail('invalid')).toBe(false);
+      expect(isValidEmail('@example.com')).toBe(false);
+      expect(isValidEmail('user@')).toBe(false);
+      expect(isValidEmail('')).toBe(false);
+    });
+  });
+
+  describe('isValidUrl', () => {
+    it('debe validar URLs correctas', () => {
+      expect(isValidUrl('https://example.com')).toBe(true);
+      expect(isValidUrl('http://example.com/path?query=1')).toBe(true);
+      expect(isValidUrl('https://subdomain.example.com:8080/path')).toBe(true);
+    });
+
+    it('debe rechazar URLs inválidas', () => {
+      expect(isValidUrl('not-a-url')).toBe(false);
+      expect(isValidUrl('://invalid')).toBe(false);
+      expect(isValidUrl('')).toBe(false);
+    });
+  });
+
+  describe('isValidE164Phone', () => {
+    it('debe validar números E.164 correctos', () => {
+      expect(isValidE164Phone('+1234567890')).toBe(true);
+      expect(isValidE164Phone('+34612345678')).toBe(true);
+    });
+
+    it('debe rechazar números inválidos', () => {
+      expect(isValidE164Phone('1234567890')).toBe(false);
+      expect(isValidE164Phone('+123')).toBe(false);
+      expect(isValidE164Phone('')).toBe(false);
+    });
+  });
+
+  describe('isValidIso8601', () => {
+    it('debe validar timestamps ISO 8601 correctos', () => {
+      expect(isValidIso8601('2024-01-01T00:00:00.000Z')).toBe(true);
+      expect(isValidIso8601('2024-12-31T23:59:59.999Z')).toBe(true);
+    });
+
+    it('debe rechazar timestamps inválidos', () => {
+      expect(isValidIso8601('2024-01-01')).toBe(false);
+      expect(isValidIso8601('invalid')).toBe(false);
+      expect(isValidIso8601('')).toBe(false);
+    });
+  });
+
+  describe('hasRequiredKeys', () => {
+    it('debe validar que un objeto tiene todas las claves requeridas', () => {
+      const obj1: Record<string, number> = { a: 1, b: 2 };
+      const obj2: Record<string, number> = { a: 1, b: 2, c: 3 };
+      expect(hasRequiredKeys(obj1, ['a', 'b'])).toBe(true);
+      expect(hasRequiredKeys(obj2, ['a', 'b'])).toBe(true);
+    });
+
+    it('debe retornar false si faltan claves requeridas', () => {
+      const obj1: Record<string, number> = { a: 1 };
+      const obj2: Record<string, unknown> = {};
+      expect(hasRequiredKeys(obj1, ['a', 'b'])).toBe(false);
+      expect(hasRequiredKeys(obj2, ['a'])).toBe(false);
+    });
+  });
+});

package/src/utils/validation.ts

@@ -0,0 +1,136 @@
+/**
+ * Utilidades de validación para formatos comunes utilizados en los contratos.
+ */
+
+/**
+ * Expresión regular para validar formato UUID v4.
+ */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Expresión regular básica para validar formato de email.
+ * Nota: Esta es una validación básica. Para validación estricta, usar una biblioteca especializada.
+ */
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Expresión regular para validar formato de teléfono E.164.
+ * E.164 requiere: + seguido de 1-3 dígitos del código de país, luego 1-14 dígitos adicionales.
+ * Mínimo total: + seguido de al menos 7 dígitos (código de país + número local).
+ */
+const E164_PHONE_REGEX = /^\+[1-9]\d{6,14}$/;
+
+/**
+ * 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
+ * ```
+ */
+export function isValidUuid(value: string): boolean {
+  return UUID_V4_REGEX.test(value);
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isValidEmail(value: string): boolean {
+  return EMAIL_REGEX.test(value);
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isValidUrl(value: string): boolean {
+  try {
+    // URL está disponible en Node.js 18+ y navegadores modernos
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+    const URLConstructor = (globalThis as unknown as { URL?: new (url: string) => unknown }).URL;
+    
+    if (URLConstructor) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      new URLConstructor(value);
+      return true;
+    }
+    // Fallback para entornos sin URL global
+    return /^https?:\/\/.+\..+/.test(value);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isValidE164Phone(value: string): boolean {
+  return E164_PHONE_REGEX.test(value);
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isValidIso8601(value: string): boolean {
+  const date = new Date(value);
+  return !isNaN(date.getTime()) && value === date.toISOString();
+}
+
+/**
+ * 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
+ * ```
+ */
+export function hasRequiredKeys<T extends Record<string, unknown>>(
+  obj: T,
+  requiredKeys: (keyof T)[]
+): boolean {
+  return requiredKeys.every((key) => key in obj);
+}

package/src/versioning.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isValidSemanticVersion,
+  parseSemanticVersion,
+  compareSemanticVersions,
+  isVersionGreaterThan,
+  isVersionLessThan,
+  isVersionGreaterOrEqual,
+  isVersionLessOrEqual,
+  type SemanticVersion,
+} from './versioning';
+
+describe('versioning', () => {
+  describe('isValidSemanticVersion', () => {
+    it('debe validar versiones semánticas correctas', () => {
+      expect(isValidSemanticVersion('1.0.0')).toBe(true);
+      expect(isValidSemanticVersion('0.1.0')).toBe(true);
+      expect(isValidSemanticVersion('10.20.30')).toBe(true);
+    });
+
+    it('debe rechazar versiones inválidas', () => {
+      expect(isValidSemanticVersion('1.0')).toBe(false);
+      expect(isValidSemanticVersion('1.0.0.0')).toBe(false);
+      expect(isValidSemanticVersion('1.0.0-beta')).toBe(false);
+      expect(isValidSemanticVersion('invalid')).toBe(false);
+      expect(isValidSemanticVersion('')).toBe(false);
+    });
+  });
+
+  describe('parseSemanticVersion', () => {
+    it('debe parsear versiones válidas correctamente', () => {
+      expect(parseSemanticVersion('1.2.3')).toEqual({
+        major: 1,
+        minor: 2,
+        patch: 3,
+      });
+      expect(parseSemanticVersion('10.20.30')).toEqual({
+        major: 10,
+        minor: 20,
+        patch: 30,
+      });
+    });
+
+    it('debe retornar null para versiones inválidas', () => {
+      expect(parseSemanticVersion('1.0')).toBeNull();
+      expect(parseSemanticVersion('invalid')).toBeNull();
+      expect(parseSemanticVersion('')).toBeNull();
+    });
+  });
+
+  describe('compareSemanticVersions', () => {
+    it('debe comparar versiones correctamente', () => {
+      expect(compareSemanticVersions('1.0.0', '1.0.0')).toBe(0);
+      expect(compareSemanticVersions('1.0.0', '1.0.1')).toBe(-1);
+      expect(compareSemanticVersions('1.0.1', '1.0.0')).toBe(1);
+      expect(compareSemanticVersions('1.1.0', '1.0.0')).toBe(1);
+      expect(compareSemanticVersions('2.0.0', '1.9.9')).toBe(1);
+    });
+
+    it('debe lanzar error para versiones inválidas', () => {
+      expect(() => compareSemanticVersions('invalid', '1.0.0')).toThrow();
+      expect(() => compareSemanticVersions('1.0.0', 'invalid')).toThrow();
+    });
+  });
+
+  describe('isVersionGreaterThan', () => {
+    it('debe retornar true cuando version1 > version2', () => {
+      expect(isVersionGreaterThan('2.0.0', '1.9.9')).toBe(true);
+      expect(isVersionGreaterThan('1.1.0', '1.0.9')).toBe(true);
+      expect(isVersionGreaterThan('1.0.1', '1.0.0')).toBe(true);
+    });
+
+    it('debe retornar false cuando version1 <= version2', () => {
+      expect(isVersionGreaterThan('1.0.0', '1.0.0')).toBe(false);
+      expect(isVersionGreaterThan('1.0.0', '2.0.0')).toBe(false);
+    });
+  });
+
+  describe('isVersionLessThan', () => {
+    it('debe retornar true cuando version1 < version2', () => {
+      expect(isVersionLessThan('1.0.0', '2.0.0')).toBe(true);
+      expect(isVersionLessThan('1.0.0', '1.1.0')).toBe(true);
+    });
+
+    it('debe retornar false cuando version1 >= version2', () => {
+      expect(isVersionLessThan('1.0.0', '1.0.0')).toBe(false);
+      expect(isVersionLessThan('2.0.0', '1.0.0')).toBe(false);
+    });
+  });
+
+  describe('isVersionGreaterOrEqual', () => {
+    it('debe retornar true cuando version1 >= version2', () => {
+      expect(isVersionGreaterOrEqual('2.0.0', '1.0.0')).toBe(true);
+      expect(isVersionGreaterOrEqual('1.0.0', '1.0.0')).toBe(true);
+    });
+
+    it('debe retornar false cuando version1 < version2', () => {
+      expect(isVersionGreaterOrEqual('1.0.0', '2.0.0')).toBe(false);
+    });
+  });
+
+  describe('isVersionLessOrEqual', () => {
+    it('debe retornar true cuando version1 <= version2', () => {
+      expect(isVersionLessOrEqual('1.0.0', '2.0.0')).toBe(true);
+      expect(isVersionLessOrEqual('1.0.0', '1.0.0')).toBe(true);
+    });
+
+    it('debe retornar false cuando version1 > version2', () => {
+      expect(isVersionLessOrEqual('2.0.0', '1.0.0')).toBe(false);
+    });
+  });
+});

package/src/versioning.ts

@@ -0,0 +1,156 @@
+/**
+ * Representa una versión semántica en formato MAJOR.MINOR.PATCH
+ * 
+ * @example
+ * ```typescript
+ * const version: SemanticVersion = '1.2.3';
+ * ```
+ */
+export 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
+ */
+export 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
+ * ```
+ */
+export function isValidSemanticVersion(version: string): version is SemanticVersion {
+  return /^\d+\.\d+\.\d+$/.test(version);
+}
+
+/**
+ * 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
+ * ```
+ */
+export function parseSemanticVersion(version: string): {
+  major: number;
+  minor: number;
+  patch: number;
+} | null {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) return null;
+  
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+  };
+}
+
+/**
+ * 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
+ * ```
+ */
+export function compareSemanticVersions(
+  version1: string,
+  version2: string
+): number {
+  const v1 = parseSemanticVersion(version1);
+  const v2 = parseSemanticVersion(version2);
+  
+  if (!v1 || !v2) {
+    throw new Error(`Invalid semantic version: ${!v1 ? version1 : version2}`);
+  }
+  
+  if (v1.major !== v2.major) {
+    return v1.major - v2.major;
+  }
+  
+  if (v1.minor !== v2.minor) {
+    return v1.minor - v2.minor;
+  }
+  
+  return v1.patch - v2.patch;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isVersionGreaterThan(version1: string, version2: string): boolean {
+  return compareSemanticVersions(version1, version2) > 0;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function isVersionLessThan(version1: string, version2: string): boolean {
+  return compareSemanticVersions(version1, version2) < 0;
+}
+
+/**
+ * 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
+ */
+export function isVersionGreaterOrEqual(version1: string, version2: string): boolean {
+  return compareSemanticVersions(version1, version2) >= 0;
+}
+
+/**
+ * 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
+ */
+export function isVersionLessOrEqual(version1: string, version2: string): boolean {
+  return compareSemanticVersions(version1, version2) <= 0;
+}