gitpod/components/usage-api/usage/v1/usage.proto

syntax = "proto3";

package usage.v1;

option go_package = "github.com/gitpod-io/gitpod/usage-api/v1";

import "google/protobuf/timestamp.proto";

service UsageService {

    // GetCostCenter retrieves the active cost center for the given attributionID
    rpc GetCostCenter(GetCostCenterRequest) returns (GetCostCenterResponse) {}

    // SetCostCenter stores the given cost center
    rpc SetCostCenter(SetCostCenterRequest) returns (SetCostCenterResponse) {}

    // Triggers reconciliation of usage.
    rpc ReconcileUsage(ReconcileUsageRequest) returns (ReconcileUsageResponse) {}

    // ListUsage retrieves all usage for the specified attributionId and theb given time range
    rpc ListUsage(ListUsageRequest) returns (ListUsageResponse) {}
}

message ReconcileUsageRequest {
    // from specifies the starting time range for this request.
    google.protobuf.Timestamp from = 1;

    // to specifies the end time range for this request.
    google.protobuf.Timestamp to = 2;
}

message ReconcileUsageResponse {}

message PaginatedRequest {
    int64 per_page = 1;
    int64 page = 2;
}

message PaginatedResponse {
    int64 per_page = 2;
    int64 total_pages = 3;
    int64 total = 4;
    int64 page = 5;
}

message ListUsageRequest {
    string attribution_id = 1;

    // from specifies the starting time range for this request.
    // All instances which existed starting at from will be returned.
    google.protobuf.Timestamp from = 2;

    // to specifies the end time range for this request.
    // All instances which existed ending at to will be returned.
    google.protobuf.Timestamp to = 3;

    enum Ordering {
        ORDERING_DESCENDING = 0;
        ORDERING_ASCENDING = 1;
    }

    Ordering order = 4;

    PaginatedRequest pagination = 5;
}

message ListUsageResponse {
    repeated Usage usage_entries = 1;
    PaginatedResponse pagination = 2;
    // the amount of credits the given account (attributionId) had at the beginning of the requested period
    double credit_balance_at_start = 3;

    // the amount of credits the given account (attributionId) had at the end of the requested period
    double credit_balance_at_end = 4;
}

message Usage {
    string id = 1;
	string attribution_id = 2;
	string description = 3;
	double credits = 4;
    google.protobuf.Timestamp effective_time = 5;

    enum Kind {
        KIND_WORKSPACE_INSTANCE = 0;
        KIND_INVOICE = 1;
    }
	Kind kind = 6;
	string workspace_instance_id = 7;
	bool draft = 8;
	string metadata = 9;
}

message SetCostCenterRequest {
    CostCenter cost_center = 1;
}

message SetCostCenterResponse {
}

message GetCostCenterRequest {
    string attribution_id = 1;
}

message GetCostCenterResponse {
    CostCenter cost_center = 1;
}

message CostCenter {
    string attribution_id = 1;
    int32 spending_limit = 2;
    enum BillingStrategy {
        BILLING_STRATEGY_STRIPE = 0;
        BILLING_STRATEGY_OTHER = 1;
    }
    BillingStrategy billing_strategy = 3;
}