openapi: 3.0.0
info:
  title: GroundControl push server API
  description: Push notifications server for BlueWallet
  version: 0.0.14
servers:
  - url: http://localhost:3001
  - url: https://groundcontrol-bluewallet.herokuapp.com
  - url: https://groundcontrol.bluewallet.io/
paths:
  /lightningInvoiceGotSettled:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LightningInvoiceSettledNotification"
      responses:
        "200":
          description: OK

  /majorTomToGroundControl:
    post:
      summary: "Associate bitcoin addressess / ln preimage hashes / txids that you wish to be notified about to specific push token. Token serves as unique identifier of a device/user. Also, OS of the token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                hashes:
                  type: array
                  items:
                    type: string
                txids:
                  type: array
                  items:
                    type: string
                token:
                  type: string
                os:
                  type: string
      responses:
        "201":
          description: Created

  /unsubscribe:
    post:
      summary: "This call is a reverse call for /majorTomToGroundControl. In case user doesnt want to track addresses/txids/ln invoice hashes, he makes this call along with his token/os so GroundControl can remove them from the database"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                hashes:
                  type: array
                  items:
                    type: string
                txids:
                  type: array
                  items:
                    type: string
                token:
                  type: string
                os:
                  type: string
      responses:
        "201":
          description: Created

  /ping:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerInfo"

  /getTokenConfiguration:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                os:
                  type: string
      summary: "Returns levels of notifications user currently subscribed to"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenConfiguration"

  /setTokenConfiguration:
    post:
      summary: "Sets levels of notifications user is subscribed to; also saves some user info, like lang or app version"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/TokenConfiguration"
                - type: object
                  required:
                    - token
                    - os
                  properties:
                    token:
                      type: "string"
                    os:
                      type: "string"
      responses:
        "200":
          description: OK

  /enqueue:
    post:
      summary: "Puts push in send queue. Push body should be any descendant of `/components/schemas/PushNotificationBase`"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/PushNotificationLightningInvoicePaid"
                - $ref: "#/components/schemas/PushNotificationOnchainAddressGotPaid"
                - $ref: "#/components/schemas/PushNotificationOnchainAddressGotUnconfirmedTransaction"
                - $ref: "#/components/schemas/PushNotificationTxidGotConfirmed"
      responses:
        "200":
          description: OK

components:
  schemas:
    ServerInfo:
      type: "object"
      properties:
        name:
          type: "string"
        description:
          type: "string"
        version:
          type: "string"
        uptime:
          type: "number"
        last_processed_block:
          type: "number"
        send_queue_size:
          type: "number"
        sent_24h:
          type: "number"

    NotificationLevel:
      type: string
      enum:
        - transactions
        - news
        - price
        - tips

    TokenConfiguration:
      type: "object"
      properties:
        level_all:
          type: "boolean"
        level_transactions:
          type: "boolean"
        level_news:
          type: "boolean"
        level_price:
          type: "boolean"
        level_tips:
          type: "boolean"
        redacted:
          type: "boolean"
          description: "when true, server sends generic push text and omits data payload"
        lang:
          type: "string"
        app_version:
          type: "string"

    LightningInvoiceSettledNotification:
      description: object thats posted to GroundControl to notify end-user that his specific invoice was paid by someone
      type: "object"
      properties:
        memo:
          type: "string"
          description: "text that was embedded in invoice paid"
        preimage:
          type: "string"
          description: "hex string preimage"
        hash:
          type: "string"
          description: "hex string preimage hash"
        amt_paid_sat:
          type: "number"
          description: "exactly how much satoshis was paid to make this invoice settked (>= invoice amount)"

    PushNotificationBase:
      description: payload for push notification delivered to phone
      type: object
      required:
        - type
        - level
        - os
        - token
      properties:
        "type":
          type: "integer"
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          description: >
            type:
             * `1` - Your lightning invoice was paid
             * `2` - New transaction to one of your addresses
             * `3` - New unconfirmed transaction to one of your addresses
             * `4` - Transaction confirmed
             * `5` - Arbitrary text message
        "token":
          type: "string"
        "os":
          type: "string"
          enum:
            - "android"
            - "ios"
        badge:
          type: "integer"
        level:
          $ref: "#/components/schemas/NotificationLevel"

    PushNotificationLightningInvoicePaid:
      allOf: # Combines PushNotificationBase and the inline model
        - $ref: "#/components/schemas/PushNotificationBase"
        - type: object
          required:
            - sat
            - hash
            - memo
          properties:
            type:
              type: "integer"
              enum: [1]
            level:
              type: "string"
              enum: ["transactions"]
            sat:
              type: "integer"
              description: amount of satoshis
            hash:
              type: "string"
              description: hash of specific ln invoice preimage
            memo:
              type: "string"
              description: text attached to bolt11

    PushNotificationOnchainAddressGotPaid:
      allOf: # Combines PushNotificationBase and the inline model
        - $ref: "#/components/schemas/PushNotificationBase"
        - type: object
          required:
            - address
            - sat
            - txid
          properties:
            type:
              type: "integer"
              enum: [2]
            level:
              type: "string"
              enum: ["transactions"]
            sat:
              type: "integer"
              description: amount of satoshis
            address:
              type: "string"
              description: user's onchain address that has incoming transaction
            txid:
              type: "string"
              description: txid of the transaction where this address is one of the outputs

    PushNotificationOnchainAddressGotUnconfirmedTransaction:
      allOf: # Combines PushNotificationBase and the inline model
        - $ref: "#/components/schemas/PushNotificationBase"
        - type: object
          required:
            - address
            - sat
            - txid
          properties:
            type:
              type: "integer"
              enum: [3]
            level:
              type: "string"
              enum: ["transactions"]
            sat:
              type: "integer"
              description: amount of satoshis
            address:
              type: "string"
              description: user's onchain address that has incoming transaction
            txid:
              type: "string"
              description: txid of the transaction where this address is one of the outputs

    PushNotificationTxidGotConfirmed:
      allOf: # Combines PushNotificationBase and the inline model
        - $ref: "#/components/schemas/PushNotificationBase"
        - type: object
          required:
            - txid
          properties:
            type:
              type: "integer"
              enum: [4]
            level:
              type: "string"
              enum: ["transactions"]
            txid:
              type: "string"
              description: txid of the transaction that got confirmed

    PushNotificationMessage:
      allOf: # Combines PushNotificationBase and the inline model
        - $ref: "#/components/schemas/PushNotificationBase"
        - type: object
          required:
            - text
          properties:
            type:
              type: "integer"
              enum: [5]
            text:
              type: "string"
              description: custom text thats displayed on push notification buble