thread-master/apps/backend/generate/api/usage.api

syntax = "v1"

type (
	UsageEventPublic {
		Id        string `json:"id"`
		Uid       int64  `json:"uid"`
		Meter     string `json:"meter"`
		Credits   int    `json:"credits"`
		KeyMode   string `json:"key_mode"`
		Label     string `json:"label"`
		Source    string `json:"source"`
		CreatedAt int64  `json:"created_at"`
	}

	UsageMeterCount {
		Count   int `json:"count"`
		Credits int `json:"credits"`
	}

	UsagePlatformBlock {
		CreditsUsed      int                        `json:"credits_used"`
		CreditsRemaining int                        `json:"credits_remaining"`
		CreditsTotal     int                        `json:"credits_total"`
		CallCount        int                        `json:"call_count"`
		ByMeter          map[string]UsageMeterCount `json:"by_meter,optional"`
	}

	UsageByokBlock {
		CallCount int                        `json:"call_count"`
		ByMeter   map[string]UsageMeterCount `json:"by_meter,optional"`
	}

	UsageSummaryData {
		MonthKey         string             `json:"month_key"`
		Uid              int64              `json:"uid"`
		PlanId           string             `json:"plan_id"`
		Unlimited        bool               `json:"unlimited"`
		Platform         UsagePlatformBlock `json:"platform"`
		Byok             UsageByokBlock     `json:"byok"`
		// FE progress bar (platform only)
		TotalCredits     int `json:"total_credits"`
		RemainingCredits int `json:"remaining_credits"`
	}

	UsageSummaryReq {
		MonthKey string `form:"month_key,optional"`
	}

	UsageEventsReq {
		MonthKey string `form:"month_key,optional"`
		KeyMode  string `form:"key_mode,optional"` // platform|byok|all
		Limit    int    `form:"limit,optional"`
	}

	UsageEventsData {
		List []UsageEventPublic `json:"list"`
	}

	UsagePrefsData {
		PlanId    string `json:"plan_id"`
		Unlimited bool   `json:"unlimited"`
	}

	UsageSetPrefsReq {
		Uid       string `json:"uid"`
		PlanId    string `json:"plan_id,optional"`
		Unlimited *bool  `json:"unlimited,optional"`
	}

	UsagePurchaseReq {
		PlanId  string `json:"plan_id"`
		MockRef string `json:"mock_ref,optional"`
	}

	UsagePurchasePublic {
		Id        string `json:"id"`
		PlanId    string `json:"plan_id"`
		MockRef   string `json:"mock_ref,optional"`
		CreatedAt int64  `json:"created_at"`
	}

	UsagePurchasesData {
		List []UsagePurchasePublic `json:"list"`
	}

	UsageTenantRow {
		Uid                 int64  `json:"uid"`
		PlanId              string `json:"plan_id"`
		Unlimited           bool   `json:"unlimited"`
		PlatformCreditsUsed int    `json:"platform_credits_used"`
		ByokCallCount       int    `json:"byok_call_count"`
	}

	UsageTenantSummaryData {
		MonthKey            string           `json:"month_key"`
		PlatformCreditsUsed int              `json:"platform_credits_used"`
		ByokCallCount       int              `json:"byok_call_count"`
		Members             []UsageTenantRow `json:"members"`
	}

	UsageTenantSummaryReq {
		MonthKey string `form:"month_key,optional"`
	}

	UsageTenantAnalyticsReq {
		Granularity string `form:"granularity"` // day|month|year
		From        string `form:"from"`        // inclusive YYYY-MM-DD UTC
		To          string `form:"to"`          // inclusive YYYY-MM-DD UTC
	}

	UsageTenantAnalyticsBucket {
		Key              string `json:"key"`
		Label            string `json:"label"`
		PurchasedCredits int    `json:"purchased_credits"`
		ConsumedCredits  int    `json:"consumed_credits"`
		AiCalls          int    `json:"ai_calls"`
		SearchCalls      int    `json:"search_calls"`
		ByokCallCount    int    `json:"byok_call_count"`
	}

	UsageTenantAnalyticsMember {
		Uid              int64  `json:"uid"`
		Email            string `json:"email"`
		DisplayName      string `json:"display_name"`
		Unlimited        bool   `json:"unlimited"`
		PlanId           string `json:"plan_id"`
		PurchasedCredits int    `json:"purchased_credits"`
		TotalCredits     int    `json:"total_credits"`
		AiCalls          int    `json:"ai_calls"`
		SearchCalls      int    `json:"search_calls"`
		ByokCallCount    int    `json:"byok_call_count"`
		RemainingCredits int    `json:"remaining_credits"`
		Pct              int    `json:"pct"`
	}

	UsageTenantAnalyticsData {
		Granularity      string                         `json:"granularity"`
		From             string                         `json:"from"`
		To               string                         `json:"to"`
		RangeLabel       string                         `json:"range_label"`
		PurchasedCredits int                            `json:"purchased_credits"`
		ConsumedCredits  int                            `json:"consumed_credits"`
		RemainingCredits int                            `json:"remaining_credits"`
		Pct              int                            `json:"pct"`
		AiCalls          int                            `json:"ai_calls"`
		SearchCalls      int                            `json:"search_calls"`
		ByMeter          map[string]UsageMeterCount     `json:"by_meter"`
		Byok             UsageByokBlock                 `json:"byok"`
		Series           []UsageTenantAnalyticsBucket  `json:"series"`
		Members          []UsageTenantAnalyticsMember  `json:"members"`
	}
)

@server (
	jwt:        Auth
	group:      usage
	prefix:     /api/v1/usage
	middleware: AuthJWT
)
service gateway {
	@handler GetUsageSummary
	get /summary (UsageSummaryReq) returns (UsageSummaryData)

	@handler ListUsageEvents
	get /events (UsageEventsReq) returns (UsageEventsData)

	@handler GetUsagePrefs
	get /prefs returns (UsagePrefsData)

	@handler PurchasePlan
	post /purchase (UsagePurchaseReq) returns (UsagePurchasePublic)

	@handler ListMyPurchases
	get /purchases returns (UsagePurchasesData)
}

@server (
	jwt:        Auth
	group:      usage
	prefix:     /api/v1/usage
	middleware: AuthJWT,AdminAuth
)
service gateway {
	@handler SetUsagePrefs
	post /prefs (UsageSetPrefsReq) returns (UsagePrefsData)

	@handler GetTenantUsageSummary
	get /tenant-summary (UsageTenantSummaryReq) returns (UsageTenantSummaryData)

	@handler GetTenantUsageAnalytics
	get /tenant-analytics (UsageTenantAnalyticsReq) returns (UsageTenantAnalyticsData)
}