{"_id":"@atlas-id/contracts","_rev":"3-b02d8109c183af784efd58663c9cdcea","name":"@atlas-id/contracts","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@atlas-id/contracts","version":"0.1.0","author":{"name":"Opendex, Inc."},"license":"UNLICENSED","_id":"@atlas-id/contracts@0.1.0","maintainers":[{"name":"agrufino","email":"agrufino@cloud.opendex.dev"}],"dist":{"shasum":"8b528354338caa20162154d74ee5d877e8f88105","tarball":"https://registry.npmjs.org/@atlas-id/contracts/-/contracts-0.1.0.tgz","fileCount":17,"integrity":"sha512-zW8PIHupYVcxZXbeSaW9nDY7InrFDf27blXq53mqw9hBjZb1/niYaOyEvJfIkVWgyy4L+uy0DmXGPTh8LS46VA==","signatures":[{"sig":"MEQCIDRdZro9hB6GW/pbREWSTgocsOyntvW63jbysuXQGdyYAiAmL4Uj5wGn9DpiywR1odHJ0yzXbxNiS91GG5vWHYOpug==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61848},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/esm/index.js","require":{"default":"./dist/index.js"}},"./dist/*":{"types":"./dist/*.d.ts","default":"./dist/esm/*.js","require":{"default":"./dist/*.js"}}},"gitHead":"49cae38f54687fc25c86c208ad470604d8321557","scripts":{"lint":"eslint --ext .ts .","test":"vitest run","build":"rimraf dist && tsup-node","clean":"rimraf dist && rimraf node_modules","lint:fix":"eslint --ext .ts . --fix","prebuild":"pnpm typecheck && pnpm lint && pnpm test","typecheck":"tsc --noEmit","test:watch":"vitest watch","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"agrufino","email":"agrufino@cloud.opendex.dev"},"_npmVersion":"11.7.0","description":"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.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.23.8"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","husky":"^9.0.11","eslint":"^8.57.1","rimraf":"^6.1.2","vitest":"^4.0.16","typescript":"5.3.3","@vitest/coverage-v8":"^4.0.16","@typescript-eslint/parser":"^7.18.0","@typescript-eslint/eslint-plugin":"^7.18.0"},"peerDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/contracts_0.1.0_1767429824610_0.3120498950248678","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@atlas-id/contracts","version":"0.2.0","author":{"name":"Opendex, Inc."},"license":"UNLICENSED","_id":"@atlas-id/contracts@0.2.0","maintainers":[{"name":"agrufino","email":"agrufino@cloud.opendex.dev"}],"dist":{"shasum":"916a6e6784454fdd194b33b6646789bce14a8ba1","tarball":"https://registry.npmjs.org/@atlas-id/contracts/-/contracts-0.2.0.tgz","fileCount":22,"integrity":"sha512-wac3JPSi51vks+Pk/HhluShDfsDYHtMwm5x2QIDFjqfiq1LzLJTr6ybaALH9nOatA+6Wwi7My4RDasgSm4TFLw==","signatures":[{"sig":"MEYCIQCUf+IwGkMjec8xNRI13mfwjUebx5assldbJ9zJT6/6WwIhAKeIPN1ulsNb4yhbfmRPHemxI+5E6Had29rAShI7k6jS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":201771},"type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/esm/index.js","require":{"default":"./dist/index.js"}},"./dist/*":{"types":"./dist/*.d.ts","default":"./dist/esm/*.js","require":{"default":"./dist/*.js"}}},"gitHead":"49cae38f54687fc25c86c208ad470604d8321557","scripts":{"lint":"eslint --ext .ts .","test":"vitest run","build":"rimraf dist && tsup-node","clean":"rimraf dist && rimraf node_modules","lint:fix":"eslint --ext .ts . --fix","prebuild":"pnpm typecheck && pnpm lint && pnpm test","typecheck":"tsc --noEmit","test:watch":"vitest watch","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"agrufino","email":"agrufino@cloud.opendex.dev"},"_npmVersion":"11.7.0","description":"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.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.23.8"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","husky":"^9.0.11","eslint":"^8.57.1","rimraf":"^6.1.2","vitest":"^4.0.16","typescript":"5.3.3","@vitest/coverage-v8":"^4.0.16","@typescript-eslint/parser":"^7.18.0","@typescript-eslint/eslint-plugin":"^7.18.0"},"peerDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/contracts_0.2.0_1767431574888_0.24008196970665008","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@atlas-id/contracts","version":"0.2.1","license":"UNLICENSED","author":{"name":"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"},"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"},"gitHead":"49cae38f54687fc25c86c208ad470604d8321557","_id":"@atlas-id/contracts@0.2.1","description":"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.","_nodeVersion":"24.12.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-vLsT+UCqJO5npwhFFBpP0gnNf6aomeMVCRS9HrCPhzJZBE+eHRZg72y3/V8hBcrd+XzZZuR4zA59APhoYaFikQ==","shasum":"3cdf41bf0fcf2e892aaebba19b065178a8af4ec4","tarball":"https://registry.npmjs.org/@atlas-id/contracts/-/contracts-0.2.1.tgz","fileCount":22,"unpackedSize":201259,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD1cnEot8xgjg/7l4XNvk+WOmFhLpVHaKJ9bopeYBYtRwIhAN9/A3JZC5ww+KuGMBlvX6uTKBZgMTl40sH7/H9EqvNL"}]},"_npmUser":{"name":"agrufino","email":"agrufino@cloud.opendex.dev"},"directories":{},"maintainers":[{"name":"agrufino","email":"agrufino@cloud.opendex.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/contracts_0.2.1_1767432861045_0.2546494250997977"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-03T08:43:44.528Z","modified":"2026-01-03T09:34:21.501Z","0.1.0":"2026-01-03T08:43:44.756Z","0.2.0":"2026-01-03T09:12:55.028Z","0.2.1":"2026-01-03T09:34:21.270Z"},"author":{"name":"Opendex, Inc."},"license":"UNLICENSED","description":"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.","maintainers":[{"name":"agrufino","email":"agrufino@cloud.opendex.dev"}],"readme":"## Opendex Atlas ID Contracts\n\nBiblioteca 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.\n\n**Propiedad de Opendex, Inc.** - Este software es propietario y no es de código abierto.\n\n## Función Principal\n\nEste 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:\n\n- Definiciones de tipos TypeScript para eventos, notificaciones y conexiones OAuth\n- Contratos de eventos con versionado semántico\n- Esquemas de validación en runtime\n- Utilidades de validación y type guards\n\n## Arquitectura\n\nEl proyecto está organizado en módulos especializados:\n\n### Eventos\n\nDefine la estructura base para eventos en sistemas distribuidos con soporte para:\n- Versionado semántico de contratos\n- Metadata de trazabilidad (traceId, spanId, correlationId, causationId)\n- Soporte para multi-tenancy (tenantId, projectId)\n- Identificación de origen (source)\n\n### Notificaciones\n\nContratos para el sistema de notificaciones que soporta múltiples canales:\n- Email con soporte para templates, variables, CC, BCC y reply-to\n- SMS con templates y variables\n- Webhooks con versionado de firmas y payloads personalizados\n\nIncluye estados del ciclo de vida: requested, scheduled, dispatched, delivered, failed, cancelled.\n\n### Conexiones OAuth\n\nContratos para gestión de conexiones OAuth con soporte para:\n- Múltiples protocolos: OAuth2, OIDC, SAML\n- Gestión de tokens (access, refresh, ID tokens)\n- Estados de conexión: active, refreshing, revoked, expired\n- Soporte para PKCE y webhooks de refresh\n\n### Versionado\n\nUtilidades para trabajar con versionado semántico:\n- Validación de formato de versiones\n- Parsing y comparación de versiones\n- Funciones de comparación (mayor que, menor que, igual)\n\n## Uso\n\n### Instalación\n\n```bash\npnpm add @atlas-id/contracts\n```\n\n### Importación de Tipos\n\n```typescript\nimport type {\n  EventEnvelope,\n  NotificationRequest,\n  OAuthConnection,\n  SemanticVersion,\n} from '@atlas-id/contracts';\n```\n\n### Uso de Contratos de Eventos\n\n```typescript\nimport { notificationEvents } from '@atlas-id/contracts';\n\n// El contrato incluye el tipo, versión, schema y un ejemplo\nconst event = {\n  ...notificationEvents.requested.example,\n  id: 'evt_custom_123',\n  occurredAt: new Date().toISOString(),\n  payload: {\n    notification: {\n      // ... datos de la notificación\n    },\n  },\n};\n```\n\n### Validación en Runtime\n\n```typescript\nimport {\n  notificationRequestSchema,\n  createEventEnvelopeSchema,\n} from '@atlas-id/contracts';\n\n// Validar una solicitud de notificación\nconst result = notificationRequestSchema.safeParse(requestData);\nif (result.success) {\n  // requestData es válido\n} else {\n  // result.error contiene los errores de validación\n}\n```\n\n### Type Guards\n\n```typescript\nimport {\n  isEmailNotificationRequest,\n  isSmsNotificationRequest,\n  isWebhookNotificationRequest,\n} from '@atlas-id/contracts';\n\nfunction processNotification(request: NotificationRequest) {\n  if (isEmailNotificationRequest(request)) {\n    // TypeScript sabe que request es EmailNotificationRequest\n    console.log(request.to);\n  } else if (isSmsNotificationRequest(request)) {\n    // TypeScript sabe que request es SmsNotificationRequest\n    console.log(request.to);\n  }\n}\n```\n\n### Utilidades de Validación\n\n```typescript\nimport {\n  isValidUuid,\n  isValidEmail,\n  isValidUrl,\n  isValidE164Phone,\n  isValidIso8601,\n} from '@atlas-id/contracts';\n\nif (isValidUuid(userId)) {\n  // userId es un UUID válido\n}\n\nif (isValidEmail(email)) {\n  // email tiene formato válido\n}\n```\n\n### Versionado Semántico\n\n```typescript\nimport {\n  isValidSemanticVersion,\n  parseSemanticVersion,\n  compareSemanticVersions,\n  isVersionGreaterThan,\n} from '@atlas-id/contracts';\n\nif (isValidSemanticVersion('1.2.3')) {\n  const parsed = parseSemanticVersion('1.2.3');\n  // { major: 1, minor: 2, patch: 3 }\n}\n\nif (isVersionGreaterThan('2.0.0', '1.9.9')) {\n  // La versión 2.0.0 es mayor que 1.9.9\n}\n```\n\n## Estructura de Contratos\n\nCada contrato de evento sigue la estructura:\n\n```typescript\n{\n  type: string;           // Tipo del evento (ej: 'notifications.requested')\n  version: SemanticVersion; // Versión semántica del contrato\n  schema: string;         // Identificador del schema (tipo@version)\n  example: EventEnvelope; // Ejemplo completo del evento\n}\n```\n\nLos eventos incluyen metadata de trazabilidad:\n\n```typescript\n{\n  traceId?: string;        // ID de traza para distributed tracing\n  spanId?: string;         // ID de span dentro de la traza\n  correlationId?: string;  // ID para correlacionar eventos relacionados\n  causationId?: string;    // ID del evento que causó este evento\n  tenantId?: string;       // ID del tenant (multi-tenancy)\n  projectId?: string;      // ID del proyecto\n  source: string;          // Servicio que originó el evento\n}\n```\n\n## Validación\n\nEl paquete proporciona validación en dos niveles:\n\n1. **Compilación**: TypeScript valida los tipos en tiempo de compilación\n2. **Runtime**: Zod valida los datos en tiempo de ejecución\n\nLos esquemas de Zod están disponibles para validar:\n- Event envelopes\n- Notification requests\n- OAuth connections\n- Token sets\n- Versiones semánticas\n\n## Constantes\n\nLos tipos de eventos están centralizados en constantes para evitar errores de tipeo:\n\n```typescript\nimport {\n  NOTIFICATION_EVENT_TYPES,\n  OAUTH_CONNECTION_EVENT_TYPES,\n} from '@atlas-id/contracts';\n\n// En lugar de 'notifications.requested'\nconst eventType = NOTIFICATION_EVENT_TYPES.REQUESTED;\n```\n\n## Desarrollo\n\n### Scripts Disponibles\n\n- `pnpm build`: Compila el proyecto TypeScript\n- `pnpm typecheck`: Valida tipos sin compilar\n- `pnpm test`: Ejecuta tests unitarios\n- `pnpm test:watch`: Ejecuta tests en modo watch\n- `pnpm test:coverage`: Genera reporte de cobertura\n- `pnpm lint`: Ejecuta ESLint\n- `pnpm lint:fix`: Ejecuta ESLint y corrige errores automáticamente\n- `pnpm clean`: Limpia directorios de build y node_modules\n\n### Estructura del Proyecto\n\n```\nsrc/\n  events.ts              # Tipos y contratos base de eventos\n  notifications.ts       # Contratos de notificaciones\n  oauth-connections.ts   # Contratos de conexiones OAuth\n  versioning.ts          # Utilidades de versionado semántico\n  utils/\n    validation.ts        # Utilidades de validación\n  schemas/\n    index.ts             # Esquemas Zod para validación runtime\n  *.test.ts              # Tests unitarios\n```\n\n### Tests\n\nLos tests validan:\n- Funcionalidad de utilidades de versionado\n- Type guards y discriminación de tipos\n- Validación de formatos (UUID, email, URL, etc.)\n- Estructura y validez de ejemplos en contratos\n- Esquemas de validación Zod\n\n### Contribución\n\nAl agregar nuevos contratos o modificar existentes:\n\n1. Actualizar los tipos TypeScript\n2. Agregar documentación JSDoc\n3. Crear o actualizar esquemas Zod\n4. Agregar ejemplos en los contratos\n5. Escribir tests unitarios\n6. Actualizar el CHANGELOG.md\n\nLos cambios que modifiquen la estructura de contratos existentes deben incrementar la versión semántica del contrato afectado.\n\n## Compatibilidad\n\n- Node.js: 18+\n- TypeScript: 5.3+\n- ESM y CommonJS soportados\n","readmeFilename":"README.md"}