openapi: 3.1.0
info:
    title: Wallora Searcher API
    version: 0.1.0
    description: Public API contract for Wallora Searcher.
servers:
    - url: /api/v1
      description: Local Next.js API route base
paths:
    /auth/login:
        post:
            summary: Login app user with email and password
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - email
                                - password
                            properties:
                                email:
                                    type: string
                                    format: email
                                password:
                                    type: string
            responses:
                "200":
                    description: App user token and profile.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AuthResponse"
                "401":
                    description: Invalid email or password, or the app user is disabled.
    /auth/register:
        post:
            summary: Register app user with email and password
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - email
                                - password
                            properties:
                                email:
                                    type: string
                                    format: email
                                password:
                                    type: string
                                    minLength: 8
                                displayName:
                                    type:
                                        - string
                                        - "null"
            responses:
                "200":
                    description: App user token and profile.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AuthResponse"
                "400":
                    description: Invalid request or duplicate email.
    /gallery/collections:
        get:
            summary: List published photo collections
            description: Returns published photo collections with cover metadata.
            parameters:
                - name: page
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: pageSize
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 50
                      default: 20
            responses:
                "200":
                    description: Paginated published collections.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/PhotoCollection"
                                    pagination:
                                        $ref: "#/components/schemas/Pagination"
    /gallery/collections/{slug}:
        get:
            summary: Get a published photo collection
            description: Returns collection metadata and paginated picked photos in collection order.
            parameters:
                - name: slug
                  in: path
                  required: true
                  schema:
                      type: string
                - name: page
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: pageSize
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 24
            responses:
                "200":
                    description: Published collection with paginated photos.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        type: object
                                        properties:
                                            collection:
                                                $ref: "#/components/schemas/PhotoCollection"
                                            photos:
                                                type: array
                                                items:
                                                    $ref: "#/components/schemas/PickedGalleryPhoto"
                                    pagination:
                                        $ref: "#/components/schemas/Pagination"
                "404":
                    description: Collection was not found or is not published.
    /gallery/photos:
        get:
            summary: List picked gallery photos
            description: Returns public picked photos for waterfall-style infinite scroll. If a Bearer JWT is provided, each photo includes current user's favorite state.
            security:
                - {}
                - bearerAuth: []
            parameters:
                - name: page
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: pageSize
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 24
                - name: colorFamily
                  in: query
                  schema:
                      type: string
                      enum:
                          - all
                          - black
                          - blue
                          - green
                          - light
                          - orange
                          - purple
                          - red
                          - yellow
            responses:
                "200":
                    description: Paginated picked photos.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/PickedGalleryPhoto"
                                    pagination:
                                        $ref: "#/components/schemas/Pagination"
    /gallery/photos/{id}:
        get:
            summary: Get picked photo detail
            description: Returns one picked photo by id. If a Bearer JWT is provided, includes current user's favorite state.
            security:
                - {}
                - bearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Picked photo detail.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        $ref: "#/components/schemas/PickedGalleryPhoto"
                "404":
                    description: Photo was not found or is not picked.
        post:
            summary: Favorite picked photo
            description: Adds the photo to the current user's favorites.
            security:
                - bearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Favorited photo.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        $ref: "#/components/schemas/FavoritePhoto"
                "401":
                    description: Missing or invalid app user JWT.
        delete:
            summary: Unfavorite picked photo
            description: Removes the photo from the current user's favorites.
            security:
                - bearerAuth: []
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Favorite removed.
                "401":
                    description: Missing or invalid app user JWT.
    /users/me:
        get:
            summary: Get current app user
            security:
                - bearerAuth: []
            responses:
                "200":
                    description: Current app user profile.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        type: object
                                        properties:
                                            user:
                                                $ref: "#/components/schemas/AppUser"
                "401":
                    description: Missing or invalid app user JWT.
    /users/me/favorites:
        get:
            summary: List current user's favorite photos
            security:
                - bearerAuth: []
            parameters:
                - name: page
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: pageSize
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 24
            responses:
                "200":
                    description: Paginated favorite picked photos.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/FavoritePhoto"
                                    pagination:
                                        $ref: "#/components/schemas/Pagination"
                "401":
                    description: Missing or invalid app user JWT.
        post:
            summary: Add a picked photo to current user's favorites
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - photoId
                            properties:
                                photoId:
                                    type: string
                                    format: uuid
            responses:
                "200":
                    description: Favorited photo.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        $ref: "#/components/schemas/FavoritePhoto"
                "401":
                    description: Missing or invalid app user JWT.
    /users/me/favorites/{photoId}:
        delete:
            summary: Remove a photo from current user's favorites
            security:
                - bearerAuth: []
            parameters:
                - name: photoId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                "200":
                    description: Favorite removed.
                "401":
                    description: Missing or invalid app user JWT.
    /users/me/settings:
        get:
            summary: Get current user's preferences
            security:
                - bearerAuth: []
            responses:
                "200":
                    description: User preferences and download preferences.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        $ref: "#/components/schemas/UserSettings"
                "401":
                    description: Missing or invalid app user JWT.
        patch:
            summary: Update current user's preferences
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                preferences:
                                    type: object
                                    additionalProperties: true
                                downloadPreferences:
                                    type: object
                                    additionalProperties: true
            responses:
                "200":
                    description: Updated user settings.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    ok:
                                        type: boolean
                                    data:
                                        $ref: "#/components/schemas/UserSettings"
                "401":
                    description: Missing or invalid app user JWT.
components:
    securitySchemes:
        bearerAuth:
            type: http
            scheme: bearer
            bearerFormat: JWT
    schemas:
        AppUser:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                email:
                    type:
                        - string
                        - "null"
                    format: email
                displayName:
                    type:
                        - string
                        - "null"
                avatarUrl:
                    type:
                        - string
                        - "null"
                authProvider:
                    type: string
        AuthResponse:
            type: object
            properties:
                ok:
                    type: boolean
                data:
                    type: object
                    properties:
                        token:
                            type: string
                        user:
                            $ref: "#/components/schemas/AppUser"
        FavoritePhoto:
            allOf:
                - $ref: "#/components/schemas/PickedGalleryPhoto"
                - type: object
                  properties:
                      favoritedAt:
                          type:
                              - string
                              - "null"
                          format: date-time
        PhotoCollection:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                title:
                    type: string
                slug:
                    type: string
                description:
                    type:
                        - string
                        - "null"
                coverPhoto:
                    oneOf:
                        - $ref: "#/components/schemas/PickedGalleryPhoto"
                        - type: "null"
                coverUrl:
                    type:
                        - string
                        - "null"
                photoCount:
                    type: integer
                publishedAt:
                    type:
                        - string
                        - "null"
                    format: date-time
        PickedGalleryPhoto:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                unsplashId:
                    type: string
                slug:
                    type:
                        - string
                        - "null"
                description:
                    type:
                        - string
                        - "null"
                altDescription:
                    type:
                        - string
                        - "null"
                width:
                    type:
                        - integer
                        - "null"
                height:
                    type:
                        - integer
                        - "null"
                color:
                    type:
                        - string
                        - "null"
                colorFamily:
                    type:
                        - string
                        - "null"
                url:
                    type:
                        - string
                        - "null"
                sourceUrl:
                    type:
                        - string
                        - "null"
                user:
                    type: object
                    additionalProperties: true
                likes:
                    type:
                        - integer
                        - "null"
                pickedAt:
                    type:
                        - string
                        - "null"
                    format: date-time
                isFavorited:
                    type: boolean
        UserSettings:
            type: object
            properties:
                preferences:
                    type: object
                    additionalProperties: true
                downloadPreferences:
                    type: object
                    additionalProperties: true
                updatedAt:
                    type: string
                    format: date-time
        Pagination:
            type: object
            properties:
                page:
                    type: integer
                pageSize:
                    type: integer
                total:
                    type: integer
                hasMore:
                    type: boolean
                nextPage:
                    type:
                        - integer
                        - "null"