openapi: 3.1.0
info:
  title: Daremeet Lieux Go — web to app deep links
  description: |
    Build Universal Links and custom-scheme URLs that open the Daremeet mobile app
    on a Lieux city (map focus) or prefill a create-challenge flow at a POI.

    Human fallback page (HTML, noindex): GET /go/lieu?key=…
    City metadata for the app after a deep link: GET /api/lieux-place?key=…&items=0

    For AI agents: prefer GET /api/lieux-go to obtain all URLs in one JSON response.
  version: 1.0.0
  contact:
    email: contact@daremeet.com
    url: https://www.daremeet.com/contact
servers:
  - url: https://www.daremeet.com
    description: Production
paths:
  /api/lieux-go:
    get:
      operationId: buildLieuxGoLinks
      summary: Build Lieux → app deep link URLs
      description: |
        Validates a Lieux city key and returns web fallback, iOS scheme, Android intent,
        and localized Lieux city page URL. No authentication required.
      tags: [lieux-go]
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
            pattern: '^[a-z0-9-]+/[a-z0-9-]+/[a-z0-9-]+$'
          example: france/nouvelle-aquitaine/bordeaux
          description: Canonical Lieux key country/region/city (slugs)
        - name: action
          in: query
          required: false
          schema:
            type: string
            enum: [map, create]
            default: map
          description: map = focus map on city; create = open create-challenge (requires place for POI)
        - name: lat
          in: query
          required: false
          schema:
            type: number
          description: Latitude (defaults to city center from catalog)
        - name: lng
          in: query
          required: false
          schema:
            type: number
          description: Longitude (defaults to city center from catalog)
        - name: place
          in: query
          required: false
          schema:
            type: string
          description: POI name when action=create
        - name: city
          in: query
          required: false
          schema:
            type: string
          description: Display name override
        - name: locale
          in: query
          required: false
          schema:
            type: string
            default: fr
          description: BCP-47 locale for lieux_city_page path
      responses:
        '200':
          description: URL bundle and flow hint
          content:
            application/json:
              schema:
                type: object
                required: [enabled, key, city_name, action, geo, urls, flow]
                properties:
                  enabled:
                    type: boolean
                    description: false when NEXT_PUBLIC_LIEUX_GO_ENABLED=0 on the website
                  key:
                    type: string
                  city_name:
                    type: string
                  action:
                    type: string
                    enum: [map, create]
                  geo:
                    type: object
                    properties:
                      lat: { type: number }
                      lng: { type: number }
                  urls:
                    type: object
                    properties:
                      web_fallback:
                        type: string
                        format: uri
                        description: https://www.daremeet.com/go/lieu?… (noindex HTML fallback)
                      app_scheme:
                        type: string
                        description: daremeet://go/lieu?… (iOS / same-domain Safari)
                      android_intent:
                        type: string
                        description: intent://… Chrome on Android
                      lieux_city_page:
                        type: string
                        format: uri
                        description: Localized SEO Lieux city page
                  flow:
                    type: string
        '400':
          description: Missing or invalid query parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: invalid_params
        '404':
          description: Unknown Lieux key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: city_not_found
  /go/lieu:
    get:
      operationId: lieuxGoFallbackPage
      summary: Web fallback page (opens app or store badges)
      description: |
        Noindex HTML page shown when the app is not installed or on desktop.
        Same query parameters as /api/lieux-go. Universal Link path on iOS/Android
        when opened from outside the browser (Associated Domains / App Links).
      tags: [lieux-go]
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
        - name: action
          in: query
          required: false
          schema:
            type: string
            enum: [map, create]
        - name: lat
          in: query
          required: false
          schema:
            type: number
        - name: lng
          in: query
          required: false
          schema:
            type: number
        - name: place
          in: query
          required: false
          schema:
            type: string
        - name: city
          in: query
          required: false
          schema:
            type: string
        - name: locale
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: HTML fallback (robots noindex)
          content:
            text/html:
              schema:
                type: string
