openapi: 3.0.3
info:
  title: Barcodes.dev API
  description: |
    Comprehensive barcode and QR code generation API with two distinct versions:

    ## API Versions

    ### API v1 - Public Access
    - **Base Path**: `/api/v1/`
    - **Authentication**: Optional (anonymous usage allowed)
    - **Rate Limiting**: Applied to all requests
    - **Features**: Basic barcode and QR code generation

    ### API v2 - Authenticated Access
    - **Base Path**: `/api/v2/`
    - **Authentication**: Required (API key)
    - **Rate Limiting**: Tier-based limits
    - **Features**: All v1 features plus batch generation, account management

    ## Getting Started

    1. **For v1 (Anonymous)**: Start making requests immediately
    2. **For v2 (Authenticated)**: Register at `/register` to get your API key

    ## Authentication

    v2 endpoints require an API key in the `X-API-Key` header:
    ```
    X-API-Key: bcd_your_api_key_here
    ```

  version: 2.0.0
  contact:
    name: API Support
    url: https://barcodes.dev/api-docs
    email: api@barcodes.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://barcodes.dev
    description: Production server
  - url: http://localhost:5001
    description: Local development server

tags:
  - name: v1-barcode
    description: API v1 - Linear barcode generation (public)
  - name: v1-qr
    description: API v1 - QR code generation (public)
  - name: v1-utility
    description: API v1 - Utility endpoints (public)
  - name: v2-barcode
    description: API v2 - Linear barcode generation (authenticated)
  - name: v2-qr
    description: API v2 - QR code generation (authenticated)
  - name: v2-batch
    description: API v2 - Batch generation (authenticated)
  - name: v2-postal
    description: API v2 - Postal code generation (authenticated)
  - name: v2-account
    description: API v2 - Account management (authenticated)
  - name: v2-utility
    description: API v2 - Utility endpoints (authenticated)
  - name: v2-degradation
    description: API v2 - Barcode degradation testing (authenticated)
  - name: authentication
    description: User registration and authentication

security:
  - ApiKeyAuth: []
  - {} # Allow no authentication for v1 endpoints

paths:
  # API v1 Endpoints (Public)
  /api/v1/barcode:
    post:
      tags:
        - v1-barcode
      summary: Generate Linear Barcode (v1)
      description: |
        Generate traditional 1D barcodes. No authentication required, but rate limited.

        **Rate Limits**: 100 requests/hour for anonymous users, tier-based for API key users.
      security:
        - {}
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinearBarcodeRequest'
            examples:
              basic:
                summary: Basic Code128
                value:
                  text: "EXAMPLE-123"
                  barcode_type: "code128"
                  image_format: "PNG"
      responses:
        '200':
          description: Barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/qrcode:
    post:
      tags:
        - v1-qr
      summary: Generate QR Code (v1)
      description: |
        Generate QR codes with customization options and optional logo overlay. No authentication required.

        **Logo Support**: Add your logo to QR codes by providing base64 encoded image data in the `logo` parameter.
      security:
        - {}
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QRCodeRequest'
            examples:
              basic:
                summary: Basic QR Code
                value:
                  text: "https://example.com"
                  error_correction: "M"
              with_logo:
                summary: QR Code with Logo
                value:
                  text: "https://example.com"
                  error_correction: "H"
                  logo: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                  box_size: 12
                  border: 6
      responses:
        '200':
          description: QR code generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QRCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v1/usage:
    get:
      tags:
        - v1-utility
      summary: Get Usage Statistics (v1)
      description: Get current usage statistics. API key optional for anonymous usage.
      security:
        - {}
        - ApiKeyAuth: []
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'

  /api/v1/version:
    get:
      tags:
        - v1-utility
      summary: Get API Version Info (v1)
      description: Get version and system information for API v1.
      security:
        - {}
      responses:
        '200':
          description: Version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'

  # API v2 Endpoints (Authenticated)
  /api/v2/barcode:
    post:
      tags:
        - v2-barcode
      summary: Generate Linear Barcode (v2)
      description: |
        Generate traditional 1D barcodes with enhanced features. Requires API key authentication.

        **Enhanced Features**:
        - User tier information in response
        - Better error handling
        - Priority processing
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinearBarcodeRequest'
            examples:
              authenticated:
                summary: Authenticated Barcode Generation
                value:
                  text: "AUTH-BARCODE-456"
                  barcode_type: "code128"
                  image_format: "PNG"
                  scale: 1.5
      responses:
        '200':
          description: Barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedBarcodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/qrcode:
    post:
      tags:
        - v2-qr
      summary: Generate QR Code (v2)
      description: |
        Generate QR codes with enhanced features, logo overlay support, and user tier information.

        **Enhanced Features**:
        - User tier information in response
        - Logo overlay with automatic error correction optimization
        - Priority processing
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QRCodeRequest'
            examples:
              enhanced:
                summary: Enhanced QR Code
                value:
                  text: "https://authenticated.example.com"
                  error_correction: "H"
                  box_size: 12
                  border: 6
                  scale: 2.0
              with_logo:
                summary: QR Code with Company Logo
                value:
                  text: "https://company.example.com"
                  error_correction: "H"
                  logo: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                  scale: 1.5
                  fill_color: "#0066cc"
                  back_color: "#ffffff"
                  box_size: 10
                  border: 4
      responses:
        '200':
          description: QR code generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedQRCodeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/batch:
    post:
      tags:
        - v2-batch
      summary: Batch Generate Codes (v2 Exclusive)
      description: |
        Generate multiple barcodes and QR codes in a single request. Maximum 10 items per batch.

        **v2 Exclusive Feature**: Only available with API key authentication.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            examples:
              mixed_batch:
                summary: Mixed Barcode and QR Code Batch
                value:
                  batch:
                    - type: "barcode"
                      text: "BATCH-001"
                      barcode_type: "code128"
                    - type: "qrcode"
                      text: "https://batch.example.com"
                      error_correction: "M"
                    - type: "barcode"
                      text: "BATCH-002"
                      barcode_type: "ean13"
      responses:
        '200':
          description: Batch processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/postal:
    post:
      tags:
        - v2-postal
      summary: Generate Postal Barcode (v2)
      description: |
        Generate postal service barcodes for various countries and services. Requires API key authentication.

        **Supported Postal Types**:
        - USPS: usps_imd, usps_postnet, usps_planet
        - Royal Mail: royal_mail, ukroyalmail
        - Australia Post: australia_post, auspost
        - Netherlands: netherlands_kix
        - Japan Post: japan_post, japanpost
        - Korea Post: korea_post
        - Deutsche Post: dpleit, dpident
        - Channel Code: channel
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostalRequest'
            examples:
              usps_imd:
                summary: USPS Intelligent Mail
                value:
                  text: "0123456709498765432101234567891"
                  postal_type: "usps_imd"
                  image_format: "PNG"
                  scale: 1.2
              royal_mail:
                summary: Royal Mail 4-State
                value:
                  text: "B31HQ1A"
                  postal_type: "royal_mail"
                  image_format: "PNG"
                  scale: 0.8
              australia_post:
                summary: Australia Post
                value:
                  text: "1139549554"
                  postal_type: "australia_post"
                  image_format: "PNG"
                  scale: 1.0
      responses:
        '200':
          description: Postal barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - v2-postal
      summary: Generate Postal Barcode via GET (v2)
      description: Generate postal barcodes using query parameters. Requires API key authentication.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: text
          in: query
          required: true
          schema:
            type: string
          description: Data to encode in postal barcode
          example: "0123456709498765432101234567891"
        - name: postal_type
          in: query
          required: true
          schema:
            type: string
            enum: [usps_imd, usps_postnet, usps_planet, royal_mail, ukroyalmail, australia_post, auspost, netherlands_kix, japan_post, japanpost, korea_post, dpleit, dpident, channel]
          description: Type of postal barcode
          example: "usps_imd"
        - name: image_format
          in: query
          schema:
            type: string
            enum: [PNG, JPEG, WEBP]
            default: PNG
          description: Output image format
        - name: output
          in: query
          schema:
            type: string
            enum: [base64, file]
            default: base64
          description: Response format
      responses:
        '200':
          description: Postal barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostalResponse'
            application/octet-stream:
              description: Binary image file (when output=file)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/account:
    get:
      tags:
        - v2-account
      summary: Get Account Information (v2 Exclusive)
      description: |
        Get detailed account information including tier, usage limits, and current usage.

        **v2 Exclusive Feature**: Only available with API key authentication.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/usage:
    get:
      tags:
        - v2-utility
      summary: Get Enhanced Usage Statistics (v2)
      description: Get detailed usage statistics with account information.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Enhanced usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedUsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/version:
    get:
      tags:
        - v2-utility
      summary: Get API Version Info (v2)
      description: Get version and system information for API v2 with user context.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Enhanced version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedVersionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # API v2 Degradation Endpoints (Authenticated)
  /api/v2/degrade:
    post:
      tags:
        - v2-degradation
      summary: Apply Degradation Effects (v2 Exclusive)
      description: |
        Apply realistic degradation effects to existing barcode images to test scanner robustness.

        **v2 Exclusive Feature**: Advanced degradation testing with multiple effect categories.

        **Degradation Categories**:
        - **Damage**: Scratches, fading, water droplets, stains, smudges
        - **Printing**: Low ink quality, broken bars, white noise
        - **Geometry**: Cylindrical warping, flexible wrinkles
        - **Materials**: Metallic reflection, transparent overlay

        **Important**: This endpoint only applies degradation to existing barcode images.
        To generate a new barcode first, use the appropriate generation endpoints
        (`/api/v2/barcode`, `/api/v2/qrcode`, etc.) then pass the image data here.

        **Enhanced Features**:
        - Multiple variants generation
        - Detailed metadata and transformation tracking
        - Support for all image formats (PNG, JPEG, WEBP)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DegradationRequest'
            examples:
              water_damage:
                summary: Water Damage Effects
                value:
                  source:
                    image_data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                  degradation:
                    categories:
                      damage:
                        - type: "water_droplets"
                          count: 5
                          size_range: [10, 25]
                          refraction_strength: 0.7
                          surface_tension: 0.8
                  output:
                    format: "base64"
                    include_metadata: true
              printing_quality:
                summary: Printing Quality Issues
                value:
                  source:
                    image_data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                  degradation:
                    categories:
                      printing:
                        - type: "low_ink"
                          intensity: 0.6
                          pattern: "random"
                        - type: "broken_bars"
                          frequency: 0.3
                          gap_size_range: [1, 3]
                  output:
                    format: "base64"
                    include_metadata: true
              multi_effect:
                summary: Multiple Degradation Effects
                value:
                  source:
                    image_data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                  degradation:
                    categories:
                      damage:
                        - type: "scratches"
                          count: 3
                          severity: 0.5
                        - type: "stains"
                          count: 2
                          stain_type: "grease"
                          opacity_range: [0.3, 0.6]
                      geometry:
                        - type: "cylindrical"
                          radius: 50
                          axis: "vertical"
                    global_params:
                      variants: 3
                      preserve_readability: 0.7
                  output:
                    format: "base64"
                    include_metadata: true
      responses:
        '200':
          description: Degraded barcode generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DegradationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/v2/presets:
    get:
      tags:
        - v2-degradation
      summary: Get Degradation Presets (v2 Exclusive)
      description: |
        Get predefined degradation preset configurations for common testing scenarios.

        **Available Presets**:
        - **light_damage**: Minor wear and tear
        - **moderate_damage**: Typical handling damage
        - **severe_damage**: Heavy degradation
        - **cylindrical_surface**: Curved surface effects
        - **flexible_packaging**: Flexible material warping
        - **poor_conditions**: Multiple adverse effects
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Available degradation presets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DegradationPresetsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  # Authentication Endpoints
  /register:
    post:
      tags:
        - authentication
      summary: Register New Account
      description: Register a new user account and receive an API key.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - email
                - agree_terms
              properties:
                email:
                  type: string
                  format: email
                  description: User email address
                agree_terms:
                  type: boolean
                  description: Must agree to terms of service
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for v2 endpoints. Get your key by registering at `/register`.

        Format: `bcd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

  schemas:
    LinearBarcodeRequest:
      type: object
      required:
        - text
        - barcode_type
      properties:
        text:
          type: string
          description: Text to encode in the barcode
          example: "123456789012"
        barcode_type:
          type: string
          enum: [
            # Code 128 Family
            code128, gs1, gs1_128, ean14, nve18, sscc18, hibc_128, dpd,
            # EAN/UPC Family
            ean, ean2, ean5, ean8, ean13, upc, upca, upce, isbn, isbn10, isbn13, sbn, jan,
            # Code 39 Family
            code39, excode39, code32, hibc_39, vin, logmars,
            # Other Linear Codes
            code93, code11, codabar,
            # Code 2 of 5 Family
            c25standard, c25iata, c25ind, c25inter, itf, c25logic, itf14, dpleit, dpident,
            # Plessey Family
            plessey, msi, msi_plessey,
            # Telepen
            telepen, telepen_num,
            # Pharmaceutical
            pharma, pharmacode, pzn,
            # GS1 DataBar
            dbar_omn, dbar_ltd, dbar_exp, databar_omn, databar_ltd, databar_exp,
            gs1_databar_omn, gs1_databar_ltd, gs1_databar_exp,
            # Postal & Special
            koreapost, channel,
            # Legacy/Aliases
            gtin
          ]
          description: Type of barcode to generate
          example: "code128"
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format (base64 JSON or file download)
        scale:
          type: number
          format: float
          minimum: 0.1
          maximum: 10.0
          description: Scale multiplier for image size (e.g., 2.0 = double size, 0.5 = half size)
          example: 1.0
        degradation:
          type: object
          description: Optional degradation effects to apply to the generated barcode
          properties:
            categories:
              type: object
              description: Degradation categories to apply
              properties:
                damage:
                  type: array
                  description: Physical damage effects (scratches, fading, ink bleeding, etc.)
                  items:
                    type: object
                geometry:
                  type: array
                  description: Geometric transformations (cylindrical, flexible, perspective, etc.)
                  items:
                    type: object
                materials:
                  type: array
                  description: Material effects (metallic reflection, transparent overlay, etc.)
                  items:
                    type: object
            global_params:
              type: object
              description: Global degradation parameters
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate
                seed:
                  type: integer
                  description: Random seed for reproducible results
                preserve_readability:
                  type: number
                  format: float
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.7
                  description: How much to preserve barcode readability (0.0 = no preservation, 1.0 = maximum preservation)
          example:
            categories:
              damage:
                - type: "scratches"
                  count: 3
                  severity: 0.5
                - type: "fading"
                  contrast_reduction: 0.3
                  pattern: "uniform"
            global_params:
              variants: 1
              preserve_readability: 0.7

    QRCodeRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Text to encode in the QR code
          example: "https://example.com"
        error_correction:
          type: string
          enum: [L, M, Q, H]
          default: M
          description: Error correction level
        box_size:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: Size of each box in pixels
        border:
          type: integer
          minimum: 0
          maximum: 20
          default: 4
          description: Border size in boxes
        fill_color:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          default: "#000000"
          description: Foreground color (hex)
        back_color:
          type: string
          pattern: '^#[0-9A-Fa-f]{6}$'
          default: "#ffffff"
          description: Background color (hex)
        logo:
          type: string
          format: byte
          description: |
            Base64 encoded logo image to overlay in the center of the QR code.

            **Requirements:**
            - Must be valid base64 encoded image data
            - Supported image formats: PNG, JPEG, WEBP, GIF, BMP
            - Logo will be automatically scaled to ~20% of QR code size
            - Not supported with SVG output format

            **Note:** When a logo is provided, error correction is automatically upgraded to 'H' (highest) to ensure QR code remains scannable.
          example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format (SVG not supported when using logo)
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format
        degradation:
          type: object
          description: Optional degradation effects to apply to the generated barcode
          properties:
            categories:
              type: object
              description: Degradation categories to apply
              properties:
                damage:
                  type: array
                  description: Physical damage effects (scratches, fading, ink bleeding, etc.)
                  items:
                    type: object
                geometry:
                  type: array
                  description: Geometric transformations (cylindrical, flexible, perspective, etc.)
                  items:
                    type: object
                materials:
                  type: array
                  description: Material effects (metallic reflection, transparent overlay, etc.)
                  items:
                    type: object
            global_params:
              type: object
              description: Global degradation parameters
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate
                seed:
                  type: integer
                  description: Random seed for reproducible results
                preserve_readability:
                  type: number
                  format: float
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.7
                  description: How much to preserve barcode readability (0.0 = no preservation, 1.0 = maximum preservation)
          example:
            categories:
              damage:
                - type: "scratches"
                  count: 3
                  severity: 0.5
                - type: "fading"
                  contrast_reduction: 0.3
                  pattern: "uniform"
            global_params:
              variants: 1
              preserve_readability: 0.7

    BatchRequest:
      type: object
      required:
        - batch
      properties:
        batch:
          type: array
          minItems: 1
          maxItems: 10
          description: Array of generation requests (max 10)
          items:
            oneOf:
              - $ref: '#/components/schemas/BatchBarcodeItem'
              - $ref: '#/components/schemas/BatchQRCodeItem'

    BatchBarcodeItem:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [barcode]
        text:
          type: string
        barcode_type:
          type: string
          enum: [
            # Most common types for batch operations
            code128, code39, ean13, ean8, upca, upce, isbn, gs1_128,
            pharma, pharmacode, pzn, vin, dbar_omn, itf14,
            # Additional common types
            code93, code11, codabar, jan, gtin, msi, telepen,
            c25inter, itf, dpd, hibc_128, hibc_39, channel
          ]
          default: code128
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
        degradation:
          type: object
          description: Optional degradation effects to apply to the generated barcode
          properties:
            categories:
              type: object
              description: Degradation categories to apply
              properties:
                damage:
                  type: array
                  description: Physical damage effects (scratches, fading, ink bleeding, etc.)
                  items:
                    type: object
                geometry:
                  type: array
                  description: Geometric transformations (cylindrical, flexible, perspective, etc.)
                  items:
                    type: object
                materials:
                  type: array
                  description: Material effects (metallic reflection, transparent overlay, etc.)
                  items:
                    type: object
            global_params:
              type: object
              description: Global degradation parameters
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate
                seed:
                  type: integer
                  description: Random seed for reproducible results
                preserve_readability:
                  type: number
                  format: float
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.7
                  description: How much to preserve barcode readability (0.0 = no preservation, 1.0 = maximum preservation)
          example:
            categories:
              damage:
                - type: "scratches"
                  count: 3
                  severity: 0.5
                - type: "fading"
                  contrast_reduction: 0.3
                  pattern: "uniform"
            global_params:
              variants: 1
              preserve_readability: 0.7

    BatchQRCodeItem:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [qrcode]
        text:
          type: string
        error_correction:
          type: string
          enum: [L, M, Q, H]
          default: M
        box_size:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        border:
          type: integer
          minimum: 0
          maximum: 20
          default: 4
        logo:
          type: string
          format: byte
          description: Base64 encoded logo image for QR code overlay
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
        degradation:
          type: object
          description: Optional degradation effects to apply to the generated barcode
          properties:
            categories:
              type: object
              description: Degradation categories to apply
              properties:
                damage:
                  type: array
                  description: Physical damage effects (scratches, fading, ink bleeding, etc.)
                  items:
                    type: object
                geometry:
                  type: array
                  description: Geometric transformations (cylindrical, flexible, perspective, etc.)
                  items:
                    type: object
                materials:
                  type: array
                  description: Material effects (metallic reflection, transparent overlay, etc.)
                  items:
                    type: object
            global_params:
              type: object
              description: Global degradation parameters
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate
                seed:
                  type: integer
                  description: Random seed for reproducible results
                preserve_readability:
                  type: number
                  format: float
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.7
                  description: How much to preserve barcode readability (0.0 = no preservation, 1.0 = maximum preservation)
          example:
            categories:
              damage:
                - type: "scratches"
                  count: 3
                  severity: 0.5
                - type: "fading"
                  contrast_reduction: 0.3
                  pattern: "uniform"
            global_params:
              variants: 1
              preserve_readability: 0.7

    PostalRequest:
      type: object
      required:
        - text
        - postal_type
      properties:
        text:
          type: string
          description: Data to encode in postal barcode
          example: "0123456709498765432101234567891"
        postal_type:
          type: string
          enum: [usps_imd, usps_postnet, usps_planet, royal_mail, ukroyalmail, australia_post, auspost, netherlands_kix, japan_post, japanpost, korea_post, dpleit, dpident, channel]
          description: Type of postal barcode to generate
          example: "usps_imd"
        image_format:
          type: string
          enum: [PNG, JPEG, WEBP]
          default: PNG
          description: Output image format
        output:
          type: string
          enum: [base64, file]
          default: base64
          description: Response format (base64 JSON or file download)
        scale:
          type: number
          format: float
          minimum: 0.1
          maximum: 10.0
          description: Scale multiplier for image size (e.g., 2.0 = double size, 0.5 = half size)
          example: 1.0
        degradation:
          type: object
          description: Optional degradation effects to apply to the generated barcode
          properties:
            categories:
              type: object
              description: Degradation categories to apply
              properties:
                damage:
                  type: array
                  description: Physical damage effects (scratches, fading, ink bleeding, etc.)
                  items:
                    type: object
                geometry:
                  type: array
                  description: Geometric transformations (cylindrical, flexible, perspective, etc.)
                  items:
                    type: object
                materials:
                  type: array
                  description: Material effects (metallic reflection, transparent overlay, etc.)
                  items:
                    type: object
            global_params:
              type: object
              description: Global degradation parameters
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate
                seed:
                  type: integer
                  description: Random seed for reproducible results
                preserve_readability:
                  type: number
                  format: float
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.7
                  description: How much to preserve barcode readability (0.0 = no preservation, 1.0 = maximum preservation)
          example:
            categories:
              damage:
                - type: "scratches"
                  count: 3
                  severity: 0.5
                - type: "fading"
                  contrast_reduction: 0.3
                  pattern: "uniform"
            global_params:
              variants: 1
              preserve_readability: 0.7

    PostalResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        barcode_data:
          type: string
          description: Base64 encoded image data (for POST requests)
        message:
          type: string
          description: Success message with postal type
          example: "USPS Intelligent Mail generated successfully"
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        postal_type:
          type: string
          example: "usps_imd"
        text:
          type: string
          example: "0123456709498765432101234567891"
        user_tier:
          type: string
          enum: [free, basic, pro, enterprise]
          description: User account tier
          example: "free"

    BarcodeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        barcode_type:
          type: string
          example: "code128"
        text:
          type: string
          example: "123456789012"

    EnhancedBarcodeResponse:
      allOf:
        - $ref: '#/components/schemas/BarcodeResponse'
        - type: object
          properties:
            user_tier:
              type: string
              enum: [free, basic, pro, enterprise]
              description: User account tier
              example: "free"

    QRCodeResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: string
          description: Base64 encoded image data
        format:
          type: string
          example: "PNG"
        encoding:
          type: string
          example: "base64"
        error_correction:
          type: string
          example: "M"
        border:
          type: integer
          example: 4
        box_size:
          type: integer
          example: 10
        text:
          type: string
          example: "https://example.com"

    EnhancedQRCodeResponse:
      allOf:
        - $ref: '#/components/schemas/QRCodeResponse'
        - type: object
          properties:
            user_tier:
              type: string
              enum: [free, basic, pro, enterprise]
              example: "free"

    BatchResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        batch_results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Original position in batch
              success:
                type: boolean
              data:
                type: string
                description: Base64 encoded image (if successful)
              format:
                type: string
              encoding:
                type: string
              error:
                type: string
                description: Error message (if failed)
        total_processed:
          type: integer
          example: 3
        user_tier:
          type: string
          enum: [free, basic, pro, enterprise]
          example: "free"

    AccountResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        account:
          type: object
          properties:
            id:
              type: integer
              example: 123
            email:
              type: string
              format: email
              example: "user@example.com"
            tier:
              type: string
              enum: [free, basic, pro, enterprise]
              example: "free"
            active:
              type: boolean
              example: true
            created_at:
              type: string
              format: date-time
              example: "2024-01-01T00:00:00"
            monthly_limit:
              type: integer
              example: 1000
              description: Monthly request limit (-1 for unlimited)
            current_usage:
              type: integer
              example: 150
            remaining:
              oneOf:
                - type: integer
                - type: string
              example: 850
              description: Remaining requests or 'unlimited'

    UsageResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        usage_stats:
          type: object
          properties:
            current_usage:
              type: integer
              example: 150
            monthly_limit:
              type: integer
              example: 1000
            remaining:
              type: integer
              example: 850
            reset_date:
              type: string
              format: date-time

    EnhancedUsageResponse:
      allOf:
        - $ref: '#/components/schemas/UsageResponse'
        - type: object
          properties:
            usage_stats:
              type: object
              properties:
                account_details:
                  type: object
                  properties:
                    tier:
                      type: string
                      enum: [free, basic, pro, enterprise]
                    created_at:
                      type: string
                      format: date-time
                    api_version:
                      type: string
                      example: "2.0"

    VersionResponse:
      type: object
      properties:
        version:
          type: string
          example: "2.0.0"
        api_version:
          type: string
          example: "1.0"
        build_date:
          type: string
          format: date-time
        environment:
          type: string
          example: "production"

    EnhancedVersionResponse:
      allOf:
        - $ref: '#/components/schemas/VersionResponse'
        - type: object
          properties:
            api_version:
              type: string
              example: "2.0"
            authenticated_user:
              type: string
              enum: [free, basic, pro, enterprise]
              description: Current user tier

    RegistrationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Account created successfully"
        api_key:
          type: string
          example: "bcd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          description: Your new API key for v2 endpoints
        user:
          type: object
          properties:
            id:
              type: integer
            email:
              type: string
              format: email
            tier:
              type: string
              enum: [free, basic, pro, enterprise]
              default: free

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
          example: "Invalid parameter"
        message:
          type: string
          description: Detailed error message
          example: "The barcode_type must be one of: code128, code39, ean13"
        provided:
          type: string
          description: Invalid value provided (for validation errors)
          example: "invalid_type"

    # Degradation Schemas
    DegradationRequest:
      type: object
      required:
        - source
        - degradation
      properties:
        source:
          type: object
          description: Source barcode image configuration
          required:
            - image_data
          properties:
            image_data:
              type: string
              description: Base64-encoded barcode image to apply degradation effects to
              example: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
        degradation:
          type: object
          description: Degradation configuration
          properties:
            categories:
              type: object
              description: Categorized degradation effects
              properties:
                damage:
                  type: array
                  description: Physical damage effects that simulate real-world wear and environmental exposure
                  items:
                    anyOf:
                      - $ref: '#/components/schemas/ScratchesEffect'
                      - $ref: '#/components/schemas/FadingEffect'
                      - $ref: '#/components/schemas/WaterDropletsEffect'
                      - $ref: '#/components/schemas/StainsEffect'
                      - $ref: '#/components/schemas/SmudgesEffect'
                      - $ref: '#/components/schemas/MotionBlurEffect'
                      - $ref: '#/components/schemas/GlareEffect'
                      - $ref: '#/components/schemas/InkBleedingEffect'
                      - $ref: '#/components/schemas/BrokenBarsEffect'
                      - $ref: '#/components/schemas/LowInkEffect'
                      - $ref: '#/components/schemas/WhiteNoiseEffect'
                geometry:
                  type: array
                  description: Geometric distortions from curved or flexible surfaces
                  items:
                    anyOf:
                      - $ref: '#/components/schemas/CylindricalEffect'
                      - $ref: '#/components/schemas/FlexibleWrinkleEffect'
                materials:
                  type: array
                  description: Material surface effects that alter light reflection and transmission
                  items:
                    anyOf:
                      - $ref: '#/components/schemas/MetallicReflectionEffect'
                      - $ref: '#/components/schemas/TransparentOverlayEffect'
            global_params:
              type: object
              description: Global degradation parameters that affect all transformations
              properties:
                variants:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: Number of degraded variants to generate. Each variant applies random variations within parameter ranges.
                  example: 3
                seed:
                  type: integer
                  minimum: 0
                  description: Random seed for reproducible results. Use the same seed to get identical degradations.
                  example: 42
        output:
          type: object
          description: Output configuration
          properties:
            format:
              type: string
              enum: [base64, file]
              default: base64
              description: Response format for degraded images
            include_metadata:
              type: boolean
              default: true
              description: Include detailed metadata about applied transformations

    DegradationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        degraded_barcodes:
          type: array
          description: Array of degraded barcode variants
          items:
            type: object
            properties:
              variant_id:
                type: string
                description: Unique identifier for this variant
                example: "variant_001"
              data:
                type: string
                description: Base64 encoded image data
                example: "iVBORw0KGgoAAAANSUhEUgAA..."
              format:
                type: string
                example: "PNG"
              degradation_applied:
                type: object
                description: Summary of degradation effects applied
                properties:
                  environmental:
                    type: array
                    items:
                      type: string
                    example: ["water_droplets", "smudges"]
                  physical:
                    type: array
                    items:
                      type: string
                    example: ["scratches", "stains"]
                  printing:
                    type: object
                    properties:
                      quality_reduction:
                        type: number
                        example: 0.3
                  geometry:
                    type: array
                    items:
                      type: string
                    example: ["cylindrical"]
        metadata:
          type: object
          description: Additional metadata about the degradation process
          properties:
            preset_used:
              type: string
              example: "moderate_damage"
            total_variants:
              type: integer
              example: 3
            processing_time_ms:
              type: number
              example: 247.5

    DegradationPresetsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        presets:
          type: object
          description: Available degradation presets
          properties:
            light_damage:
              type: object
              properties:
                name:
                  type: string
                  example: "Light Damage"
                description:
                  type: string
                  example: "Minor wear and tear - light environmental effects"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["minor_smudges", "light_printing_issues"]
            moderate_damage:
              type: object
              properties:
                name:
                  type: string
                  example: "Moderate Damage"
                description:
                  type: string
                  example: "Typical handling damage - moderate environmental and physical effects"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["water_droplets", "scratches", "reduced_print_quality"]
            severe_damage:
              type: object
              properties:
                name:
                  type: string
                  example: "Severe Damage"
                description:
                  type: string
                  example: "Heavy degradation - multiple adverse effects"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["multiple_stains", "deep_scratches", "poor_print_quality", "smudges"]
            cylindrical_surface:
              type: object
              properties:
                name:
                  type: string
                  example: "Cylindrical Surface"
                description:
                  type: string
                  example: "Barcode applied to curved/cylindrical surface"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["cylindrical_distortion"]
            flexible_packaging:
              type: object
              properties:
                name:
                  type: string
                  example: "Flexible Packaging"
                description:
                  type: string
                  example: "Barcode on flexible material with warping"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["perspective_distortion", "light_creasing"]
            poor_conditions:
              type: object
              properties:
                name:
                  type: string
                  example: "Poor Conditions"
                description:
                  type: string
                  example: "Multiple adverse environmental and handling conditions"
                effects:
                  type: array
                  items:
                    type: string
                  example: ["water_damage", "dirt_stains", "scratches", "poor_printing", "geometric_distortion"]

  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_text:
              summary: Missing required parameter
              value:
                error: "Missing required parameter: text"
                message: "text parameter is required"
            invalid_barcode_type:
              summary: Invalid barcode type
              value:
                error: "Invalid barcode_type"
                message: "barcode_type must be one of: code128, gs1, gs1_128, ean14, nve18, sscc18, hibc_128, dpd, ean, ean2, ean5, ean8, ean13, upc, upca, upce, isbn, isbn10, isbn13, sbn, jan, code39, excode39, code32, hibc_39, vin, logmars, code93, code11, codabar, c25standard, c25iata, c25ind, c25inter, itf, c25logic, itf14, dpleit, dpident, plessey, msi, msi_plessey, telepen, telepen_num, pharma, pharmacode, pzn, dbar_omn, dbar_ltd, dbar_exp, databar_omn, databar_ltd, databar_exp, gs1_databar_omn, gs1_databar_ltd, gs1_databar_exp, koreapost, channel, gtin"
                provided: "invalid_type"

    Unauthorized:
      description: Unauthorized - API key required or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                error: "API key required"
                message: "v2 endpoints require a valid API key. Get one at /register"
            invalid_key:
              summary: Invalid API key
              value:
                error: "Invalid API key"
                message: "The provided API key is invalid or inactive"

    RateLimit:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Rate limit exceeded"
              message:
                type: string
                example: "Monthly limit of 1000 requests exceeded"
              usage_info:
                type: object
                properties:
                  current_usage:
                    type: integer
                    example: 1001
                  monthly_limit:
                    type: integer
                    example: 1000
                  reset_date:
                    type: string
                    format: date-time

    # Detailed Degradation Effect Schemas
    ScratchesEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [scratches]
        count:
          type: integer
          minimum: 1
          maximum: 15
          default: 3
          description: Number of scratches to apply
          example: 5
        severity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.5
          description: Scratch severity (0.1=light surface marks, 1.0=deep gouges)
          example: 0.7
        angle_range:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          default: [0, 180]
          description: Range of scratch angles in degrees [min, max]
          example: [30, 120]
        cross_modules:
          type: boolean
          default: true
          description: Whether scratches can cross barcode modules/bars
          example: true
        width_range:
          type: array
          items:
            type: integer
          minItems: 2
          maxItems: 2
          default: [1, 5]
          description: Range of scratch widths in pixels [min, max]
          example: [2, 4]

    FadingEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [fading]
        contrast_reduction:
          type: number
          minimum: 0.1
          maximum: 0.9
          default: 0.3
          description: Amount of contrast reduction (0.1=slight, 0.9=severe fading)
          example: 0.4
        pattern:
          type: string
          enum: [uniform, gradient, random]
          default: uniform
          description: "Fading pattern: uniform=even across image, gradient=radial from center, random=patchy"
          example: gradient
        center_point:
          type: array
          items:
            type: number
            minimum: 0
            maximum: 1
          minItems: 2
          maxItems: 2
          default: [0.5, 0.5]
          description: Center point for gradient fading [x, y] in normalized coordinates (0-1)
          example: [0.3, 0.7]

    WaterDropletsEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [water_droplets]
        droplet_count:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
          description: Number of water droplets to apply
          example: 8
        size_range:
          type: array
          items:
            type: number
            minimum: 0.01
            maximum: 0.15
          minItems: 2
          maxItems: 2
          default: [0.02, 0.15]
          description: Droplet size range as fraction of image dimensions [min, max]
          example: [0.03, 0.08]
        intensity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.7
          description: Water droplet visibility/opacity
          example: 0.6
        refraction_strength:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.5
          description: Strength of refraction distortion effect (0.1=minimal, 1.0=strong)
          example: 0.8

    StainsEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [stains]
        stain_count:
          type: integer
          minimum: 1
          maximum: 15
          default: 3
          description: Number of stains to apply
          example: 4
        stain_type:
          type: string
          enum: [dirt, ink, grease, food, oil, coffee, mixed]
          default: mixed
          description: "Type of stain: mixed=random types, others=specific stain materials"
          example: oil
        intensity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.6
          description: Stain opacity/visibility
          example: 0.5
        size_range:
          type: array
          items:
            type: number
            minimum: 0.01
            maximum: 0.2
          minItems: 2
          maxItems: 2
          default: [0.03, 0.12]
          description: Stain size range as fraction of image dimensions [min, max]
          example: [0.04, 0.1]

    SmudgesEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [smudges]
        smudge_count:
          type: integer
          minimum: 1
          maximum: 10
          default: 2
          description: Number of smudges to apply
          example: 3
        smudge_type:
          type: string
          enum: [finger, grease, pressure, mixed]
          default: mixed
          description: "Type of smudge: finger=fingerprint patterns, grease=oily smears, pressure=crushing effects"
          example: finger
        intensity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.4
          description: Smudge intensity/darkness
          example: 0.6
        direction_range:
          type: array
          items:
            type: number
            minimum: 0
            maximum: 360
          minItems: 2
          maxItems: 2
          default: [0, 360]
          description: Range of smudge directions in degrees [min, max]
          example: [45, 135]
        size_range:
          type: array
          items:
            type: number
            minimum: 0.05
            maximum: 0.3
          minItems: 2
          maxItems: 2
          default: [0.08, 0.25]
          description: Smudge size range as fraction of image dimensions [min, max]
          example: [0.1, 0.2]

    MotionBlurEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [motion_blur]
        direction:
          type: number
          minimum: 0
          maximum: 360
          default: 0
          description: Blur direction in degrees (0=horizontal, 90=vertical)
          example: 45
        intensity:
          type: number
          minimum: 0.5
          maximum: 10.0
          default: 2.0
          description: Blur intensity/distance in pixels
          example: 3.5

    GlareEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [glare]
        position:
          type: array
          items:
            type: number
            minimum: 0
            maximum: 1
          minItems: 2
          maxItems: 2
          default: [0.5, 0.5]
          description: Glare center position [x, y] in normalized coordinates (0-1)
          example: [0.3, 0.7]
        intensity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.8
          description: Glare brightness/intensity
          example: 0.6
        size:
          type: number
          minimum: 10
          maximum: 200
          default: 50
          description: Glare radius in pixels
          example: 75
        light_direction:
          type: string
          enum: [center, left, right, top, bottom, top-left, top-right, bottom-left, bottom-right]
          default: center
          description: Direction of light source for realistic glare patterns
          example: top-right

    InkBleedingEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [ink_bleeding]
        intensity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.3
          description: Ink bleeding intensity (how much ink spreads)
          example: 0.4
        spread_radius:
          type: integer
          minimum: 1
          maximum: 5
          default: 2
          description: Ink spread radius in pixels
          example: 3

    BrokenBarsEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [broken_bars]
        streak_count:
          type: integer
          minimum: 3
          maximum: 20
          default: 8
          description: Number of white streaks breaking through bars
          example: 12
        streak_width_range:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 8
          minItems: 2
          maxItems: 2
          default: [1, 4]
          description: Width range of streaks in pixels [min, max]
          example: [2, 6]
        intensity:
          type: number
          minimum: 0.5
          maximum: 1.0
          default: 0.8
          description: Intensity of white streaks (brightness)
          example: 0.9
        vertical_coverage:
          type: number
          minimum: 0.3
          maximum: 1.0
          default: 0.7
          description: Vertical coverage of streaks as fraction of image height
          example: 0.8

    LowInkEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [low_ink]
        speckle_density:
          type: number
          minimum: 0.1
          maximum: 0.8
          default: 0.3
          description: Density of white speckles in dark areas
          example: 0.5
        streak_count:
          type: integer
          minimum: 5
          maximum: 30
          default: 12
          description: Number of fine streaks to add
          example: 18
        intensity:
          type: number
          minimum: 0.3
          maximum: 1.0
          default: 0.6
          description: Intensity of low ink effect
          example: 0.7
        speckle_size_range:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 5
          minItems: 2
          maxItems: 2
          default: [1, 3]
          description: Size range of speckles in pixels [min, max]
          example: [1, 4]

    WhiteNoiseEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [white_noise]
        noise_density:
          type: number
          minimum: 0.1
          maximum: 0.8
          default: 0.4
          description: Density of white noise pixels
          example: 0.3
        intensity:
          type: number
          minimum: 0.4
          maximum: 1.0
          default: 0.7
          description: Intensity/brightness of noise pixels
          example: 0.6
        cluster_probability:
          type: number
          minimum: 0.1
          maximum: 0.6
          default: 0.3
          description: Probability of noise clustering together
          example: 0.25
        cluster_size_range:
          type: array
          items:
            type: integer
            minimum: 2
            maximum: 8
          minItems: 2
          maxItems: 2
          default: [2, 5]
          description: Size range of noise clusters [min, max]
          example: [3, 6]

    CylindricalEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [cylindrical]
        radius:
          type: number
          minimum: 10.0
          maximum: 200.0
          default: 50.0
          description: Cylinder radius in pixels (smaller=more curved)
          example: 75.0
        axis:
          type: string
          enum: [vertical, horizontal]
          default: vertical
          description: Cylinder axis orientation
          example: horizontal
        wrap_angle:
          type: number
          minimum: 45.0
          maximum: 360.0
          default: 180.0
          description: How much of cylinder surface the barcode covers in degrees
          example: 120.0

    FlexibleWrinkleEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [flexible_wrinkle]
        fold_count:
          type: integer
          minimum: 1
          maximum: 8
          default: 3
          description: Number of wrinkle/fold lines
          example: 4
        depth:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.5
          description: Depth of wrinkles/folds (0.1=subtle, 1.0=deep)
          example: 0.7
        direction:
          type: string
          enum: [vertical, horizontal, diagonal, random]
          default: random
          description: Direction of wrinkle/fold lines
          example: vertical

    MetallicReflectionEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [metallic_reflection]
        specularity:
          type: number
          minimum: 0.1
          maximum: 1.0
          default: 0.7
          description: Surface specularity/shininess (0.1=matte, 1.0=mirror-like)
          example: 0.8
        roughness:
          type: number
          minimum: 0.0
          maximum: 1.0
          default: 0.3
          description: Surface roughness (0.0=smooth, 1.0=very rough)
          example: 0.2
        reflection_count:
          type: integer
          minimum: 1
          maximum: 5
          default: 2
          description: Number of reflection hotspots
          example: 3

    TransparentOverlayEffect:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [transparent_overlay]
        opacity:
          type: number
          minimum: 0.1
          maximum: 0.9
          default: 0.6
          description: Overlay opacity (0.1=nearly invisible, 0.9=nearly opaque)
          example: 0.4
        refraction_index:
          type: number
          minimum: 1.0
          maximum: 2.0
          default: 1.4
          description: Refractive index of overlay material (1.0=air, 1.5=glass, 2.0=diamond)
          example: 1.5
        thickness:
          type: number
          minimum: 0.1
          maximum: 5.0
          default: 1.0
          description: Overlay thickness affecting refraction strength
          example: 2.0
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            general_error:
              summary: Server error
              value:
                error: "Internal server error"
                message: "An unexpected error occurred while processing your request"