The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
cursorusage: add a Cursor Admin API usage-events client
Claudea860ce4cbad8
diff --git a/cli/beacon/internal/cursorusage/client.go b/cli/beacon/internal/cursorusage/client.gonew file mode 100644index 00000000..d09ed25f--- /dev/null+++ b/cli/beacon/internal/cursorusage/client.go@@ -0,0 +1,615 @@+// Package cursorusage reads Cursor's per-request token usage from the Cursor Admin API.+//+// Cursor is the one large runtime whose local surfaces carry no spend at all. No hook payload has a+// token count (preCompact reports context occupancy, which is a level, not spend), and the+// Composer records in Cursor's own state.vscdb carry no usage either. The only place Cursor+// publishes what a request cost is its Admin API, which reports every model call a team member+// made with its token counts and the amount Cursor charged for it:+//+// POST https://api.cursor.com/teams/filtered-usage-events+// Authorization: Basic base64(<admin API key>:)+// {"startDate": <ms>, "endDate": <ms>, "page": 1, "pageSize": 100, "email": "...", "userId": 123}+//+// The response lists events under usageEventsDisplay (older responses: usageEvents), each with a+// millisecond timestamp, the model, a tokenUsage block (inputTokens, outputTokens,+// cacheWriteTokens, cacheReadTokens, totalCents) and the charge in chargedCents.+//+// This package is only the client. It never reads a key from anywhere itself, never writes one,+// and never puts one in an error: the caller hands it a key it got from the environment, and the+// key leaves this process only as the basic-auth header of a request to the configured Cursor+// host. Talking to the network is the explicit, user-started `beacon endpoint cursor usage sync`;+// nothing in a hook or a scheduled Beacon job calls it.+package cursorusage++import (+ "bytes"+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "io"+ "math"+ "net"+ "net/http"+ "net/url"+ "strconv"+ "strings"+ "time"+)++// DefaultBaseURL is Cursor's Admin API host.+const DefaultBaseURL = "https://api.cursor.com"++// UsageEventsPath is the endpoint that lists per-request usage events.+const UsageEventsPath = "/teams/filtered-usage-events"++const (+ defaultPageSize = 100+ // maxPageSize is the most a page may ask for. Cursor's own dashboard pages at 100; a caller+ // asking for more gets the cap rather than a request the API may reject.+ maxPageSize = 1000+ // maxResponseBytes bounds one page's body. A page of a thousand events is tens of kilobytes,+ // so this is generous for a real response and still stops a misbehaving host from streaming+ // without end into memory.+ maxResponseBytes = 32 << 20+ // maxPages stops a paging loop that a host keeps saying has another page.+ maxPages = 10000+ // maxAttempts is how many times one page is tried. The Admin API rate-limits per team, and a+ // sync that pages through a busy week can meet a 429 partway; giving up on the first one+ // would leave every later page for the next run.+ maxAttempts = 4+ // maxRetryWait caps how long a Retry-After header can make one attempt wait.+ maxRetryWait = 60 * time.Second+)++// Client talks to the Cursor Admin API.+type Client struct {+ BaseURL string+ APIKey string+ HTTPClient *http.Client+ // UserAgent is sent on every request. Empty sends Go's default.+ UserAgent string+ // Sleep waits between retries. Nil uses a context-aware timer; tests replace it.+ Sleep func(context.Context, time.Duration) error+}++// NewClient returns a client for Cursor's own host.+func NewClient(apiKey string) *Client {+ return &Client{+ BaseURL: DefaultBaseURL,+ APIKey: apiKey,+ HTTPClient: &http.Client{Timeout: 30 * time.Second},+ }+}++// TokenUsage is the token block of one usage event. TotalCents is Cursor's price for the tokens,+// which is not necessarily what was charged: a request included in a plan has a token price and+// no charge.+type TokenUsage struct {+ InputTokens int64+ OutputTokens int64+ CacheWriteTokens int64+ CacheReadTokens int64+ TotalCents *float64+}++// UsageEvent is one model request as the Admin API reports it.+type UsageEvent struct {+ Timestamp time.Time+ Model string+ Kind string+ MaxMode bool+ // TokenBased reports isTokenBasedCall: whether the request was billed by tokens rather than+ // as a flat request.+ TokenBased bool+ TokenUsage TokenUsage+ // ChargedCents is what Cursor charged for the request. Nil when the response did not say.+ ChargedCents *float64+ // CursorTokenFeeCents is Cursor's own fee on top of the model price. Nil when absent.+ CursorTokenFeeCents *float64+ // RequestsCosts is the number of plan requests the call consumed. Nil when absent.+ RequestsCosts *float64+ Chargeable *bool+ Headless bool+ UserID string+ UserEmail string+}++// Query selects one window of usage events.+type Query struct {+ StartDate time.Time+ EndDate time.Time+ // Email and UserID filter to one team member. Both empty asks for the whole team.+ Email string+ UserID string+ // PageSize is the number of events per request. Zero means 100.+ PageSize int+}++// Page is one paginated response.+type Page struct {+ TotalCount int+ // HasNextPage is the response's own pagination.hasNextPage, when it sent one.+ HasNextPage *bool+ Events []UsageEvent+}++// StatusError is a non-2xx response. It carries the status only: the body of an error from an+// authenticated API is not something to print, and the key is never in it.+type StatusError struct {+ StatusCode int+ Status string+}++func (e *StatusError) Error() string {+ switch e.StatusCode {+ case http.StatusUnauthorized, http.StatusForbidden:+ return fmt.Sprintf("cursor admin API returned %s: check that the key is a Cursor Admin API key for a team admin", e.Status)+ }+ return fmt.Sprintf("cursor admin API returned %s", e.Status)+}++// ErrMissingAPIKey is returned when the client has no key.+var ErrMissingAPIKey = errors.New("missing Cursor Admin API key")++// ValidateBaseURL accepts an https URL, or plain http to a loopback address. Plain http anywhere+// else would send the admin key in the clear, so it is refused rather than warned about.+func ValidateBaseURL(raw string) (string, error) {+ raw = strings.TrimSpace(raw)+ if raw == "" {+ return DefaultBaseURL, nil+ }+ parsed, err := url.Parse(raw)+ if err != nil {+ return "", fmt.Errorf("invalid Cursor Admin API URL: %w", err)+ }+ if parsed.User != nil {+ return "", errors.New("cursor Admin API URL must not carry credentials")+ }+ if parsed.Host == "" {+ return "", fmt.Errorf("invalid Cursor Admin API URL %q: no host", raw)+ }+ switch parsed.Scheme {+ case "https":+ case "http":+ if !isLoopbackHost(parsed.Hostname()) {+ return "", fmt.Errorf("cursor Admin API URL must use https (plain http is allowed only to a loopback address)")+ }+ default:+ return "", fmt.Errorf("cursor Admin API URL must use https, got %q", parsed.Scheme)+ }+ if parsed.RawQuery != "" || parsed.Fragment != "" {+ return "", errors.New("cursor Admin API URL must not carry a query or fragment")+ }+ return strings.TrimRight(parsed.String(), "/"), nil+}++func isLoopbackHost(host string) bool {+ if strings.EqualFold(host, "localhost") {+ return true+ }+ ip := net.ParseIP(host)+ return ip != nil && ip.IsLoopback()+}++// ListUsageEvents fetches one page. Page numbers start at 1.+func (c *Client) ListUsageEvents(ctx context.Context, q Query, page int) (Page, error) {+ if c == nil {+ return Page{}, errors.New("nil Cursor usage client")+ }+ if strings.TrimSpace(c.APIKey) == "" {+ return Page{}, ErrMissingAPIKey+ }+ base, err := ValidateBaseURL(c.BaseURL)+ if err != nil {+ return Page{}, err+ }+ if page <= 0 {+ page = 1+ }+ body, err := requestBody(q, page)+ if err != nil {+ return Page{}, err+ }++ var lastErr error+ for attempt := 1; attempt <= maxAttempts; attempt++ {+ result, retryAfter, err := c.do(ctx, base+UsageEventsPath, body)+ if err == nil {+ return result, nil+ }+ lastErr = err+ if retryAfter < 0 || attempt == maxAttempts {+ break+ }+ if err := c.sleep(ctx, retryAfter); err != nil {+ return Page{}, err+ }+ }+ return Page{}, lastErr+}++func requestBody(q Query, page int) ([]byte, error) {+ pageSize := q.PageSize+ if pageSize <= 0 {+ pageSize = defaultPageSize+ }+ if pageSize > maxPageSize {+ pageSize = maxPageSize+ }+ body := map[string]any{+ "startDate": millis(q.StartDate),+ "endDate": millis(q.EndDate),+ "page": page,+ "pageSize": pageSize,+ }+ if email := strings.TrimSpace(q.Email); email != "" {+ body["email"] = email+ }+ if raw := strings.TrimSpace(q.UserID); raw != "" {+ // The Admin API's user ids are numbers. Sending one as a string is rejected by the API+ // with a message that does not say why, so a non-numeric id is refused here instead.+ id, err := strconv.ParseInt(raw, 10, 64)+ if err != nil || id <= 0 {+ return nil, fmt.Errorf("invalid Cursor user ID %q: Cursor user IDs are numeric", raw)+ }+ body["userId"] = id+ }+ return json.Marshal(body)+}++// do sends one request. retryAfter is how long to wait before trying again, or negative when the+// failure is not worth retrying.+func (c *Client) do(ctx context.Context, endpoint string, body []byte) (Page, time.Duration, error) {+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(body))+ if err != nil {+ return Page{}, -1, fmt.Errorf("create Cursor usage request: %w", err)+ }+ req.SetBasicAuth(c.APIKey, "")+ req.Header.Set("Content-Type", "application/json")+ req.Header.Set("Accept", "application/json")+ if c.UserAgent != "" {+ req.Header.Set("User-Agent", c.UserAgent)+ }+ resp, err := c.httpClient().Do(req)+ if err != nil {+ if ctx.Err() != nil {+ return Page{}, -1, ctx.Err()+ }+ // A transport error carries the URL, never the header, so it is safe to wrap.+ return Page{}, time.Second, fmt.Errorf("call Cursor Admin API: %w", err)+ }+ defer resp.Body.Close()++ if resp.StatusCode < 200 || resp.StatusCode > 299 {+ _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 64<<10))+ statusErr := &StatusError{StatusCode: resp.StatusCode, Status: resp.Status}+ if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500 {+ return Page{}, retryDelay(resp.Header.Get("Retry-After")), statusErr+ }+ return Page{}, -1, statusErr+ }++ data, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes+1))+ if err != nil {+ return Page{}, time.Second, fmt.Errorf("read Cursor usage response: %w", err)+ }+ if len(data) > maxResponseBytes {+ return Page{}, -1, fmt.Errorf("cursor usage response exceeds %d bytes", maxResponseBytes)+ }+ page, err := DecodePage(data)+ if err != nil {+ return Page{}, -1, err+ }+ return page, 0, nil+}++func retryDelay(header string) time.Duration {+ header = strings.TrimSpace(header)+ if header == "" {+ return 2 * time.Second+ }+ if seconds, err := strconv.Atoi(header); err == nil && seconds >= 0 {+ wait := time.Duration(seconds) * time.Second+ if wait > maxRetryWait {+ wait = maxRetryWait+ }+ return wait+ }+ if at, err := http.ParseTime(header); err == nil {+ wait := time.Until(at)+ if wait < 0 {+ wait = 0+ }+ if wait > maxRetryWait {+ wait = maxRetryWait+ }+ return wait+ }+ return 2 * time.Second+}++func (c *Client) httpClient() *http.Client {+ if c.HTTPClient != nil {+ return c.HTTPClient+ }+ return &http.Client{Timeout: 30 * time.Second}+}++func (c *Client) sleep(ctx context.Context, d time.Duration) error {+ if c.Sleep != nil {+ return c.Sleep(ctx, d)+ }+ if d <= 0 {+ return ctx.Err()+ }+ timer := time.NewTimer(d)+ defer timer.Stop()+ select {+ case <-ctx.Done():+ return ctx.Err()+ case <-timer.C:+ return nil+ }+}++// FetchAll pages through every event in the query's window.+func (c *Client) FetchAll(ctx context.Context, q Query) ([]UsageEvent, error) {+ pageSize := q.PageSize+ if pageSize <= 0 {+ pageSize = defaultPageSize+ }+ if pageSize > maxPageSize {+ pageSize = maxPageSize+ }+ q.PageSize = pageSize++ var out []UsageEvent+ for page := 1; page <= maxPages; page++ {+ resp, err := c.ListUsageEvents(ctx, q, page)+ if err != nil {+ return out, err+ }+ out = append(out, resp.Events...)+ if len(resp.Events) == 0 {+ return out, nil+ }+ // The response's own answer wins when it gives one. The fallbacks matter for responses+ // that send no pagination block: without them a host that ignores page numbers would be+ // asked for the same page until maxPages.+ if resp.HasNextPage != nil {+ if !*resp.HasNextPage {+ return out, nil+ }+ continue+ }+ if resp.TotalCount > 0 && page*pageSize >= resp.TotalCount {+ return out, nil+ }+ if len(resp.Events) < pageSize {+ return out, nil+ }+ }+ return out, fmt.Errorf("cursor usage paging did not finish after %d pages", maxPages)+}++func millis(t time.Time) int64 {+ if t.IsZero() {+ return 0+ }+ return t.UTC().UnixMilli()+}++// --- response decoding ---++type envelope struct {+ TotalCount *flexInt `json:"totalUsageEventsCount"`+ Pagination *pagination `json:"pagination"`+ Display []rawUsageEvent `json:"usageEventsDisplay"`+ Events []rawUsageEvent `json:"usageEvents"`+}++type pagination struct {+ HasNextPage *bool `json:"hasNextPage"`+}++type rawUsageEvent struct {+ Timestamp json.RawMessage `json:"timestamp"`+ Model string `json:"model"`+ Kind string `json:"kind"`+ KindLabel string `json:"kindLabel"`+ MaxMode bool `json:"maxMode"`+ TokenBased bool `json:"isTokenBasedCall"`+ TokenUsage *rawTokenUsage `json:"tokenUsage"`+ ChargedCents *flexFloat `json:"chargedCents"`+ CursorTokenFee *flexFloat `json:"cursorTokenFee"`+ RequestsCosts *flexFloat `json:"requestsCosts"`+ Chargeable *bool `json:"isChargeable"`+ Headless bool `json:"isHeadless"`+ UserID json.RawMessage `json:"userId"`+ UserEmail string `json:"userEmail"`+}++type rawTokenUsage struct {+ InputTokens flexInt `json:"inputTokens"`+ OutputTokens flexInt `json:"outputTokens"`+ CacheWriteTokens flexInt `json:"cacheWriteTokens"`+ CacheReadTokens flexInt `json:"cacheReadTokens"`+ TotalCents *flexFloat `json:"totalCents"`+}++// DecodePage parses one response body.+func DecodePage(data []byte) (Page, error) {+ var env envelope+ if err := json.Unmarshal(data, &env); err != nil {+ return Page{}, fmt.Errorf("decode Cursor usage response: %w", err)+ }+ raw := env.Display+ if len(raw) == 0 {+ raw = env.Events+ }+ page := Page{Events: make([]UsageEvent, 0, len(raw))}+ if env.TotalCount != nil {+ page.TotalCount = int(*env.TotalCount)+ }+ if env.Pagination != nil {+ page.HasNextPage = env.Pagination.HasNextPage+ }+ for i, item := range raw {+ ev, err := parseEvent(item)+ if err != nil {+ return Page{}, fmt.Errorf("cursor usage event %d: %w", i, err)+ }+ page.Events = append(page.Events, ev)+ }+ return page, nil+}++func parseEvent(raw rawUsageEvent) (UsageEvent, error) {+ ts, err := parseTimestamp(raw.Timestamp)+ if err != nil {+ return UsageEvent{}, err+ }+ ev := UsageEvent{+ Timestamp: ts,+ Model: strings.TrimSpace(raw.Model),+ Kind: strings.TrimSpace(firstNonEmpty(raw.Kind, raw.KindLabel)),+ MaxMode: raw.MaxMode,+ TokenBased: raw.TokenBased,+ Chargeable: raw.Chargeable,+ Headless: raw.Headless,+ UserID: scalarString(raw.UserID),+ UserEmail: strings.TrimSpace(raw.UserEmail),+ }+ if raw.TokenUsage != nil {+ for name, n := range map[string]flexInt{+ "inputTokens": raw.TokenUsage.InputTokens,+ "outputTokens": raw.TokenUsage.OutputTokens,+ "cacheWriteTokens": raw.TokenUsage.CacheWriteTokens,+ "cacheReadTokens": raw.TokenUsage.CacheReadTokens,+ } {+ if n < 0 {+ return UsageEvent{}, fmt.Errorf("negative %s %d", name, n)+ }+ }+ ev.TokenUsage = TokenUsage{+ InputTokens: int64(raw.TokenUsage.InputTokens),+ OutputTokens: int64(raw.TokenUsage.OutputTokens),+ CacheWriteTokens: int64(raw.TokenUsage.CacheWriteTokens),+ CacheReadTokens: int64(raw.TokenUsage.CacheReadTokens),+ }+ if ev.TokenUsage.TotalCents, err = cents("tokenUsage.totalCents", raw.TokenUsage.TotalCents); err != nil {+ return UsageEvent{}, err+ }+ }+ if ev.ChargedCents, err = cents("chargedCents", raw.ChargedCents); err != nil {+ return UsageEvent{}, err+ }+ if ev.CursorTokenFeeCents, err = cents("cursorTokenFee", raw.CursorTokenFee); err != nil {+ return UsageEvent{}, err+ }+ if ev.RequestsCosts, err = cents("requestsCosts", raw.RequestsCosts); err != nil {+ return UsageEvent{}, err+ }+ return ev, nil+}++// cents validates an amount. A negative or non-finite amount is an error rather than a zero: a+// refund or a garbled number silently summed into a cost report is worse than a failed sync.+func cents(name string, value *flexFloat) (*float64, error) {+ if value == nil {+ return nil, nil+ }+ f := float64(*value)+ if math.IsNaN(f) || math.IsInf(f, 0) {+ return nil, fmt.Errorf("non-finite %s", name)+ }+ if f < 0 {+ return nil, fmt.Errorf("negative %s %v", name, f)+ }+ return &f, nil+}++func parseTimestamp(raw json.RawMessage) (time.Time, error) {+ value := scalarString(raw)+ if value == "" {+ return time.Time{}, errors.New("missing timestamp")+ }+ if ms, err := strconv.ParseInt(value, 10, 64); err == nil {+ if ms <= 0 {+ return time.Time{}, fmt.Errorf("invalid timestamp %q", value)+ }+ return time.UnixMilli(ms).UTC(), nil+ }+ if t, err := time.Parse(time.RFC3339Nano, value); err == nil {+ return t.UTC(), nil+ }+ return time.Time{}, fmt.Errorf("invalid timestamp %q", value)+}++// scalarString renders a JSON string or number as a string, and anything else as empty.+func scalarString(raw json.RawMessage) string {+ raw = bytes.TrimSpace(raw)+ if len(raw) == 0 || bytes.Equal(raw, []byte("null")) {+ return ""+ }+ if raw[0] == '"' {+ var s string+ if err := json.Unmarshal(raw, &s); err != nil {+ return ""+ }+ return strings.TrimSpace(s)+ }+ var n json.Number+ if err := json.Unmarshal(raw, &n); err != nil {+ return ""+ }+ return n.String()+}++// flexInt decodes a count sent as a JSON number or a numeric string. null is zero.+type flexInt int64++func (f *flexInt) UnmarshalJSON(data []byte) error {+ value := scalarString(data)+ if value == "" {+ *f = 0+ return nil+ }+ n, err := strconv.ParseInt(value, 10, 64)+ if err != nil {+ // Some responses write counts as floats ("12.0"). Accept them when they are whole.+ parsed, ferr := strconv.ParseFloat(value, 64)+ if ferr != nil || parsed != math.Trunc(parsed) || math.Abs(parsed) > 1<<53 {+ return fmt.Errorf("invalid token count %q", value)+ }+ n = int64(parsed)+ }+ *f = flexInt(n)+ return nil+}++// flexFloat decodes an amount sent as a JSON number or a numeric string.+type flexFloat float64++func (f *flexFloat) UnmarshalJSON(data []byte) error {+ value := scalarString(data)+ if value == "" {+ return fmt.Errorf("invalid amount %s", string(data))+ }+ parsed, err := strconv.ParseFloat(value, 64)+ if err != nil {+ return fmt.Errorf("invalid amount %q", value)+ }+ *f = flexFloat(parsed)+ return nil+}++func firstNonEmpty(values ...string) string {+ for _, v := range values {+ if strings.TrimSpace(v) != "" {+ return v+ }+ }+ return ""+}diff --git a/cli/beacon/internal/cursorusage/client_test.go b/cli/beacon/internal/cursorusage/client_test.gonew file mode 100644index 00000000..97490e47--- /dev/null+++ b/cli/beacon/internal/cursorusage/client_test.go@@ -0,0 +1,478 @@+package cursorusage++import (+ "context"+ "encoding/json"+ "errors"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "strings"+ "sync/atomic"+ "testing"+ "time"+)++func readFixture(t *testing.T) []byte {+ t.Helper()+ data, err := os.ReadFile(filepath.Join("testdata", "filtered_usage_events.json"))+ if err != nil {+ t.Fatal(err)+ }+ return data+}++func testClient(url string) *Client {+ c := NewClient("key_test_secret")+ c.BaseURL = url+ c.Sleep = func(context.Context, time.Duration) error { return nil }+ return c+}++func TestDecodePageReadsEveryField(t *testing.T) {+ page, err := DecodePage(readFixture(t))+ if err != nil {+ t.Fatal(err)+ }+ if page.TotalCount != 3 || page.HasNextPage == nil || *page.HasNextPage {+ t.Fatalf("pagination = %d %v", page.TotalCount, page.HasNextPage)+ }+ if len(page.Events) != 3 {+ t.Fatalf("events = %d", len(page.Events))+ }++ first := page.Events[0]+ if !first.Timestamp.Equal(time.UnixMilli(1750979225854)) {+ t.Errorf("timestamp = %v", first.Timestamp)+ }+ if first.Model != "claude-4-opus" || first.Kind != "Usage-based" || !first.MaxMode || !first.TokenBased {+ t.Errorf("identity = %+v", first)+ }+ want := TokenUsage{InputTokens: 126, OutputTokens: 450, CacheWriteTokens: 6112, CacheReadTokens: 11964}+ got := first.TokenUsage+ got.TotalCents = nil+ if got != want {+ t.Errorf("tokens = %+v, want %+v", got, want)+ }+ if first.TokenUsage.TotalCents == nil || *first.TokenUsage.TotalCents != 20.18232 {+ t.Errorf("totalCents = %v", first.TokenUsage.TotalCents)+ }+ if first.ChargedCents == nil || *first.ChargedCents != 20.18232 {+ t.Errorf("chargedCents = %v", first.ChargedCents)+ }+ if first.CursorTokenFeeCents == nil || *first.CursorTokenFeeCents != 0.5 {+ t.Errorf("cursorTokenFee = %v", first.CursorTokenFeeCents)+ }+ if first.RequestsCosts == nil || *first.RequestsCosts != 5 {+ t.Errorf("requestsCosts = %v", first.RequestsCosts)+ }+ if first.Chargeable == nil || !*first.Chargeable || first.Headless {+ t.Errorf("flags = %v %v", first.Chargeable, first.Headless)+ }+ // userId arrives as a number on one event and a string on the next; both read the same.+ if first.UserID != "152683922" || page.Events[1].UserID != "152683922" {+ t.Errorf("user ids = %q %q", first.UserID, page.Events[1].UserID)+ }++ second := page.Events[1]+ if second.TokenUsage.InputTokens != 42 || !second.Headless {+ t.Errorf("second = %+v", second)+ }+ if second.ChargedCents == nil || *second.ChargedCents != 0 {+ t.Errorf("an explicit zero charge must survive as zero, got %v", second.ChargedCents)+ }++ third := page.Events[2]+ if !third.Timestamp.Equal(time.Date(2025, 6, 26, 23, 5, 0, 0, time.UTC)) {+ t.Errorf("RFC 3339 timestamp = %v", third.Timestamp)+ }+ if third.Kind != "Included in Pro" {+ t.Errorf("kindLabel fallback = %q", third.Kind)+ }+ if third.ChargedCents != nil || third.TokenUsage != (TokenUsage{}) {+ t.Errorf("absent amounts must stay absent: %+v", third)+ }+}++func TestDecodePageAcceptsLegacyEnvelopeKey(t *testing.T) {+ page, err := DecodePage([]byte(`{"totalUsageEventsCount":"1","usageEvents":[{"timestamp":1748700000000,"model":"m","tokenUsage":{"inputTokens":1.0,"outputTokens":null}}]}`))+ if err != nil {+ t.Fatal(err)+ }+ if page.TotalCount != 1 || len(page.Events) != 1 || page.Events[0].TokenUsage.InputTokens != 1 {+ t.Fatalf("page = %+v", page)+ }+ if page.HasNextPage != nil {+ t.Fatalf("no pagination block must leave HasNextPage unset")+ }+}++func TestDecodePageRejectsBadValues(t *testing.T) {+ cases := map[string]string{+ "negative charge": `{"usageEventsDisplay":[{"timestamp":"1","model":"m","chargedCents":-1}]}`,+ "negative tokens": `{"usageEventsDisplay":[{"timestamp":"1","model":"m","tokenUsage":{"inputTokens":-5}}]}`,+ "fractional tokens": `{"usageEventsDisplay":[{"timestamp":"1","model":"m","tokenUsage":{"inputTokens":1.5}}]}`,+ "missing timestamp": `{"usageEventsDisplay":[{"model":"m"}]}`,+ "zero timestamp": `{"usageEventsDisplay":[{"timestamp":"0","model":"m"}]}`,+ "bad timestamp": `{"usageEventsDisplay":[{"timestamp":"yesterday","model":"m"}]}`,+ "string amount": `{"usageEventsDisplay":[{"timestamp":"1","model":"m","chargedCents":"lots"}]}`,+ "not json": `<html>`,+ }+ for name, body := range cases {+ t.Run(name, func(t *testing.T) {+ if _, err := DecodePage([]byte(body)); err == nil {+ t.Fatalf("expected an error for %s", body)+ }+ })+ }+}++func TestListUsageEventsSendsTheAdminRequest(t *testing.T) {+ type requestBody struct {+ StartDate int64 `json:"startDate"`+ EndDate int64 `json:"endDate"`+ Page int `json:"page"`+ PageSize int `json:"pageSize"`+ Email string `json:"email"`+ UserID int64 `json:"userId"`+ }+ fixture := readFixture(t)+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Method != http.MethodPost || r.URL.Path != UsageEventsPath {+ t.Errorf("request = %s %s", r.Method, r.URL.Path)+ }+ user, pass, ok := r.BasicAuth()+ if !ok || user != "key_test_secret" || pass != "" {+ t.Errorf("basic auth = %q %q %v", user, pass, ok)+ }+ if got := r.Header.Get("Content-Type"); got != "application/json" {+ t.Errorf("content type = %q", got)+ }+ if got := r.Header.Get("User-Agent"); got != "beacon-test" {+ t.Errorf("user agent = %q", got)+ }+ var body requestBody+ if err := json.NewDecoder(r.Body).Decode(&body); err != nil {+ t.Error(err)+ }+ want := requestBody{StartDate: 1777593600000, EndDate: 1777766399000, Page: 2, PageSize: 50, Email: "[email protected]", UserID: 152683922}+ if body != want {+ t.Errorf("body = %+v, want %+v", body, want)+ }+ _, _ = w.Write(fixture)+ }))+ t.Cleanup(srv.Close)++ c := testClient(srv.URL)+ c.UserAgent = "beacon-test"+ page, err := c.ListUsageEvents(t.Context(), Query{+ StartDate: time.Date(2026, 5, 1, 0, 0, 0, 0, time.UTC),+ EndDate: time.Date(2026, 5, 2, 23, 59, 59, 0, time.UTC),+ Email: " [email protected] ",+ UserID: "152683922",+ PageSize: 50,+ }, 2)+ if err != nil {+ t.Fatal(err)+ }+ if len(page.Events) != 3 {+ t.Fatalf("events = %d", len(page.Events))+ }+}++func TestListUsageEventsOmitsUnsetFilters(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ var body map[string]any+ _ = json.NewDecoder(r.Body).Decode(&body)+ if _, ok := body["email"]; ok {+ t.Errorf("email sent when unset: %v", body)+ }+ if _, ok := body["userId"]; ok {+ t.Errorf("userId sent when unset: %v", body)+ }+ if body["pageSize"] != float64(100) {+ t.Errorf("default page size = %v", body["pageSize"])+ }+ _, _ = w.Write([]byte(`{"usageEventsDisplay":[]}`))+ }))+ t.Cleanup(srv.Close)+ if _, err := testClient(srv.URL).ListUsageEvents(t.Context(), Query{}, 1); err != nil {+ t.Fatal(err)+ }+}++func TestListUsageEventsCapsPageSize(t *testing.T) {+ body, err := requestBody(Query{PageSize: 50000}, 1)+ if err != nil {+ t.Fatal(err)+ }+ if !strings.Contains(string(body), `"pageSize":1000`) {+ t.Fatalf("body = %s", body)+ }+}++func TestListUsageEventsRejectsNonNumericUserID(t *testing.T) {+ _, err := testClient("https://example.test").ListUsageEvents(t.Context(), Query{UserID: "user_123"}, 1)+ if err == nil || !strings.Contains(err.Error(), `invalid Cursor user ID "user_123"`) {+ t.Fatalf("err = %v", err)+ }+}++func TestListUsageEventsRequiresAKey(t *testing.T) {+ c := testClient("https://example.test")+ c.APIKey = " "+ if _, err := c.ListUsageEvents(t.Context(), Query{}, 1); !errors.Is(err, ErrMissingAPIKey) {+ t.Fatalf("err = %v", err)+ }+}++func TestFetchAllFollowsHasNextPage(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ var body struct {+ Page int `json:"page"`+ }+ _ = json.NewDecoder(r.Body).Decode(&body)+ calls.Add(1)+ next := body.Page < 3+ // Full pages with hasNextPage true, then a final page with hasNextPage false. The total+ // count is deliberately wrong so the test proves hasNextPage, not the count, decides.+ resp := map[string]any{+ "totalUsageEventsCount": 1,+ "pagination": map[string]any{"hasNextPage": next},+ "usageEventsDisplay": []map[string]any{+ {"timestamp": time.UnixMilli(int64(1000 + body.Page)).UnixMilli(), "model": "m"},+ },+ }+ _ = json.NewEncoder(w).Encode(resp)+ }))+ t.Cleanup(srv.Close)++ events, err := testClient(srv.URL).FetchAll(t.Context(), Query{PageSize: 1})+ if err != nil {+ t.Fatal(err)+ }+ if len(events) != 3 || calls.Load() != 3 {+ t.Fatalf("events = %d, calls = %d", len(events), calls.Load())+ }+}++func TestFetchAllWithoutPaginationUsesCountAndShortPage(t *testing.T) {+ fixture := readFixture(t)+ var env map[string]json.RawMessage+ _ = json.Unmarshal(fixture, &env)+ var all []json.RawMessage+ _ = json.Unmarshal(env["usageEventsDisplay"], &all)++ t.Run("total count", func(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ var body struct {+ Page int `json:"page"`+ }+ _ = json.NewDecoder(r.Body).Decode(&body)+ calls.Add(1)+ _ = json.NewEncoder(w).Encode(map[string]any{+ "totalUsageEventsCount": 3,+ "usageEventsDisplay": all[body.Page-1 : body.Page],+ })+ }))+ t.Cleanup(srv.Close)+ events, err := testClient(srv.URL).FetchAll(t.Context(), Query{PageSize: 1})+ if err != nil {+ t.Fatal(err)+ }+ if len(events) != 3 || calls.Load() != 3 {+ t.Fatalf("events = %d calls = %d", len(events), calls.Load())+ }+ })++ t.Run("host ignores page numbers", func(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ _ = json.NewEncoder(w).Encode(map[string]any{"usageEventsDisplay": all})+ }))+ t.Cleanup(srv.Close)+ events, err := testClient(srv.URL).FetchAll(t.Context(), Query{PageSize: 10})+ if err != nil {+ t.Fatal(err)+ }+ if len(events) != 3 || calls.Load() != 1 {+ t.Fatalf("a short page must end paging: events = %d calls = %d", len(events), calls.Load())+ }+ })+}++func TestRetriesRateLimitAndServerErrors(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ switch calls.Add(1) {+ case 1:+ w.Header().Set("Retry-After", "7")+ w.WriteHeader(http.StatusTooManyRequests)+ case 2:+ w.WriteHeader(http.StatusBadGateway)+ default:+ _, _ = w.Write([]byte(`{"usageEventsDisplay":[]}`))+ }+ }))+ t.Cleanup(srv.Close)++ var waits []time.Duration+ c := testClient(srv.URL)+ c.Sleep = func(_ context.Context, d time.Duration) error {+ waits = append(waits, d)+ return nil+ }+ if _, err := c.ListUsageEvents(t.Context(), Query{}, 1); err != nil {+ t.Fatal(err)+ }+ if calls.Load() != 3 {+ t.Fatalf("calls = %d", calls.Load())+ }+ if len(waits) != 2 || waits[0] != 7*time.Second {+ t.Fatalf("waits = %v", waits)+ }+}++func TestGivesUpAfterMaxAttempts(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ w.WriteHeader(http.StatusServiceUnavailable)+ }))+ t.Cleanup(srv.Close)+ _, err := testClient(srv.URL).ListUsageEvents(t.Context(), Query{}, 1)+ var statusErr *StatusError+ if !errors.As(err, &statusErr) || statusErr.StatusCode != http.StatusServiceUnavailable {+ t.Fatalf("err = %v", err)+ }+ if calls.Load() != maxAttempts {+ t.Fatalf("calls = %d", calls.Load())+ }+}++func TestAuthFailureIsNotRetriedAndNeverEchoesTheKeyOrBody(t *testing.T) {+ var calls atomic.Int32+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ calls.Add(1)+ w.WriteHeader(http.StatusUnauthorized)+ _, _ = w.Write([]byte(`{"error":"bad key key_test_secret"}`))+ }))+ t.Cleanup(srv.Close)+ _, err := testClient(srv.URL).ListUsageEvents(t.Context(), Query{}, 1)+ if err == nil {+ t.Fatal("expected an error")+ }+ if calls.Load() != 1 {+ t.Fatalf("a 401 must not be retried, calls = %d", calls.Load())+ }+ if strings.Contains(err.Error(), "key_test_secret") {+ t.Fatalf("error leaks the key: %v", err)+ }+ if !strings.Contains(err.Error(), "Admin API key") {+ t.Fatalf("error should say what to check: %v", err)+ }+}++func TestRetryDelay(t *testing.T) {+ cases := map[string]time.Duration{+ "": 2 * time.Second,+ "3": 3 * time.Second,+ "9999": maxRetryWait,+ "later": 2 * time.Second,+ }+ for header, want := range cases {+ if got := retryDelay(header); got != want {+ t.Errorf("retryDelay(%q) = %v, want %v", header, got, want)+ }+ }+ if got := retryDelay(time.Now().Add(-time.Hour).UTC().Format(http.TimeFormat)); got != 0 {+ t.Errorf("past HTTP date = %v", got)+ }+}++func TestOversizedResponseIsRefused(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ _, _ = w.Write([]byte(`{"usageEventsDisplay":[],"pad":"`))+ chunk := []byte(strings.Repeat("x", 1<<20))+ for i := 0; i < (maxResponseBytes>>20)+1; i++ {+ if _, err := w.Write(chunk); err != nil {+ return+ }+ }+ _, _ = w.Write([]byte(`"}`))+ }))+ t.Cleanup(srv.Close)+ _, err := testClient(srv.URL).ListUsageEvents(t.Context(), Query{}, 1)+ if err == nil || !strings.Contains(err.Error(), "exceeds") {+ t.Fatalf("err = %v", err)+ }+}++func TestContextCancellationStopsRetries(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.WriteHeader(http.StatusTooManyRequests)+ }))+ t.Cleanup(srv.Close)+ ctx, cancel := context.WithCancel(t.Context())+ c := testClient(srv.URL)+ c.Sleep = func(ctx context.Context, _ time.Duration) error {+ cancel()+ return ctx.Err()+ }+ if _, err := c.ListUsageEvents(ctx, Query{}, 1); !errors.Is(err, context.Canceled) {+ t.Fatalf("err = %v", err)+ }+}++func TestValidateBaseURL(t *testing.T) {+ ok := map[string]string{+ "": DefaultBaseURL,+ "https://api.cursor.com/": "https://api.cursor.com",+ "http://127.0.0.1:8080": "http://127.0.0.1:8080",+ "http://localhost:9": "http://localhost:9",+ "http://[::1]:9": "http://[::1]:9",+ "https://proxy.example/api": "https://proxy.example/api",+ }+ for in, want := range ok {+ got, err := ValidateBaseURL(in)+ if err != nil || got != want {+ t.Errorf("ValidateBaseURL(%q) = %q, %v; want %q", in, got, err, want)+ }+ }+ for _, bad := range []string{+ "http://api.cursor.com",+ "ftp://api.cursor.com",+ "https://user:[email protected]",+ "https://api.cursor.com?x=1",+ "api.cursor.com",+ "https://",+ } {+ if _, err := ValidateBaseURL(bad); err == nil {+ t.Errorf("ValidateBaseURL(%q) accepted", bad)+ }+ }+}++func TestPlainHTTPToARemoteHostNeverSendsTheKey(t *testing.T) {+ var reached atomic.Bool+ transport := roundTripFunc(func(r *http.Request) (*http.Response, error) {+ reached.Store(true)+ return nil, errors.New("must not be called")+ })+ c := testClient("http://api.cursor.com")+ c.HTTPClient = &http.Client{Transport: transport}+ if _, err := c.ListUsageEvents(t.Context(), Query{}, 1); err == nil {+ t.Fatal("expected refusal")+ }+ if reached.Load() {+ t.Fatal("request was sent over plain http")+ }+}++type roundTripFunc func(*http.Request) (*http.Response, error)++func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }diff --git a/cli/beacon/internal/cursorusage/testdata/filtered_usage_events.json b/cli/beacon/internal/cursorusage/testdata/filtered_usage_events.jsonnew file mode 100644index 00000000..5b8aa662--- /dev/null+++ b/cli/beacon/internal/cursorusage/testdata/filtered_usage_events.json@@ -0,0 +1,59 @@+{+ "totalUsageEventsCount": 3,+ "pagination": {+ "numPages": 1,+ "currentPage": 1,+ "pageSize": 100,+ "hasNextPage": false,+ "hasPreviousPage": false+ },+ "usageEventsDisplay": [+ {+ "timestamp": "1750979225854",+ "model": "claude-4-opus",+ "kind": "Usage-based",+ "maxMode": true,+ "requestsCosts": 5,+ "isTokenBasedCall": true,+ "tokenUsage": {+ "inputTokens": 126,+ "outputTokens": 450,+ "cacheWriteTokens": 6112,+ "cacheReadTokens": 11964,+ "totalCents": 20.18232+ },+ "isChargeable": true,+ "chargedCents": 20.18232,+ "cursorTokenFee": 0.5,+ "isHeadless": false,+ "userId": 152683922,+ "userEmail": "[email protected]"+ },+ {+ "timestamp": "1750979173824",+ "model": "gpt-5.5-high",+ "kind": "USAGE_EVENT_KIND_INCLUDED_IN_BUSINESS",+ "maxMode": false,+ "isTokenBasedCall": true,+ "tokenUsage": {+ "inputTokens": "42",+ "outputTokens": 18,+ "cacheWriteTokens": 4,+ "cacheReadTokens": 8,+ "totalCents": 0.11+ },+ "isChargeable": false,+ "chargedCents": 0,+ "isHeadless": true,+ "userId": "152683922",+ "userEmail": "[email protected]"+ },+ {+ "timestamp": "2025-06-26T23:05:00Z",+ "model": "auto",+ "kindLabel": "Included in Pro",+ "isTokenBasedCall": false,+ "userEmail": "[email protected]"+ }+ ]+}