feat: add organization balance API (#13964)

Author: Tim Roes

airbyte-api/problems-api/src/main/openapi/api-problems.yaml

@@ -549,6 +549,38 @@ components:
               default: An unexpected error occurred when creating your GitHub contribution.
             data:
               $ref: "#/components/schemas/GithubContributionProblemData"
+    BillingSubscriptionRequiredProblemResponse:
+      x-implements: io.airbyte.api.problems.ProblemResponse
+      type: object
+      allOf:
+        - $ref: "#/components/schemas/BaseProblemFields"
+        - type: object
+          properties:
+            status:
+              type: integer
+              default: 404
+            type:
+              type: string
+              default: error:billing/subscription/subscription-required
+            title:
+              type: string
+              default: A subscription is required for this operation to succeed.
+    BillingTooManyNonPrepaidSubscriptionsProblemResponse:
+      x-implements: io.airbyte.api.problems.ProblemResponse
+      type: object
+      allOf:
+        - $ref: "#/components/schemas/BaseProblemFields"
+        - type: object
+          properties:
+            status:
+              type: integer
+              default: 400
+            type:
+              type: string
+              default: error:billing/subscription/too-many-incompatible-subscriptions
+            title:
+              type: string
+              default: Found more than one subscription with some not being prepaid.
     ProblemCronData:
       type: object
       properties:

airbyte-api/server-api/src/main/openapi/config.yaml

@@ -4609,6 +4609,25 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/PaymentInformationRead"
+  /v1/billing/organization_balance:
+    post:
+      summary: Get the current balance of an organization
+      tags:
+        - billing
+        - cloud-only
+      operationId: getOrganizationBalance
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrganizationIdRequestBody"
+      responses:
+        "200":
+          description: Successfully got organization's balance
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OrganizationBalanceRead"
   /v1/organizations/get:
     post:
       summary: Get an organization info
@@ -10431,6 +10450,56 @@ components:
               $ref: "#/components/schemas/AddressRead"
             defaultPaymentMethod:
               $ref: "#/components/schemas/PaymentMethodRead"
+    OrganizationBalanceRead:
+      type: object
+      required:
+        - upcomingInvoice
+        - planType
+      properties:
+        planType:
+          description: Whether the customer is on a prepaid or in_arrears type plan. This is only used during the migration and will be removed after the migration again.
+          type: string
+          enum:
+            - in_arrears
+            - prepaid
+          deprecated: true
+        upcomingInvoice:
+          type: object
+          required:
+            - currency
+            - amount
+            - dueDate
+          properties:
+            currency:
+              type: string
+            amount:
+              type: string
+              description: The amount of the next upcoming invoice formatted as a decimal number wrapped inside a string.
+            dueDate:
+              $ref: "#/components/schemas/LocalDate"
+        credits:
+          type: object
+          required:
+            - balance
+            - blocks
+          properties:
+            balance:
+              type: number
+              format: double
+            blocks:
+              type: array
+              items:
+                $ref: "#/components/schemas/CreditBlockRead"
+    CreditBlockRead:
+      type: object
+      required:
+        - amount
+      properties:
+        amount:
+          type: number
+          format: double
+        expiryDate:
+          $ref: "#/components/schemas/ISO8601DateTime"
 
     # ORGANIZATIONS
     OrganizationId:
@@ -14250,10 +14319,15 @@ components:
         - destination
       x-sdk-component: true
 
+    LocalDate:
+      type: string
+      format: date
+      x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonFormat(pattern="yyyy-MM-dd")'
+
     ISO8601DateTime:
       type: string
       format: date-time
-      x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonFormat(pattern="yyyy-MM-dd''T''HH:mm:ss.SSS''Z''")'
+      x-field-extra-annotation: '@com.fasterxml.jackson.annotation.JsonFormat(pattern="yyyy-MM-dd''T''HH:mm:ss.SSSZ")'
 
     DiagnosticReportRequestBody:
       type: object

airbyte-server/src/main/kotlin/io/airbyte/server/apis/controllers/BillingController.kt

@@ -4,6 +4,7 @@ import io.airbyte.api.generated.BillingApi
 import io.airbyte.api.model.generated.CustomerPortalRead
 import io.airbyte.api.model.generated.CustomerPortalRequestBody
 import io.airbyte.api.model.generated.ListInvoicesRead
+import io.airbyte.api.model.generated.OrganizationBalanceRead
 import io.airbyte.api.model.generated.OrganizationIdRequestBody
 import io.airbyte.api.model.generated.PaymentInformationRead
 import io.airbyte.api.problems.throwable.generated.ApiNotImplementedInOssProblem
@@ -43,4 +44,13 @@ open class BillingController : BillingApi {
   ): PaymentInformationRead {
     throw ApiNotImplementedInOssProblem()
   }
+
+  @RequiresIntent(Intent.ManageOrganizationBilling)
+  @Post("/organization_balance")
+  @ExecuteOn(AirbyteTaskExecutors.IO)
+  override fun getOrganizationBalance(
+    @Body organizationIdRequestBody: OrganizationIdRequestBody,
+  ): OrganizationBalanceRead {
+    throw ApiNotImplementedInOssProblem()
+  }
 }