openapi: 3.0.1
info:
  title: Vibe Springs API
  description: >-
    Pay-per-use AI utilities: image conversion, PDF generation, CSV processing,
    and historical weather data. All endpoints require x402 USDC payments on
    Base mainnet. No API keys needed.
  version: 'v2'
servers:
  - url: https://vibesprings.net

paths:
  /api/convert-image:
    post:
      operationId: convertImage
      summary: Convert, resize, and optimize images. Supports JPG, PNG, WebP, AVIF.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: Image file (max 10MB)
                format:
                  type: string
                  enum: [webp, jpg, png, avif]
                  default: webp
                width:
                  type: integer
                  description: Resize width in pixels
                height:
                  type: integer
                  description: Resize height in pixels
                quality:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 80
                preset:
                  type: string
                  enum: [nft-ready, web-optimized]
      responses:
        '200':
          description: Converted image binary
          content:
            image/*:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '400':
          description: Invalid input

  /api/generate-pdf:
    post:
      operationId: generatePdf
      summary: Generate professional PDFs from structured JSON data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template:
                  type: string
                  enum: [invoice, resume, report, contract, receipt, document]
                  default: document
                data:
                  type: object
                  description: Template-specific data
                options:
                  type: object
                  properties:
                    pageSize:
                      type: string
                      enum: [A4, Letter]
                    watermark:
                      type: string
      responses:
        '200':
          description: PDF binary
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/process-csv:
    post:
      operationId: processCsv
      summary: Clean, filter, and analyze CSV files. Output as JSON, CSV, or PDF summary.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file (max 10MB)
                instructions:
                  type: string
                  description: JSON string with processing instructions
      responses:
        '200':
          description: Processed data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CsvResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/weather:
    get:
      operationId: getHistoricalWeather
      summary: Get historical weather data for any location and date range.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
          description: City name or location
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD, must be in the past)
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD, must be yesterday or earlier)
      responses:
        '200':
          description: Historical weather data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherResult'
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'


  /api/forecast:
    get:
      operationId: getForecast
      summary: Up to 16-day weather forecast for any location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Forecast data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/air-quality:
    get:
      operationId: getAirQuality
      summary: Current and forecast air quality for any location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Air quality data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/marine:
    get:
      operationId: getMarineWeather
      summary: Marine and ocean conditions for coastal locations.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Marine weather data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/earthquakes:
    get:
      operationId: getEarthquakes
      summary: Recent earthquakes near a location.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Earthquake data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/flood:
    get:
      operationId: getFlood
      summary: Flood risk and river discharge data.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Flood data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/solar:
    get:
      operationId: getSolar
      summary: Solar radiation and energy forecast.
      parameters:
        - name: location
          in: query
          required: true
          schema:
            type: string
        - name: days
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Solar data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/exchange:
    get:
      operationId: getExchangeRates
      summary: Real-time and historical fiat exchange rates.
      parameters:
        - name: base
          in: query
          required: false
          schema:
            type: string
        - name: target
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Exchange rate data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/holidays:
    get:
      operationId: getHolidays
      summary: Public holidays for any country.
      parameters:
        - name: country
          in: query
          required: true
          schema:
            type: string
        - name: year
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Holiday data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/exchange/convert:
    get:
      operationId: convertCurrency
      summary: Convert an amount between any two fiat currencies with live ECB rates.
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: string
          description: Source currency ISO code (e.g. GBP, USD)
        - name: to
          in: query
          required: true
          schema:
            type: string
          description: Target currency ISO code (e.g. JPY, EUR)
        - name: amount
          in: query
          required: false
          schema:
            type: string
          description: Amount to convert (default 1)
      responses:
        '200':
          description: Conversion result with rate and inverse rate
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/exchange/history:
    get:
      operationId: getExchangeHistory
      summary: Daily exchange rate time series for any currency pair, up to 365 days.
      parameters:
        - name: base
          in: query
          required: false
          schema:
            type: string
          description: Base currency ISO code (default USD)
        - name: to
          in: query
          required: false
          schema:
            type: string
          description: Target currency ISO code (default EUR)
        - name: start
          in: query
          required: true
          schema:
            type: string
          description: Start date YYYY-MM-DD
        - name: end
          in: query
          required: true
          schema:
            type: string
          description: End date YYYY-MM-DD
      responses:
        '200':
          description: Time series data with summary statistics
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/crypto:
    get:
      operationId: getCryptoPrices
      summary: Live cryptocurrency prices, market caps, volume, and changes for top tokens.
      parameters:
        - name: ids
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated CoinGecko IDs (e.g. bitcoin,ethereum). Omit for top coins.
        - name: vs
          in: query
          required: false
          schema:
            type: string
          description: Quote currency (usd, eur, gbp, jpy, btc, eth). Default usd.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Max results 1-100 (default 25)
      responses:
        '200':
          description: Cryptocurrency market data
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/workflow/invoice-fx:
    post:
      operationId: generateInvoiceFX
      summary: Multi-currency invoice workflow. Converts line items to target currency and generates PDF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from, to, targetCurrency, items]
              properties:
                invoiceNumber:
                  type: string
                from:
                  type: object
                  properties:
                    name:
                      type: string
                    address:
                      type: string
                    email:
                      type: string
                to:
                  type: object
                  properties:
                    name:
                      type: string
                    address:
                      type: string
                    email:
                      type: string
                targetCurrency:
                  type: string
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      description:
                        type: string
                      quantity:
                        type: number
                      unitPrice:
                        type: number
                      currency:
                        type: string
                notes:
                  type: string
                dueDate:
                  type: string
      responses:
        '200':
          description: Generated PDF invoice
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/alert:
    post:
      operationId: sendAlert
      summary: Dispatch secure, PII-scrubbed email alerts to human operators.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  description: The recipient email address.
                  format: email
                subject:
                  type: string
                  description: The subject of the alert email (maximum 120 characters).
                  maxLength: 120
                body:
                  type: string
                  description: The body of the notification (maximum 2000 characters).
                  maxLength: 2000
              required:
                - to
                - subject
                - body
      responses:
        '200':
          description: Alert successfully scrubbed and sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  recipient:
                    type: string
                  processingTime:
                    type: string
        '402':
          description: Payment Required (x402)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

components:
  schemas:
    PaymentRequired:
      type: object
      properties:
        x402Version:
          type: integer
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
              network:
                type: string
              maxAmountRequired:
                type: string
              resource:
                type: string
              description:
                type: string
              payTo:
                type: string
              asset:
                type: string
        facilitatorUrl:
          type: string

    WeatherResult:
      type: object
      properties:
        location:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        days:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              temp_max_c:
                type: number
              temp_min_c:
                type: number
              precipitation_mm:
                type: number
              condition:
                type: string
        summary:
          type: object
          properties:
            avg_temp_c:
              type: number
            total_precipitation_mm:
              type: number
            days_with_rain:
              type: integer

    CsvResult:
      type: object
      properties:
        status:
          type: string
        stats:
          type: object
          properties:
            rowsBefore:
              type: integer
            rowsAfter:
              type: integer
            issuesFixed:
              type: integer
            columns:
              type: integer
        data:
          type: array
          items:
            type: object