asyncapi.yaml

asyncapi: 3.1.0
info:
  title: ALOVIDA Health API — Eventos de dominio y colas
  version: "0.0.1"
  description: >
    Catálogo de eventos de dominio y colas de trabajo del backend ALOVIDA Health.
    El mecanismo real es un outbox transaccional propio sobre PostgreSQL
    (módulo `messaging`, ver docs/events/overview.md), no un broker de mensajería
    dedicado (Kafka/RabbitMQ) — ver ADR-0007 y ADR-0019. Los "canales" HTTP
    /internal/* descritos aquí son el mecanismo real de publicación/reclamo/entrega,
    no un protocolo de mensajería estándar.
  license:
    name: UNLICENSED

defaultContentType: application/json

servers:
  local:
    host: localhost:3000
    protocol: http
    description: >
      No hay broker de mensajería como servidor independiente — el "servidor" de
      estos canales es la propia API HTTP (endpoints /internal/*), autenticados con
      JWT de servicio.

channels:
  domainEvents:
    address: /internal/events/{domainEventId}/dispatch
    description: >
      Despacho de un evento de dominio ya publicado en el outbox hacia sus
      suscriptores activos (event_subscriptions). UC-35-03.
    parameters:
      domainEventId:
        description: Identificador del evento en `messaging.domain_events`.
    messages:
      domainEvent:
        $ref: '#/components/messages/DomainEvent'

  outboxRelay:
    address: /internal/outbox/relay/run
    description: >
      Reclama (FOR UPDATE SKIP LOCKED) y publica mensajes pendientes del outbox.
      UC-35-02.
    messages:
      outboxMessage:
        $ref: '#/components/messages/OutboxMessage'

  queueJobs:
    address: /internal/queues/{code}/claim
    description: >
      Reclamo de jobs de una cola de trabajo genérica (SKIP LOCKED + visibility
      timeout). UC-35-06.
    parameters:
      code:
        description: Código de `messaging.message_queues` (ver MESSAGING_QUEUE_CODES).
    messages:
      queuedJob:
        $ref: '#/components/messages/QueuedJob'

  eventDeliveryAck:
    address: /internal/event-deliveries/{id}/ack
    description: Acuse de un consumidor sobre una entrega de evento. UC-35-04.
    parameters:
      id:
        description: Identificador de `messaging.event_deliveries`.
    messages:
      deliveryAck:
        $ref: '#/components/messages/DeliveryAck'

  providerWebhookReceipt:
    address: /webhooks/providers/{providerCode}/receipts
    description: >
      Acuse de entrega enviado por un proveedor externo de canal (SMS/email/push),
      autenticado por firma (no JWT). UC-35-12. Único canal de este documento con
      un productor externo al propio backend.
    parameters:
      providerCode:
        description: Código del proveedor de mensajería/canal externo.
    messages:
      providerReceipt:
        $ref: '#/components/messages/ProviderReceipt'

operations:
  publishDomainEvent:
    action: send
    channel:
      $ref: '#/channels/domainEvents'
    summary: >
      Un módulo de negocio publica un evento de dominio dentro de su propia
      transacción (OutboxService.publishDomainEvent — sin endpoint HTTP propio,
      UC-35-01 es interno).

  dispatchEvent:
    action: receive
    channel:
      $ref: '#/channels/domainEvents'
    summary: worker-messaging despacha el evento a cada suscripción que coincide con el filtro.

  relayOutbox:
    action: send
    channel:
      $ref: '#/channels/outboxRelay'
    summary: worker-messaging reclama y publica mensajes pendientes del outbox.

  claimQueueJob:
    action: receive
    channel:
      $ref: '#/channels/queueJobs'
    summary: Cualquiera de los 17 workers reclama trabajo pendiente de su cola.

  ackDelivery:
    action: send
    channel:
      $ref: '#/channels/eventDeliveryAck'
    summary: Un consumidor confirma que procesó una entrega.

  receiveProviderReceipt:
    action: receive
    channel:
      $ref: '#/channels/providerWebhookReceipt'
    summary: Un proveedor externo confirma el estado final de una notificación enviada.

components:
  messages:
    DomainEvent:
      name: DomainEvent
      title: Evento de dominio
      summary: >
        Envelope real de messaging.domain_events. Ver docs/events/event-catalog.md
        para los 79 valores reales de eventType observados en código (79 sitios de
        publishDomainEvent en 10 módulos productores).
      payload:
        $ref: '#/components/schemas/DomainEventPayload'

    OutboxMessage:
      name: OutboxMessage
      title: Mensaje de outbox
      summary: Estado de publicación de un domain event (pending → published | failed).
      payload:
        type: object
        properties:
          outboxMessageId:
            type: string
            format: uuid
          domainEventId:
            type: string
            format: uuid
          status:
            type: string
            enum: [pending, published, failed]
          attempts:
            type: integer

    QueuedJob:
      name: QueuedJob
      title: Job de cola
      summary: Job genérico reclamado con SKIP LOCKED + visibility timeout.
      payload:
        type: object
        properties:
          jobId:
            type: string
            format: uuid
          queueCode:
            type: string
          status:
            type: string
            enum: [ready, running, succeeded, dead_letter]
          attempts:
            type: integer
          payload:
            type: object
            description: >
              Sin JSON Schema fijo — cada cola define su propia forma de payload
              (ver docs/events/event-catalog.md §"Esquema de payload — no tipado por evento").

    DeliveryAck:
      name: DeliveryAck
      title: Acuse de entrega
      payload:
        type: object
        properties:
          eventDeliveryId:
            type: string
            format: uuid
          acknowledgedAt:
            type: string
            format: date-time

    ProviderReceipt:
      name: ProviderReceipt
      title: Acuse de proveedor externo
      summary: Autenticado por firma (verifySignature), fail-closed ante firma inválida.
      payload:
        type: object
        properties:
          signature:
            type: string
          status:
            type: string
            enum: [delivered, bounced]

  schemas:
    DomainEventPayload:
      type: object
      required: [eventType, aggregateType, aggregateId, payloadJson]
      properties:
        eventType:
          type: string
          description: >
            Sin convención de nombres única — PascalCase (mayoría) o dot.case
            (authz.break_glass.activated, periop.case.confirmation_blocked).
            Ver docs/events/event-catalog.md para el catálogo completo.
        aggregateType:
          type: string
          description: Tipo del agregado que originó el evento (p. ej. "orders").
        aggregateId:
          type: string
          format: uuid
        payloadJson:
          type: object
          additionalProperties: true
          description: >
            Sin JSON Schema validado por tipo de evento en código
            (Record<string, unknown> en TypeScript) — objeto genérico aquí a
            propósito, no se fabrica un schema por evento sin evidencia.