api.yaml

openapi: 3.0.3
info:
  title: GatherYourDeals Data API
  description: |
    API for managing purchase data and user authentication.

    ## Authentication

    This API uses JWT Bearer tokens.

    1. Register a user via `POST /users`
    2. Log in via `POST /auth/login` — returns an access token and a refresh token
    3. Include the access token in the `Authorization: Bearer <token>` header for protected requests
    4. When the access token expires, call `POST /auth/refresh` with the refresh token to get a new pair
    5. Log out via `POST /auth/logout` — revokes the refresh token

  version: 0.4.0
  license:
    name: MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Local development server

tags:
  - name: Users
    description: User registration
  - name: Sessions
    description: Login, logout, token refresh, and current user info
  - name: Meta
    description: Field metadata — list all registered fields
  - name: Receipts
    description: Purchase records — create, list, get, and delete
  - name: Admin - Users
    description: User management (admin only)
  - name: Admin - Meta
    description: Field metadata management (admin only)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT access token

  parameters:
    offsetParam:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of records to skip
      example: 0
    limitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Maximum number of records to return. Values above 100 are silently capped to 100.
      example: 20

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      example:
        error: "invalid username or password"

    UserPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/User"
        total:
          type: integer
          description: Total number of matching records (ignoring pagination)
          example: 42
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 20
        total_pages:
          type: integer
          description: "Ceiling division: ceil(total / limit). 0 when total is 0."
          example: 3

    ReceiptPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Receipt"
        total:
          type: integer
          example: 42
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 3

    MetaFieldPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/MetaField"
        total:
          type: integer
          example: 8
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 1

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        username:
          type: string
          example: "alice"
        role:
          type: string
          enum: [admin, user]
          example: "user"

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Short-lived JWT for authenticating requests
          example: "eyJhbGciOiJIUzI1NiIs..."
        refresh_token:
          type: string
          description: Long-lived token used to obtain a new access token
          example: "eyJhbGciOiJIUzI1NiIs..."
        token_type:
          type: string
          description: |
            Always "Bearer". Defined by RFC 6750 — the client must include this
            token in the Authorization header as: Authorization: Bearer <access_token>
          example: "Bearer"

    MetaField:
      type: object
      properties:
        fieldName:
          type: string
          example: "brand"
        description:
          type: string
          example: "brand of the product"
        type:
          type: string
          example: "string"
        native:
          type: boolean
          description: Whether this is a built-in field that cannot be removed
          example: false

    Receipt:
      type: object
      description: |
        A flat JSON object. Native fields (productName, price, etc.) are stored as
        dedicated columns. Any additional keys are user-defined fields stored as JSON
        internally but returned at the same level. Every non-native key must be
        registered in the meta table.
      properties:
        id:
          type: string
          format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        productName:
          type: string
          example: "Milk 2%"
        purchaseDate:
          type: string
          description: Purchase date in Y.M.D format
          example: "2025.04.05"
        price:
          type: string
          example: "5.49CAD"
        amount:
          type: string
          description: Amount in the format of number or number(unit)
          example: "2lb"
        storeName:
          type: string
          example: "Costco"
        latitude:
          type: number
          format: float
          nullable: true
          example: 49.2827
        longitude:
          type: number
          format: float
          nullable: true
          example: -123.1207
        uploadTime:
          type: integer
          description: Upload time as Unix epoch seconds (set by server)
          example: 1770620311
        userId:
          type: string
          format: uuid
          description: ID of the user who created this record (set by server)
          example: "550e8400-e29b-41d4-a716-446655440000"
      additionalProperties:
        description: User-defined fields registered in the meta table
      example:
        id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        productName: "Milk 2%"
        purchaseDate: "2025.04.05"
        price: "5.49CAD"
        amount: "2lb"
        storeName: "Costco"
        latitude: 49.2827
        longitude: -123.1207
        brand: "Kirkland"
        uploadTime: 1770620311
        userId: "550e8400-e29b-41d4-a716-446655440000"

paths:
  # ── Users ──────────────────────────────────────────────────────────────

  /users:
    post:
      summary: Register a new user
      description: |
        Creates a new user account. The account is active immediately (open registration).
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  example: "alice"
                password:
                  type: string
                  minLength: 8
                  example: "password123"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Invalid request (missing fields or password too short)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Username already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      summary: List all users
      description: Returns a paginated list of all registered user accounts. Admin only.
      tags: [Admin - Users]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/offsetParam"
        - $ref: "#/components/parameters/limitParam"
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [created_at, username, role]
            default: created_at
          description: Field to sort by
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort direction
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserPage"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Sessions ───────────────────────────────────────────────────────────

  /auth/login:
    post:
      summary: Login
      description: |
        Verifies the username and password and returns a JWT access token and a refresh token.
        The access token is valid for the duration set in `auth.access_token_exp` (default 1 hour).
        The refresh token is valid for `auth.refresh_token_exp` (default 7 days).
      tags: [Sessions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  example: "alice"
                password:
                  type: string
                  example: "password123"
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "400":
          description: Missing fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Invalid username or password
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/logout:
    post:
      summary: Logout
      description: |
        Revokes the refresh token provided in the request body.
        The access token will expire naturally. If no refresh token is provided, the endpoint
        still returns 200 — the access token will simply expire on its own.
      tags: [Sessions]
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  example: "eyJhbGciOiJIUzI1NiIs..."
      responses:
        "200":
          description: Logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "logged out"
        "401":
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/refresh:
    post:
      summary: Refresh access token
      description: |
        Exchanges a valid refresh token for a new access token and refresh token pair.
        The old refresh token is immediately invalidated (rotation).
      tags: [Sessions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
                  example: "eyJhbGciOiJIUzI1NiIs..."
      responses:
        "200":
          description: New token pair issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/me:
    get:
      summary: Get current user
      description: Returns the ID and role of the currently authenticated user, read from the access token claims.
      tags: [Sessions]
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user info
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: "550e8400-e29b-41d4-a716-446655440000"
                  role:
                    type: string
                    enum: [admin, user]
                    example: "user"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Meta (authenticated) ───────────────────────────────────────────────

  /meta:
    get:
      summary: List all fields
      description: |
        Returns a paginated list of all registered field definitions, both native (built-in)
        and user-defined. Any authenticated user can call this endpoint.
        Default sort is `name asc` (alphabetical).
      tags: [Meta]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/offsetParam"
        - $ref: "#/components/parameters/limitParam"
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [name]
            default: name
          description: Field to sort by
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: asc
          description: Sort direction (default asc for this endpoint)
      responses:
        "200":
          description: Paginated list of fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaFieldPage"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: Register a new field
      description: |
        Registers a new user-defined field. Once registered, receipts can include
        this field in their `extras` object. Any authenticated user can register fields.
      tags: [Meta]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fieldName, description, type]
              properties:
                fieldName:
                  type: string
                  example: "brand"
                description:
                  type: string
                  example: "brand of the product"
                type:
                  type: string
                  example: "string"
      responses:
        "201":
          description: Field registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaField"
        "400":
          description: Missing required fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Field already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Receipts (authenticated) ───────────────────────────────────────────

  /receipts:
    post:
      summary: Create a receipt
      description: |
        Creates a new purchase record for the authenticated user.
        The server sets `id`, `uploadTime`, and `userId` automatically.
        Any keys in `extras` must be registered in the meta table or the request is rejected.
      tags: [Receipts]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: |
          A flat JSON object. Include native fields and any registered
          user-defined fields at the same level — no `extras` wrapper needed.
        content:
          application/json:
            schema:
              type: object
              required: [productName, purchaseDate, price, amount, storeName]
              properties:
                productName:
                  type: string
                  example: "Milk 2%"
                purchaseDate:
                  type: string
                  example: "2025.04.05"
                price:
                  type: string
                  example: "5.49CAD"
                amount:
                  type: string
                  example: "1"
                storeName:
                  type: string
                  example: "Costco"
                latitude:
                  type: number
                  format: float
                  example: 49.2827
                longitude:
                  type: number
                  format: float
                  example: -123.1207
              additionalProperties:
                description: User-defined fields registered in the meta table
      responses:
        "201":
          description: Receipt created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        "400":
          description: Missing required fields or unregistered extra field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      summary: List own receipts
      description: |
        Returns a paginated list of receipts belonging to the authenticated user.
        Default sort is `created_at desc` (newest first).
        The `created_at` sort param maps to the `upload_time` column internally.
      tags: [Receipts]
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/offsetParam"
        - $ref: "#/components/parameters/limitParam"
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [created_at, purchase_date, price, store_name, product_name]
            default: created_at
          description: Field to sort by
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort direction
      responses:
        "200":
          description: Paginated list of receipts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReceiptPage"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /receipts/{id}:
    get:
      summary: Get a receipt by ID
      description: Returns a single receipt by its ID.
      tags: [Receipts]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Receipt found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Receipt"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Receipt not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: Delete a receipt
      description: Deletes a receipt by its ID.
      tags: [Receipts]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        "200":
          description: Receipt deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "receipt deleted"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Receipt not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Users (admin only) ─────────────────────────────────────────────────

  /users/{id}:
    delete:
      summary: Delete a user
      description: |
        Deletes a user account and immediately revokes all their active refresh tokens.
        Admin only.
      tags: [Admin - Users]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The user ID to delete
          example: "550e8400-e29b-41d4-a716-446655440000"
      responses:
        "200":
          description: User deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "user deleted"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Admin — Meta ───────────────────────────────────────────────────────

  /meta/{fieldName}:
    put:
      summary: Update a field description
      description: |
        Updates the description of an existing field (native or user-defined). Admin only.
      tags: [Admin - Meta]
      security:
        - bearerAuth: []
      parameters:
        - name: fieldName
          in: path
          required: true
          schema:
            type: string
          example: "brand"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description]
              properties:
                description:
                  type: string
                  example: "brand or manufacturer of the product"
      responses:
        "200":
          description: Description updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "description updated"
        "400":
          description: Missing description
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Field not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"