openapi: 3.1.0
info:
  title: Logynfra Intelligence Hub API
  version: "v1"
  description: >
    The Brain of Logynfra. Predictive intelligence, real-time visibility, 
    carrier performance scoring, and ESG (Environmental, Social, Governance) tracking.
servers:
  - url: https://intelligence.logynfra.com/v1
    description: Production Intelligence Environment

paths:
  /intelligence/predict-eta:
    post:
      summary: Predict shipment ETA and risk of delay
      description: Ingests signals and historical data to provide a predictive ETA and a delay probability score.
      operationId: predictEta
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipmentId: { type: string }
                originId: { type: string }
                destinationId: { type: string }
                carrierId: { type: string }
                currentLocation: 
                  type: object
                  properties:
                    lat: { type: number }
                    lng: { type: number }
      responses:
        '200':
          description: Predictive ETA calculated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ETAPredictionResponse'

  /analytics/carrier-performance:
    get:
      summary: Get Carrier Trust Score and Performance Tier
      description: Returns the "Trust Score" and tiered access level of a carrier based on historical reliability and documentation accuracy.
      operationId: getCarrierPerformance
      parameters:
        - name: carrierId
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Carrier performance data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPerformanceResponse'

  /sustainability/carbon-footprint:
    post:
      summary: Calculate Shipment Carbon Footprint
      description: Calculates the estimated CO2e emissions for a shipment and suggests green routing alternatives.
      operationId: calculateCarbonFootprint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                weightKg: { type: number }
                distanceKm: { type: number }
                transportMode: 
                  type: string
                  enum: [ROAD, RAIL, AIR, OCEAN]
      responses:
        '200':
          description: Carbon footprint calculated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarbonFootprintResponse'

components:
  schemas:
    ETAPredictionResponse:
      type: object
      properties:
        shipmentId: { type: string }
        predictedEta: { type: string, format: date-time }
        delayProbability: { type: number, description: "0.0 to 1.0 probability of delay" }
        riskFactors: 
          type: array
          items: { type: string }
        recommendedAlternativeRoute: { type: string, nullable: true }
    
    CarrierPerformanceResponse:
      type: object
      properties:
        carrierId: { type: string }
        trustScore: { type: number, description: "Score out of 1000" }
        tier: { type: string, enum: [TIER_1_INSTITUTIONAL, STANDARD, PROBATION, OPEN_SANDBOX] }
        metrics:
          type: object
          properties:
            onTimeDeliveryRate: { type: number }
            documentationAccuracy: { type: number }

    CarbonFootprintResponse:
      type: object
      properties:
        estimatedCO2eKg: { type: number }
        transportMode: { type: string }
        greenRoutingAlternative:
          type: object
          nullable: true
          properties:
            suggestedMode: { type: string }
            potentialCO2eSavingsKg: { type: number }
