openapi: 3.0.3
info:
  title: Joie de Vivre Public API
  description: |
    Public endpoints for accessing Joie de Vivre content.
    Joie de Vivre is a collaborative gift platform for French-speaking Africa.
    
    **Note**: These are public preview pages, not REST API endpoints.
    They return HTML with Open Graph meta tags and Schema.org structured data.
  version: 1.0.0
  contact:
    email: contact@joiedevivre.app
    url: https://joiedevivre-africa.com
  license:
    name: Proprietary
    url: https://joiedevivre-africa.com/terms-of-service

servers:
  - url: https://joiedevivre-africa.com
    description: Production server

tags:
  - name: Products
    description: Product preview pages
  - name: Businesses
    description: Business/vendor preview pages
  - name: Funds
    description: Collective fund preview pages
  - name: Static Pages
    description: Static content pages

paths:
  /:
    get:
      tags:
        - Static Pages
      summary: Homepage
      description: Main landing page with platform overview and features
      responses:
        '200':
          description: HTML page with WebSite schema

  /shop:
    get:
      tags:
        - Static Pages
      summary: Marketplace
      description: Browse all products from local African artisan shops
      responses:
        '200':
          description: HTML page with product listings

  /faq:
    get:
      tags:
        - Static Pages
      summary: FAQ Page
      description: Frequently asked questions about the platform
      responses:
        '200':
          description: HTML page with FAQPage schema

  /about:
    get:
      tags:
        - Static Pages
      summary: About Page
      description: Information about Joie de Vivre mission and story
      responses:
        '200':
          description: HTML page with Organization schema

  /p/{productId}:
    get:
      tags:
        - Products
      summary: Product Preview
      description: |
        Public product preview page with rich metadata.
        Includes Open Graph tags for social sharing and Schema.org Product markup.
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique product identifier (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: HTML page with Product schema
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Product not found

  /b/{businessId}:
    get:
      tags:
        - Businesses
      summary: Business Preview
      description: |
        Public business/vendor preview page.
        Includes LocalBusiness schema with opening hours, location, and reviews.
      parameters:
        - name: businessId
          in: path
          required: true
          description: Unique business identifier (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: HTML page with LocalBusiness schema
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Business not found

  /f/{fundId}:
    get:
      tags:
        - Funds
      summary: Public Fund Preview
      description: |
        Public collective fund page (only for public funds).
        Shows fund progress, occasion, and contribution count.
      parameters:
        - name: fundId
          in: path
          required: true
          description: Unique fund identifier (UUID)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: HTML page with Event schema
          content:
            text/html:
              schema:
                type: string
        '404':
          description: Fund not found or not public

  /llms.txt:
    get:
      tags:
        - Static Pages
      summary: LLM Context File
      description: Structured information for Large Language Models (ChatGPT, Claude, Perplexity)
      responses:
        '200':
          description: Plain text file with platform information
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      tags:
        - Static Pages
      summary: Extended LLM Context File
      description: Comprehensive documentation for LLMs with full context
      responses:
        '200':
          description: Plain text file with detailed platform information
          content:
            text/plain:
              schema:
                type: string

  /api/ai-catalog:
    get:
      tags:
        - AI Integration
      summary: AI Product & Business Catalog (JSON-LD)
      description: |
        HTML page with embedded JSON-LD catalog of popular products and businesses.
        Optimized for AI agents with Schema.org structured data (ItemList, Product, LocalBusiness).
        Products sorted by popularity score. Data fetched from edge function cached for 1 hour.
        
        The JSON-LD is injected in the document head for easy parsing by AI crawlers.
        Raw JSON is also displayed in the page body for human readability.
      responses:
        '200':
          description: JSON catalog with products, businesses, and categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICatalog'

  /api/products:
    get:
      tags:
        - AI Integration
      summary: Filtered Products API for AI Agents
      description: |
        JSON endpoint returning products with filtering, sorting, and pagination.
        Optimized for AI agents with Schema.org ItemList markup.
        Cache: 5 minutes.
      parameters:
        - name: category
          in: query
          schema:
            type: string
          description: Filter by category name (partial match)
        - name: min_price
          in: query
          schema:
            type: number
          description: Minimum price in XOF
        - name: max_price
          in: query
          schema:
            type: number
          description: Maximum price in XOF
        - name: sort
          in: query
          schema:
            type: string
            enum: [popularity, price_asc, price_desc, newest]
            default: popularity
          description: Sort order
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Number of results (max 100)
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination offset
        - name: business_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by business ID
      responses:
        '200':
          description: JSON with filtered products in Schema.org ItemList format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        price:
          type: number
        currency:
          type: string
          default: XOF
        image_url:
          type: string
          format: uri
        business_name:
          type: string

    Business:
      type: object
      properties:
        id:
          type: string
          format: uuid
        business_name:
          type: string
        business_type:
          type: string
        description:
          type: string
        address:
          type: string
        phone:
          type: string
        logo_url:
          type: string
          format: uri

    Fund:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        target_amount:
          type: number
        current_amount:
          type: number
        currency:
          type: string
          default: XOF
        occasion:
          type: string
        is_public:
          type: boolean

    AICatalog:
      type: object
      description: JSON catalog optimized for AI agents with Schema.org markup
      properties:
        '@context':
          type: string
          example: 'https://schema.org'
        '@type':
          type: string
          example: 'ItemList'
        name:
          type: string
          example: 'Joie de Vivre - AI Catalog'
        numberOfItems:
          type: integer
        generatedAt:
          type: string
          format: date-time
        platform:
          type: object
          properties:
            name:
              type: string
            url:
              type: string
            markets:
              type: array
              items:
                type: string
            currency:
              type: string
            language:
              type: string
        products:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalogItem'
        businesses:
          type: array
          items:
            $ref: '#/components/schemas/BusinessCatalogItem'
        categories:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              productCount:
                type: integer
        metadata:
          type: object
          properties:
            totalProducts:
              type: integer
            totalBusinesses:
              type: integer
            cacheMaxAge:
              type: integer

    ProductCatalogItem:
      type: object
      properties:
        '@type':
          type: string
          example: 'Product'
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        price:
          type: number
        currency:
          type: string
        image:
          type: string
          format: uri
        category:
          type: string
        seller:
          type: object
          properties:
            name:
              type: string
            id:
              type: string
        popularity:
          type: object
          properties:
            score:
              type: number
            views:
              type: integer
            orders:
              type: integer
            favorites:
              type: integer
            rank:
              type: integer
        availability:
          type: string
        updatedAt:
          type: string

    BusinessCatalogItem:
      type: object
      properties:
        '@type':
          type: string
          example: 'LocalBusiness'
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
          format: uri
        description:
          type: string
        businessType:
          type: string
        logo:
          type: string
          format: uri
        location:
          type: string
        productCount:
          type: integer
        isVerified:
          type: boolean
        updatedAt:
          type: string

    ProductsResponse:
      type: object
      description: Filtered products response for AI agents
      properties:
        '@context':
          type: string
          example: 'https://schema.org'
        '@type':
          type: string
          example: 'ItemList'
        name:
          type: string
        numberOfItems:
          type: integer
        generatedAt:
          type: string
          format: date-time
        filters:
          type: object
          properties:
            category:
              type: string
              nullable: true
            minPrice:
              type: number
              nullable: true
            maxPrice:
              type: number
              nullable: true
            sort:
              type: string
            businessId:
              type: string
              nullable: true
        pagination:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            hasMore:
              type: boolean
        itemListElement:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalogItem'
