openapi: 3.0.3
info:
  title: Calientalo Media Public API
  description: |
    Public API for Calientalo Media Distribution LLC (calientalomedia.com).
    Miami-based independent music distribution company specializing in Latin urban music and Reparto Cubano.
    Distributes to 150+ streaming platforms. Founded by Lester Hechavarria and Hansel Tamayo.

    These endpoints require no authentication and are safe for AI agents to call directly.
  version: "1.0.0"
  contact:
    email: info@calientalomedia.com
    url: https://calientalomedia.com/contact
  license:
    name: Public
    url: https://calientalomedia.com/terms

servers:
  - url: https://tdyyojkdrqymmpxfwtlv.supabase.co/functions/v1
    description: Calientalo Media Edge Functions (Supabase)
  - url: https://calientalomedia.com
    description: Calientalo Media Main Site

paths:
  /get-announcements:
    get:
      operationId: getAnnouncements
      summary: Get active in-app announcements
      description: |
        Returns all currently active announcements published by Calientalo Media.
        These are used in the web app and mobile app to surface news, promotions,
        platform updates, and alerts to artists. No authentication required.
        Filter by target_audience to get announcements relevant to a specific user type.
      parameters:
        - name: audience
          in: query
          required: false
          schema:
            type: string
            enum: [all, artists, admins]
            default: all
          description: Filter announcements by target audience. Defaults to returning all public announcements.
      responses:
        "200":
          description: List of active announcements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Announcement"
              example:
                - id: "550e8400-e29b-41d4-a716-446655440000"
                  title: "New Platform: Now distributing to Boomplay"
                  body: "We just added Boomplay to our distribution network — 100M+ African users."
                  content: "<p>We just added Boomplay...</p>"
                  image_url: "https://assets.calientalomedia.com/uploads/announcements/boomplay.jpg"
                  video_url: null
                  action_type: "url"
                  action_url: "https://calientalomedia.com/features"
                  cta_label: "Learn More"
                  category: "update"
                  priority: 1
                  is_dismissible: true
                  target_audience: "all"
                  starts_at: "2026-01-01T00:00:00Z"
                  expires_at: null
                  is_active: true
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sitemap:
    get:
      operationId: getSitemap
      summary: Get dynamic sitemap
      description: |
        Returns the XML sitemap for calientalomedia.com. Contains URLs for all
        public pages including artist profiles, releases, blog posts, knowledge base
        articles, playlists, and tool pages. Useful for AI agents to discover
        all content available on the site.
      responses:
        "200":
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string
                description: Standard XML sitemap (sitemaps.org protocol)
        "500":
          description: Server error

components:
  schemas:
    Announcement:
      type: object
      required:
        - id
        - title
        - body
        - category
        - priority
        - is_dismissible
        - target_audience
        - is_active
        - starts_at
        - action_type
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the announcement
          example: "550e8400-e29b-41d4-a716-446655440000"
        title:
          type: string
          description: Short headline for the announcement
          example: "New Royalty Advance Program Available"
        body:
          type: string
          description: Brief summary text (1–3 sentences)
          example: "Apply now to get an advance on your future streaming royalties."
        content:
          type: string
          nullable: true
          description: Full rich-text HTML content of the announcement (may be null if body is sufficient)
        image_url:
          type: string
          nullable: true
          description: URL of the featured image for this announcement
          example: "https://assets.calientalomedia.com/uploads/announcements/promo.jpg"
        video_url:
          type: string
          nullable: true
          description: Optional video URL (YouTube, Vimeo, or direct MP4)
        action_type:
          type: string
          enum: [url, internal, none]
          description: |
            Type of call-to-action:
            - "url": opens action_url in browser
            - "internal": navigates within the app
            - "none": no CTA button
          example: "url"
        action_url:
          type: string
          nullable: true
          description: Destination URL when action_type is "url"
          example: "https://calientalomedia.com/royalties-advancement"
        cta_label:
          type: string
          nullable: true
          description: Text label for the call-to-action button
          example: "Apply Now"
        category:
          type: string
          enum: [update, promotion, news, alert]
          description: |
            Category of the announcement:
            - "update": platform or product update
            - "promotion": promotional offer or campaign
            - "news": industry news or company news
            - "alert": important alert requiring attention
          example: "promotion"
        priority:
          type: integer
          description: Display priority order. Lower numbers appear first (1 = highest priority).
          example: 1
        is_dismissible:
          type: boolean
          description: Whether users can dismiss/hide this announcement after reading
          example: true
        target_audience:
          type: string
          enum: [all, artists, admins]
          description: Which users this announcement is shown to
          example: "all"
        starts_at:
          type: string
          format: date-time
          description: ISO 8601 datetime when this announcement becomes active
          example: "2026-01-15T00:00:00Z"
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 datetime when this announcement expires (null = no expiry)
          example: "2026-02-15T00:00:00Z"
        is_active:
          type: boolean
          description: Whether this announcement is currently live and visible
          example: true
        views_count:
          type: integer
          description: Total number of times this announcement has been viewed
          example: 1240
        clicks_count:
          type: integer
          description: Total number of CTA button clicks
          example: 87

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
          example: "Internal server error"
        code:
          type: string
          description: Machine-readable error code
          example: "INTERNAL_ERROR"
