openapi: 3.0.0
info:
  title: Offer Service
  version: 1.0.0
  description: Lightning offer and metadata management service
servers:
  - url: http://localhost:3002
security:
  - bearerAuth: [ ]
paths:
  /offers:
    post:
      summary: Create new offer
      description: Creates a new Lightning payment offer with specified payment limits and metadata reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferRecord'
      responses:
        '201':
          description: Offer created
          headers:
            Location:
              schema:
                type: string
                description: Location path (partition/id)
        '400':
          description: Bad request (e.g., metadata_id not found)
        '409':
          description: Offer already exists
          headers:
            Location:
              schema:
                type: string
                description: Location of existing offer
  /offers/{partition}:
    get:
      summary: Get all offers in partition
      description: Retrieves a list of all payment offers within the specified partition.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: start
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Offset for pagination (starting index)
        - name: count
          in: query
          required: false
          schema:
            type: integer
          description: Maximum number of offers to return (page size)
      responses:
        '200':
          description: List of offers
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OfferRecord'
  /offers/{partition}/{id}:
    get:
      summary: Get specific offer
      description: Retrieves detailed information about a specific payment offer including payment limits and metadata ID.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: sparse
          in: query
          required: false
          schema:
            default: true
            type: boolean
          description: If true, only includes metadataId. If false, includes full metadata representation.
      responses:
        '200':
          description: Offer details
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferRecord'
        '404':
          description: Offer not found
    put:
      summary: Create or update offer
      description: Creates a new offer or updates an existing one with the provided payment configuration.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferRecordSparse'
      responses:
        '201':
          description: Offer created
        '204':
          description: Offer updated
        '400':
          description: Bad request (e.g., metadata_id not found)
    delete:
      summary: Remove offer
      description: Permanently removes a payment offer from the system.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Offer removed
        '404':
          description: Offer not found
  /metadata:
    post:
      summary: Create new metadata
      description: Creates new metadata containing display information for payment offers such as text, images, and identifiers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferMetadata'
      responses:
        '201':
          description: Metadata created
          headers:
            Location:
              schema:
                type: string
                description: Location path (partition/id)
        '409':
          description: Metadata already exists
          headers:
            Location:
              schema:
                type: string
                description: Location of existing metadata
  /metadata/{partition}:
    get:
      summary: Get all metadata in partition
      description: Retrieves a list of all offer metadata entries within the specified partition.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: start
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Offset for pagination (starting index)
        - name: count
          in: query
          required: false
          schema:
            type: integer
          description: Maximum number of metadata entries to return (page size)
      responses:
        '200':
          description: List of metadata
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OfferMetadata'
  /metadata/{partition}/{id}:
    get:
      summary: Get specific metadata
      description: Retrieves specific metadata entry containing offer display information including text, images, and contact details.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Metadata details
          headers:
            Cache-Control:
              schema:
                type: string
            Expires:
              schema:
                type: string
            Pragma:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferMetadata'
        '404':
          description: Metadata not found
    put:
      summary: Create or update metadata
      description: Creates new metadata or updates existing metadata with the provided display information.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferMetadataSparse'
      responses:
        '201':
          description: Metadata created
        '204':
          description: Metadata updated
    delete:
      summary: Remove metadata
      description: Permanently removes metadata entry from the system.
      parameters:
        - name: partition
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Metadata removed
        '400':
          description: Bad request (e.g., metadata is referenced by offers)
        '404':
          description: Metadata not found
  /health:
    get:
      summary: Health check
      description: Returns HTTP 200 OK to indicate the offer service is running and accessible.
      security: [ ]
      responses:
        '200':
          description: Service healthy
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    OfferRecord:
      type: object
      description: Complete offer configuration with partition and ID
      required:
        - partition
        - id
        - maxSendable
        - minSendable
        - metadataId
        - timestamp
      properties:
        partition:
          type: string
          description: Partition name
        id:
          type: string
          format: uuid
          description: Unique offer identifier
        maxSendable:
          type: integer
          format: int64
          minimum: 0
          description: Maximum sendable amount in millisatoshis
        minSendable:
          type: integer
          format: int64
          minimum: 0
          description: Minimum sendable amount in millisatoshis
        metadataId:
          type: string
          format: uuid
          description: Reference to offer metadata
        metadata:
          allOf:
            - $ref: '#/components/schemas/OfferMetadataSparse'
          nullable: true
          description: Optional full metadata object (included when sparse=false in GET request)
        timestamp:
          type: string
          format: date-time
          description: Creation timestamp
        expires:
          type: string
          format: date-time
          nullable: true
          description: Optional expiration timestamp

    OfferRecordSparse:
      type: object
      description: Offer configuration without partition/id (used in PUT requests where partition/id are in path)
      required:
        - maxSendable
        - minSendable
        - metadataId
        - timestamp
      properties:
        maxSendable:
          type: integer
          format: int64
          minimum: 0
          description: Maximum sendable amount in millisatoshis
        minSendable:
          type: integer
          format: int64
          minimum: 0
          description: Minimum sendable amount in millisatoshis
        metadataId:
          type: string
          format: uuid
          description: Reference to offer metadata
        metadata:
          allOf:
            - $ref: '#/components/schemas/OfferMetadataSparse'
          nullable: true
          description: Optional full metadata object (included when sparse=false)
        timestamp:
          type: string
          format: date-time
          description: Creation timestamp
        expires:
          type: string
          format: date-time
          nullable: true
          description: Optional expiration timestamp

    OfferMetadata:
      type: object
      description: Complete metadata configuration with partition and ID
      required:
        - id
        - partition
        - text
      properties:
        id:
          type: string
          format: uuid
          description: Unique metadata identifier
        partition:
          type: string
          description: Partition name
        text:
          type: string
          description: Short text description
        longText:
          type: string
          nullable: true
          description: Optional long text description
        image:
          $ref: '#/components/schemas/OfferMetadataImage'
        identifier:
          $ref: '#/components/schemas/OfferMetadataIdentifier'

    OfferMetadataSparse:
      type: object
      description: Metadata configuration without id/partition (used in PUT requests where id/partition are in path)
      required:
        - text
      properties:
        text:
          type: string
          description: Short text description
        longText:
          type: string
          nullable: true
          description: Optional long text description
        image:
          $ref: '#/components/schemas/OfferMetadataImage'
        identifier:
          $ref: '#/components/schemas/OfferMetadataIdentifier'
    
    OfferMetadataImage:
      oneOf:
        - $ref: '#/components/schemas/PngImage'
        - $ref: '#/components/schemas/JpegImage'
      discriminator:
        propertyName: type
        mapping:
          png: '#/components/schemas/PngImage'
          jpeg: '#/components/schemas/JpegImage'

    PngImage:
      type: object
      description: PNG image with base64 encoded data
      required:
        - png
      properties:
        png:
          type: string
          format: byte
          description: Base64 encoded PNG image data

    JpegImage:
      type: object
      description: JPEG image with base64 encoded data
      required:
        - jpeg
      properties:
        jpeg:
          type: string
          format: byte
          description: Base64 encoded JPEG image data

    OfferMetadataIdentifier:
      oneOf:
        - $ref: '#/components/schemas/TextIdentifier'
        - $ref: '#/components/schemas/EmailIdentifier'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextIdentifier'
          email: '#/components/schemas/EmailIdentifier'

    TextIdentifier:
      type: object
      description: Text identifier (email address format)
      required:
        - text
      properties:
        text:
          type: string
          format: email
          description: Email address used as text identifier

    EmailIdentifier:
      type: object
      description: Email identifier
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Email address