openapi: 3.1.0
info:
  title: TTN Licensing Service
  version: 0.3.0
  description: >
    Simplified licensing service for the TTN desktop application. Client calls
    return a compact license snapshot whenever possible so the desktop keeps the
    most recent quota/status information without calling a separate status API.
servers:
  - url: http://localhost:3001
paths:
  /api/client/register-or-sync:
    post:
      summary: Register or sync a fiscal identifier and current device.
  /api/client/license/status:
    post:
      summary: Read current license status for a fiscal identifier without registering device metadata.
  /api/client/session:
    post:
      summary: Create a short-lived client session and return current license info.
  /api/client/session/refresh:
    post:
      summary: Refresh a client session in the background and return current license info.
      security:
        - bearerAuth: []
  /api/license/consume:
    post:
      summary: Consume quota idempotently for one or more invoice jobs and return current license info.
      security:
        - bearerAuth: []
  /api/client/device/stop:
    post:
      summary: Mark a desktop device session as inactive and return current license info.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    CompactLicenseSnapshot:
      type: object
      description: Minimal desktop-facing license info.
      properties:
        status:
          type: string
          enum: [unconfigured, trial, active, exhausted, pending_payment, blocked, suspended]
        mf:
          type: string
          nullable: true
        remainingQuota:
          type: integer
        totalRemaining:
          type: integer
        paidRemaining:
          type: integer
        trialRemaining:
          type: integer
        usedQuota:
          type: integer
        totalGrantedQuota:
          type: integer
        paymentReference:
          type: string
          nullable: true
        payerBic:
          type: string
          nullable: true
        contactEmail:
          type: string
          nullable: true
        lastSyncAt:
          type: string
          format: date-time
        licenseServerTime:
          type: string
          format: date-time
        message:
          type: string
        features:
          type: array
          items:
            type: string
        canRun:
          type: boolean
