feat(mgmt): add credit purchase endpoints (#360)

Because

- Instill Cloud must allow for credit purchase & purchase history.

This commit

- Exposes the data required in the purchase page via 2 endpoints:
- Get remaining credit returns detailed information about remaining
credit.
  - List purchases returns a paginated list of credit purchases.

![CleanShot 2024-06-11 at 13 31
25](https://github.com/instill-ai/protobufs/assets/3977183/fd9b37f8-da71-4181-825f-fcd6611c891e)

---------

Co-authored-by: droplet-bot <[email protected]>

core/mgmt/v1beta/mgmt.proto

@@ -589,8 +589,16 @@ message GetRemainingCreditRequest {
 // GetRemainingCreditResponse contains the remaining credit of a user or
 // organization.
 message GetRemainingCreditResponse {
-  // The requested credit.
-  float amount = 1;
+  // 1 is reserved for the previous endpoint version, where only the total
+  // amount was returned.
+  reserved 1;
+  // Amount of perishable credit, i.e. credit with an expiration date.
+  float perishable = 2;
+  // Amount of imperishable credit, e.g. purchased credit, which doesn't
+  // expire.
+  float imperishable = 3;
+  // Total remaining credit.
+  float total = 4;
 }
 
 // GetRemainingCreditAdminRequest represents a request to get the remaining

core/mgmt/v1beta/mgmt_public_service.proto

@@ -281,11 +281,9 @@ service MgmtPublicService {
 
   // Get the remaining Instill Credit
   //
-  // On Instill Cloud, users can use Instill Credit to execute pre-configured
-  // AI connectors. This simplifies the pipeline setup, removing the need to
-  // subscribe to third-party AI services. This endpoint returns the remaining
-  // Instill Credit of a given user or organization. The requested credit owner
-  // must be either the authenticated user or an organization they belong to.
+  // This endpoint returns the remaining [Instill Credit](https://www.instill.tech/docs/vdp/credit) of a given user or
+  // organization. The requested credit owner must be either the authenticated
+  // user or an organization they belong to.
   //
   // On Instill Core, this endpoint will return a 404 Not Found status.
   rpc GetRemainingCredit(GetRemainingCreditRequest) returns (GetRemainingCreditResponse) {

openapiv2/core/service.swagger.yaml

@@ -897,11 +897,9 @@ paths:
     get:
       summary: Get the remaining Instill Credit
       description: |-
-        On Instill Cloud, users can use Instill Credit to execute pre-configured
-        AI connectors. This simplifies the pipeline setup, removing the need to
-        subscribe to third-party AI services. This endpoint returns the remaining
-        Instill Credit of a given user or organization. The requested credit owner
-        must be either the authenticated user or an organization they belong to.
+        This endpoint returns the remaining [Instill Credit](https://www.instill.tech/docs/vdp/credit) of a given user or
+        organization. The requested credit owner must be either the authenticated
+        user or an organization they belong to.
 
         On Instill Core, this endpoint will return a 404 Not Found status.
       operationId: MgmtPublicService_GetRemainingCredit
@@ -2092,10 +2090,20 @@ definitions:
   v1betaGetRemainingCreditResponse:
     type: object
     properties:
-      amount:
+      perishable:
         type: number
         format: float
-        description: The requested credit.
+        description: Amount of perishable credit, i.e. credit with an expiration date.
+      imperishable:
+        type: number
+        format: float
+        description: |-
+          Amount of imperishable credit, e.g. purchased credit, which doesn't
+          expire.
+      total:
+        type: number
+        format: float
+        description: Total remaining credit.
     description: |-
       GetRemainingCreditResponse contains the remaining credit of a user or
       organization.