asyncapi: '2.6.0'
info:
  title: Search Service Async API
  version: '2.1.0'
  description: |
    AsyncAPI documentation for search-svc Kafka events.

    This service provides hybrid BM25 + Vector semantic search capabilities with:
    - Search query tracking and analytics
    - Alert notifications for saved searches
    - Entity indexing and reindexing events
    - Autocomplete interaction tracking
    - Slow query monitoring and optimization alerts
    - Integration with event, venue, artist, brand, destination, user, team,
      review, inventory, taxonomy, and subscription services

    All events follow the CloudEvents specification v1.0.
    All Kafka messages are partitioned by tenant_id for multi-tenant isolation.
  contact:
    name: EventZR Engineering
    email: engineering@eventzr.com
    url: https://developer.eventzr.com
  license:
    name: Proprietary
    url: https://eventzr.com/license

servers:
  development:
    url: localhost:9092
    protocol: kafka
    description: Local Kafka (Docker Compose)
  staging:
    url: b-1.eventzr-msk-staging.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Staging)
  production:
    url: b-1.eventzr-msk-prod.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (Production)

defaultContentType: application/cloudevents+json

channels:
  # ==================== PRODUCED EVENTS ====================

  search.analytics:
    description: Search execution analytics events for tracking and billing
    publish:
      operationId: publishSearchExecuted
      summary: Publish search executed event
      description: |
        Emitted after every search query execution. Contains query details,
        results count, timing, and AI credits consumed. Used by analytics-svc
        for dashboard metrics and wallet-svc for credit billing.
      message:
        $ref: '#/components/messages/SearchExecutedEvent'
      bindings:
        kafka:
          groupId: search-svc-analytics-producer
          clientId: search-svc

  search.queries:
    description: Detailed search query events for trending calculation and failure tracking
    publish:
      operationId: publishSearchQuery
      summary: Publish search query event
      description: |
        Emitted for every search query with detailed metadata including search method,
        cache usage, semantic search usage, AI expansion, personalization flags,
        and credit consumption. Also publishes query failure events.
      message:
        oneOf:
          - $ref: '#/components/messages/SearchQueryEvent'
          - $ref: '#/components/messages/SearchQueryFailedEvent'
      bindings:
        kafka:
          groupId: search-svc-queries-producer
          clientId: search-svc

  search.interactions:
    description: User interaction events (clicks, autocomplete) for ranking improvement
    publish:
      operationId: publishSearchInteraction
      summary: Publish search interaction events
      description: |
        Emitted when users interact with search results (clicks) or autocomplete
        suggestions. Used for learning-to-rank model training and autocomplete
        quality improvement.
      message:
        oneOf:
          - $ref: '#/components/messages/SearchClickEvent'
          - $ref: '#/components/messages/AutocompleteEvent'
          - $ref: '#/components/messages/AutocompleteSelectedEvent'
      bindings:
        kafka:
          groupId: search-svc-interactions-producer
          clientId: search-svc

  search.indexing:
    description: Document indexing events for tracking index health
    publish:
      operationId: publishSearchIndexed
      summary: Publish entity indexed event
      description: |
        Emitted when documents are added, updated, or deleted from Elasticsearch
        indexes. Includes single-document and bulk operations. Used for monitoring
        index health and replication tracking.
      message:
        oneOf:
          - $ref: '#/components/messages/SearchIndexedEvent'
          - $ref: '#/components/messages/SearchIndexedBulkEvent'
      bindings:
        kafka:
          groupId: search-svc-indexing-producer
          clientId: search-svc

  search.saved-searches:
    description: Saved search lifecycle events
    publish:
      operationId: publishSavedSearchCreated
      summary: Publish saved search created event
      description: |
        Emitted when a user creates a new saved search. Used for user
        personalization tracking and analytics.
      message:
        $ref: '#/components/messages/SavedSearchCreatedEvent'
      bindings:
        kafka:
          groupId: search-svc-saved-searches-producer
          clientId: search-svc

  search.alerts:
    description: Search alert events for notification delivery
    publish:
      operationId: publishAlertTriggered
      summary: Publish alert triggered event
      description: |
        Emitted when a saved search alert finds new matching results.
        Consumed by notify-svc to send notifications via WhatsApp, email, or push.
        Also publishes alert configuration change events.
      message:
        oneOf:
          - $ref: '#/components/messages/AlertTriggeredEvent'
          - $ref: '#/components/messages/AlertConfigChangedEvent'
      bindings:
        kafka:
          groupId: search-svc-alerts-producer
          clientId: search-svc

  eventzr.search.zero_results.v1:
    description: Zero results event topic for query optimization
    publish:
      operationId: publishZeroResults
      summary: Publish zero results event
      description: |
        Emitted when a search query returns zero results. Used for
        content gap analysis, query optimization, and synonym expansion.
      message:
        $ref: '#/components/messages/ZeroResultsEvent'
      bindings:
        kafka:
          groupId: search-svc-zero-results-producer
          clientId: search-svc

  eventzr.search.slow-query.report.v1:
    description: Slow query report events for performance monitoring
    publish:
      operationId: publishSlowQueryReport
      summary: Publish slow query report
      description: |
        Emitted periodically with aggregated slow query analysis. Contains
        pattern detection, affected tenants, and optimization suggestions.
      message:
        $ref: '#/components/messages/SlowQueryReportEvent'
      bindings:
        kafka:
          groupId: search-svc-slow-query-producer
          clientId: search-svc

  eventzr.search.slow-query.digest.v1:
    description: Daily slow query digest events
    publish:
      operationId: publishSlowQueryDigest
      summary: Publish daily slow query digest
      description: |
        Emitted daily with a comprehensive digest of slow queries per tenant.
        Used for proactive performance management.
      message:
        $ref: '#/components/messages/SlowQueryDigestEvent'

  eventzr.search.optimization.alert.v1:
    description: Optimization alert events for high-priority patterns
    publish:
      operationId: publishOptimizationAlert
      summary: Publish optimization alert
      description: |
        Emitted when recurring slow query patterns are detected that require
        immediate attention. Includes severity, affected tenants, and suggested fixes.
      message:
        $ref: '#/components/messages/OptimizationAlertEvent'

  eventzr.search.critical.alert.v1:
    description: Critical alert events for tenants with many slow queries
    publish:
      operationId: publishCriticalAlert
      summary: Publish critical performance alert
      description: |
        Emitted when a tenant exceeds critical slow query thresholds.
        Triggers immediate attention from the operations team.
      message:
        $ref: '#/components/messages/CriticalAlertEvent'

  # ==================== CONSUMED EVENTS ====================

  eventzr.event.created.v1:
    description: Event created in event-svc
    subscribe:
      operationId: handleEventCreated
      summary: Index new event in search
      description: |
        Consumed when a new event is created in event-svc.
        Indexes the event document in Elasticsearch and invalidates related caches.
      message:
        $ref: '#/components/messages/EventEntityEvent'

  eventzr.event.updated.v1:
    description: Event updated in event-svc
    subscribe:
      operationId: handleEventUpdated
      summary: Reindex updated event
      description: Updates the event document in Elasticsearch index.
      message:
        $ref: '#/components/messages/EventEntityEvent'

  eventzr.event.deleted.v1:
    description: Event deleted in event-svc
    subscribe:
      operationId: handleEventDeleted
      summary: Remove event from search index
      description: Deletes the event document from Elasticsearch and invalidates caches.
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.event.published.v1:
    description: Event published in event-svc
    subscribe:
      operationId: handleEventPublished
      summary: Mark event as searchable
      description: Updates event visibility to public and marks as searchable.
      message:
        $ref: '#/components/messages/EventEntityEvent'

  eventzr.event.cancelled.v1:
    description: Event cancelled in event-svc
    subscribe:
      operationId: handleEventCancelled
      summary: Mark event as cancelled in search
      description: Updates event status to cancelled in the search index.
      message:
        $ref: '#/components/messages/EventEntityEvent'

  eventzr.venue.created.v1:
    description: Venue created in venue-svc
    subscribe:
      operationId: handleVenueCreated
      summary: Index new venue in search
      description: Indexes venue with geo-coordinates for geo-spatial search.
      message:
        $ref: '#/components/messages/VenueEntityEvent'

  eventzr.venue.updated.v1:
    description: Venue updated in venue-svc
    subscribe:
      operationId: handleVenueUpdated
      summary: Reindex updated venue
      message:
        $ref: '#/components/messages/VenueEntityEvent'

  eventzr.venue.deleted.v1:
    description: Venue deleted in venue-svc
    subscribe:
      operationId: handleVenueDeleted
      summary: Remove venue from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.artist.created.v1:
    description: Artist created
    subscribe:
      operationId: handleArtistCreated
      summary: Index new artist in search
      message:
        $ref: '#/components/messages/ArtistEntityEvent'

  eventzr.artist.updated.v1:
    description: Artist updated
    subscribe:
      operationId: handleArtistUpdated
      summary: Reindex updated artist
      message:
        $ref: '#/components/messages/ArtistEntityEvent'

  eventzr.artist.deleted.v1:
    description: Artist deleted
    subscribe:
      operationId: handleArtistDeleted
      summary: Remove artist from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.brand.created.v1:
    description: Brand created in brand-svc
    subscribe:
      operationId: handleBrandCreated
      summary: Index new brand in search
      message:
        $ref: '#/components/messages/BrandEntityEvent'

  eventzr.brand.updated.v1:
    description: Brand updated in brand-svc
    subscribe:
      operationId: handleBrandUpdated
      summary: Reindex updated brand
      message:
        $ref: '#/components/messages/BrandEntityEvent'

  eventzr.brand.deleted.v1:
    description: Brand deleted in brand-svc
    subscribe:
      operationId: handleBrandDeleted
      summary: Remove brand from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.destination.created.v1:
    description: Destination created in destination-svc
    subscribe:
      operationId: handleDestinationCreated
      summary: Index new destination in search
      message:
        $ref: '#/components/messages/DestinationEntityEvent'

  eventzr.destination.updated.v1:
    description: Destination updated in destination-svc
    subscribe:
      operationId: handleDestinationUpdated
      summary: Reindex updated destination
      message:
        $ref: '#/components/messages/DestinationEntityEvent'

  eventzr.destination.deleted.v1:
    description: Destination deleted in destination-svc
    subscribe:
      operationId: handleDestinationDeleted
      summary: Remove destination from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.user.created.v1:
    description: User created in user-svc
    subscribe:
      operationId: handleUserCreated
      summary: Index new user in search
      message:
        $ref: '#/components/messages/UserEntityEvent'

  eventzr.user.updated.v1:
    description: User updated in user-svc
    subscribe:
      operationId: handleUserUpdated
      summary: Reindex updated user
      message:
        $ref: '#/components/messages/UserEntityEvent'

  eventzr.user.deleted.v1:
    description: User deleted in user-svc
    subscribe:
      operationId: handleUserDeleted
      summary: Remove user from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.team.created.v1:
    description: Team created in team-svc
    subscribe:
      operationId: handleTeamCreated
      summary: Index new team in search
      message:
        $ref: '#/components/messages/TeamEntityEvent'

  eventzr.team.updated.v1:
    description: Team updated in team-svc
    subscribe:
      operationId: handleTeamUpdated
      summary: Reindex updated team
      message:
        $ref: '#/components/messages/TeamEntityEvent'

  eventzr.team.deleted.v1:
    description: Team deleted in team-svc
    subscribe:
      operationId: handleTeamDeleted
      summary: Remove team from search index
      message:
        $ref: '#/components/messages/EntityDeletedEvent'

  eventzr.taxonomy.updated.v1:
    description: Taxonomy updated in taxonomy-svc
    subscribe:
      operationId: handleTaxonomyUpdated
      summary: Update category/tag mappings in search
      description: |
        Consumed when taxonomy categories or tags are updated.
        Refreshes search facet configurations and category-based filters.
      message:
        $ref: '#/components/messages/TaxonomyUpdatedEvent'

  eventzr.subscription.tier_changed.v1:
    description: User subscription tier changed in subscriptions-svc
    subscribe:
      operationId: handleTierChanged
      summary: Update user quotas and rate limits
      description: |
        Consumed when a user's subscription tier changes (upgrade/downgrade).
        Updates search quotas, rate limit configurations, and invalidates
        tier-related caches.
      message:
        $ref: '#/components/messages/TierChangedEvent'

  eventzr.ticketing.inventory_updated.v1:
    description: Ticket inventory updated in ticketing-svc
    subscribe:
      operationId: handleTicketInventoryUpdated
      summary: Update event availability in search
      description: |
        Consumed when ticket inventory changes (sold, reserved, released).
        Updates event availability status and pricing in the search index
        for real-time availability filtering.
      message:
        $ref: '#/components/messages/TicketInventoryUpdatedEvent'

  eventzr.review.created.v1:
    description: Review created in reviews-svc
    subscribe:
      operationId: handleReviewCreated
      summary: Update entity rating in search
      description: |
        Consumed when a new review is created for any searchable entity.
        Updates aggregated rating scores in the search index for
        rating-based filtering and sorting.
      message:
        $ref: '#/components/messages/ReviewCreatedEvent'

  eventzr.search.entity_indexed.v1:
    description: Entity indexed confirmation event
    subscribe:
      operationId: handleEntityIndexed
      summary: Process entity indexed confirmation
      description: |
        Consumed to track indexing progress and health.
        Updates indexing statistics and triggers cache warming.
      message:
        $ref: '#/components/messages/EntityIndexedEvent'

components:
  messages:
    # ==================== PRODUCED MESSAGES ====================

    SearchExecutedEvent:
      name: SearchExecutedEvent
      title: Search Executed
      summary: Emitted after each search query execution
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.executed.v1
          tenant-id:
            type: string
            format: uuid
          user-id:
            type: string
          search-id:
            type: string
          entity-type:
            type: string
          used-semantic:
            type: string
      payload:
        $ref: '#/components/schemas/CloudEvent'
      traits:
        - $ref: '#/components/messageTraits/CloudEventHeaders'
      bindings:
        kafka:
          key:
            type: string
            description: '{tenantId}:{userId}:{searchId}'

    SearchQueryEvent:
      name: SearchQueryEvent
      title: Search Query
      summary: Detailed search query event for trending and analytics
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.query.v1
          tenant-id:
            type: string
          user-id:
            type: string
          search-method:
            type: string
            enum: [bm25, hybrid, vector]
          zero-results:
            type: string
            enum: ['true', 'false']
      payload:
        $ref: '#/components/schemas/SearchQueryPayload'

    SearchQueryFailedEvent:
      name: SearchQueryFailedEvent
      title: Search Query Failed
      summary: Emitted when a search query fails
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.query.failed.v1
          tenant-id:
            type: string
          user-id:
            type: string
          error-code:
            type: string
      payload:
        type: object
        properties:
          tenantId:
            type: string
          user_id:
            type: string
          query:
            type: string
          error_code:
            type: string
          error_message:
            type: string
          timestamp:
            type: string
            format: date-time

    ZeroResultsEvent:
      name: ZeroResultsEvent
      title: Zero Results
      summary: Emitted when a search returns zero results
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.zero_results.v1
          tenant-id:
            type: string
          user-id:
            type: string
          search-method:
            type: string
      payload:
        $ref: '#/components/schemas/ZeroResultsPayload'

    SearchClickEvent:
      name: SearchClickEvent
      title: Search Click
      summary: Emitted when a user clicks on a search result
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.click.v1
          tenant-id:
            type: string
          user-id:
            type: string
          search-id:
            type: string
      payload:
        $ref: '#/components/schemas/SearchClickPayload'

    AutocompleteEvent:
      name: AutocompleteEvent
      title: Autocomplete Interaction
      summary: Emitted for autocomplete interactions
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.autocomplete.v1
          tenant-id:
            type: string
          user-id:
            type: string
      payload:
        $ref: '#/components/schemas/AutocompletePayload'

    AutocompleteSelectedEvent:
      name: AutocompleteSelectedEvent
      title: Autocomplete Suggestion Selected
      summary: Emitted when user selects an autocomplete suggestion
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.autocomplete.selected.v1
          tenant-id:
            type: string
          user-id:
            type: string
      payload:
        type: object
        properties:
          tenantId:
            type: string
          user_id:
            type: string
          query:
            type: string
          selected_text:
            type: string
          selected_position:
            type: integer
          total_suggestions:
            type: integer
          timestamp:
            type: string
            format: date-time

    SearchIndexedEvent:
      name: SearchIndexedEvent
      title: Entity Indexed
      summary: Emitted when a document is indexed in Elasticsearch
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.indexed.v1
          tenant-id:
            type: string
          entity-type:
            type: string
          operation:
            type: string
            enum: [create, update, delete]
      payload:
        $ref: '#/components/schemas/SearchIndexedPayload'

    SearchIndexedBulkEvent:
      name: SearchIndexedBulkEvent
      title: Bulk Index Completed
      summary: Emitted when a bulk indexing operation completes
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.indexed.bulk.v1
          tenant-id:
            type: string
          entity-type:
            type: string
      payload:
        type: object
        properties:
          tenantId:
            type: string
          index_name:
            type: string
          entity_type:
            type: string
          success_count:
            type: integer
          failed_count:
            type: integer
          total_duration_ms:
            type: integer
          timestamp:
            type: string
            format: date-time

    SavedSearchCreatedEvent:
      name: SavedSearchCreatedEvent
      title: Saved Search Created
      summary: Emitted when a user creates a saved search
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.saved_search.created.v1
          tenant-id:
            type: string
          user-id:
            type: string
          saved-search-id:
            type: string
      payload:
        $ref: '#/components/schemas/SavedSearchCreatedPayload'

    AlertTriggeredEvent:
      name: AlertTriggeredEvent
      title: Alert Triggered
      summary: Emitted when a saved search alert has new matching results
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.alert.triggered.v1
          tenant-id:
            type: string
          user-id:
            type: string
      payload:
        $ref: '#/components/schemas/AlertTriggeredPayload'

    AlertConfigChangedEvent:
      name: AlertConfigChangedEvent
      title: Alert Configuration Changed
      summary: Emitted when alert settings are modified
      contentType: application/cloudevents+json
      headers:
        type: object
        properties:
          event-type:
            type: string
            const: eventzr.search.alert.config_changed.v1
          tenant-id:
            type: string
          user-id:
            type: string
      payload:
        type: object
        properties:
          tenantId:
            type: string
          user_id:
            type: string
          saved_search_id:
            type: string
          enabled:
            type: boolean
          frequency:
            type: string
            enum: [immediate, daily, weekly]
          timestamp:
            type: string
            format: date-time

    SlowQueryReportEvent:
      name: SlowQueryReportEvent
      title: Slow Query Report
      summary: Periodic aggregated slow query analysis
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    SlowQueryDigestEvent:
      name: SlowQueryDigestEvent
      title: Slow Query Digest
      summary: Daily slow query digest per tenant
      contentType: application/cloudevents+json
      payload:
        $ref: '#/components/schemas/CloudEvent'

    OptimizationAlertEvent:
      name: OptimizationAlertEvent
      title: Optimization Alert
      summary: Alert for recurring slow query patterns
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          severity:
            type: string
            enum: [high, medium, low]
          message:
            type: string
          pattern:
            type: string
          affectedTenants:
            type: array
            items:
              type: string
          suggestedFix:
            type: string
          timestamp:
            type: string
            format: date-time

    CriticalAlertEvent:
      name: CriticalAlertEvent
      title: Critical Performance Alert
      summary: Critical alert when tenant exceeds slow query thresholds
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          severity:
            type: string
            const: critical
          message:
            type: string
          totalSlowQueries:
            type: integer
          criticalCount:
            type: integer
          topIssues:
            type: array
            items:
              type: object
              properties:
                issue:
                  type: string
                count:
                  type: integer
          recommendations:
            type: array
            items:
              type: string
          timestamp:
            type: string
            format: date-time

    # ==================== CONSUMED MESSAGES ====================

    EventEntityEvent:
      name: EventEntityEvent
      title: Event Entity Lifecycle
      summary: Event created/updated/published/cancelled from event-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          title:
            type: string
          slug:
            type: string
          description:
            type: string
          start_date:
            type: string
            format: date-time
          end_date:
            type: string
            format: date-time
          venue_id:
            type: string
          categories:
            type: array
            items:
              type: string
          tags:
            type: array
            items:
              type: string
          status:
            type: string
          visibility:
            type: string

    VenueEntityEvent:
      name: VenueEntityEvent
      title: Venue Entity Lifecycle
      summary: Venue created/updated from venue-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          name:
            type: string
          slug:
            type: string
          description:
            type: string
          address:
            type: string
          city:
            type: string
          state:
            type: string
          country:
            type: string
          latitude:
            type: number
          longitude:
            type: number
          capacity:
            type: integer
          categories:
            type: array
            items:
              type: string
          amenities:
            type: array
            items:
              type: string

    ArtistEntityEvent:
      name: ArtistEntityEvent
      title: Artist Entity Lifecycle
      summary: Artist created/updated
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          name:
            type: string
          genres:
            type: array
            items:
              type: string

    BrandEntityEvent:
      name: BrandEntityEvent
      title: Brand Entity Lifecycle
      summary: Brand created/updated from brand-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          name:
            type: string
          description:
            type: string
          categories:
            type: array
            items:
              type: string

    DestinationEntityEvent:
      name: DestinationEntityEvent
      title: Destination Entity Lifecycle
      summary: Destination created/updated from destination-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          name:
            type: string
          description:
            type: string
          country:
            type: string
          city:
            type: string

    UserEntityEvent:
      name: UserEntityEvent
      title: User Entity Lifecycle
      summary: User created/updated from user-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          email:
            type: string
          name:
            type: string
          display_name:
            type: string
          interests:
            type: array
            items:
              type: string
          location:
            type: string

    TeamEntityEvent:
      name: TeamEntityEvent
      title: Team Entity Lifecycle
      summary: Team created/updated from team-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid
          name:
            type: string
          description:
            type: string

    EntityDeletedEvent:
      name: EntityDeletedEvent
      title: Entity Deleted
      summary: Entity deleted event (any entity type)
      contentType: application/cloudevents+json
      payload:
        type: object
        required:
          - id
          - tenantId
        properties:
          id:
            type: string
            format: uuid
          tenantId:
            type: string
            format: uuid

    TaxonomyUpdatedEvent:
      name: TaxonomyUpdatedEvent
      title: Taxonomy Updated
      summary: Category/tag mappings updated in taxonomy-svc
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          tenantId:
            type: string
            format: uuid
          taxonomy_type:
            type: string
          categories:
            type: array
            items:
              type: object
          tags:
            type: array
            items:
              type: object
          timestamp:
            type: string
            format: date-time

    TierChangedEvent:
      name: TierChangedEvent
      title: Subscription Tier Changed
      summary: User subscription tier upgraded/downgraded
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          subscription_id:
            type: string
          tenantId:
            type: string
            format: uuid
          user_id:
            type: string
          previous_tier:
            type: string
          new_tier:
            type: string
          change_reason:
            type: string
          effective_date:
            type: string
            format: date-time
          quota_changes:
            type: object
            properties:
              searches_per_day:
                type: integer
              saved_searches:
                type: integer
              ai_credits_monthly:
                type: integer
          timestamp:
            type: string
            format: date-time

    TicketInventoryUpdatedEvent:
      name: TicketInventoryUpdatedEvent
      title: Ticket Inventory Updated
      summary: Ticket availability changed for an event
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          event_id:
            type: string
          tenantId:
            type: string
            format: uuid
          ticket_type_id:
            type: string
          ticket_type_name:
            type: string
          available_quantity:
            type: integer
          total_quantity:
            type: integer
          reserved_quantity:
            type: integer
          sold_quantity:
            type: integer
          availability_status:
            type: string
            enum: [available, low_stock, sold_out, coming_soon]
          price:
            type: number
          currency:
            type: string
          timestamp:
            type: string
            format: date-time

    ReviewCreatedEvent:
      name: ReviewCreatedEvent
      title: Review Created
      summary: New review posted for a searchable entity
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          review_id:
            type: string
          tenantId:
            type: string
            format: uuid
          entity_id:
            type: string
          entity_type:
            type: string
            enum: [event, venue, artist, brand]
          user_id:
            type: string
          rating:
            type: number
            minimum: 1
            maximum: 5
          verified_purchase:
            type: boolean
          aggregated_stats:
            type: object
            properties:
              average_rating:
                type: number
              total_reviews:
                type: integer
              rating_distribution:
                type: object
          timestamp:
            type: string
            format: date-time

    EntityIndexedEvent:
      name: EntityIndexedEvent
      title: Entity Indexed Confirmation
      summary: Confirmation that an entity was successfully indexed
      contentType: application/cloudevents+json
      payload:
        type: object
        properties:
          entity_id:
            type: string
          entity_type:
            type: string
          index_name:
            type: string
          tenantId:
            type: string
            format: uuid
          timestamp:
            type: string
            format: date-time

  schemas:
    CloudEvent:
      type: object
      description: CloudEvents 1.0 envelope
      required:
        - specversion
        - type
        - source
        - id
      properties:
        specversion:
          type: string
          const: '1.0'
        type:
          type: string
          description: Event type URI
        source:
          type: string
          description: Event source (always /search-svc)
          const: /search-svc
        id:
          type: string
          format: uuid
          description: Unique event ID
        time:
          type: string
          format: date-time
          description: Event timestamp
        datacontenttype:
          type: string
          const: application/json
        subject:
          type: string
          description: Event subject path
        data:
          type: object
          description: Event payload

    SearchQueryPayload:
      type: object
      properties:
        query_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        query:
          type: string
        corrected_query:
          type: string
        entity_type:
          type: string
        filters:
          type: object
        search_method:
          type: string
          enum: [bm25, hybrid, vector]
        results_count:
          type: integer
        query_time_ms:
          type: integer
        used_cache:
          type: boolean
        used_semantic:
          type: boolean
        used_ai_expansion:
          type: boolean
        used_personalization:
          type: boolean
        ai_credits_consumed:
          type: integer
        timestamp:
          type: string
          format: date-time

    ZeroResultsPayload:
      type: object
      properties:
        query_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        query:
          type: string
        corrected_query:
          type: string
        entity_type:
          type: string
        filters:
          type: object
        search_method:
          type: string
          enum: [bm25, hybrid, vector]
        query_time_ms:
          type: integer
        timestamp:
          type: string
          format: date-time

    SearchClickPayload:
      type: object
      properties:
        click_id:
          type: string
        search_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        query:
          type: string
        result_id:
          type: string
        entity_type:
          type: string
        position:
          type: integer
          description: Position of clicked result in results list
        score:
          type: number
          description: Relevance score of clicked result
        timestamp:
          type: string
          format: date-time

    AutocompletePayload:
      type: object
      properties:
        interaction_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        query:
          type: string
        suggestions_shown:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              type:
                type: string
              score:
                type: number
              position:
                type: integer
        selected_suggestion:
          type: object
          nullable: true
          properties:
            text:
              type: string
            position:
              type: integer
        personalized:
          type: boolean
        response_time_ms:
          type: integer
        timestamp:
          type: string
          format: date-time

    SearchIndexedPayload:
      type: object
      properties:
        index_id:
          type: string
        tenantId:
          type: string
          format: uuid
        entity_id:
          type: string
        entity_type:
          type: string
        index_name:
          type: string
        operation:
          type: string
          enum: [create, update, delete]
        document_size_bytes:
          type: integer
        fields_indexed:
          type: array
          items:
            type: string
        vector_embedding_dimension:
          type: integer
          nullable: true
        timestamp:
          type: string
          format: date-time

    SavedSearchCreatedPayload:
      type: object
      properties:
        saved_search_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        name:
          type: string
        query:
          type: string
        alerts_enabled:
          type: boolean
        timestamp:
          type: string
          format: date-time

    AlertTriggeredPayload:
      type: object
      properties:
        alert_id:
          type: string
        tenantId:
          type: string
          format: uuid
        user_id:
          type: string
        saved_search_id:
          type: string
        saved_search_name:
          type: string
        query:
          type: string
        new_results_count:
          type: integer
        new_results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              entity_type:
                type: string
              title:
                type: string
              score:
                type: number
        alert_frequency:
          type: string
          enum: [immediate, daily, weekly]
        last_checked_at:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time

  messageTraits:
    CloudEventHeaders:
      headers:
        type: object
        required:
          - event-type
          - tenant-id
        properties:
          event-type:
            type: string
            description: CloudEvents type
          tenant-id:
            type: string
            format: uuid
            description: Tenant ID for multi-tenant isolation
          user-id:
            type: string
            description: User ID (when applicable)
