Skip to content

Add stripe analytics query command#1735

Open
kamenrider-cyber wants to merge 3 commits into
masterfrom
REVINTEL-885
Open

Add stripe analytics query command#1735
kamenrider-cyber wants to merge 3 commits into
masterfrom
REVINTEL-885

Conversation

@kamenrider-cyber

@kamenrider-cyber kamenrider-cyber commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Reviewers

r?
cc @stripe/developer-products

Summary

Add stripe data metrics run, a new CLI command that wraps POST /v2/data/analytics/metric_query (a Private Preview API). The command sends the preview Stripe-Version header automatically and supports querying one or more metrics by namespace.metric name (e.g. revenue.mrr) or ID (e.g. metric_test_...), along with time range, granularity, currency, timezone, filters, group-by, and limit.

The command (and its data / data metrics parents) is hidden while the API is in Private Preview. Parameters are forwarded to the API for validation rather than duplicated client-side, so the CLI won't drift from the API's rules (metric namespaces, time ranges, group-by/filter cardinality, limit bounds, etc.).

This is implemented as a bespoke command (not OpenAPI-generated) because the endpoint's metrics array-of-objects and dynamic filters map aren't representable with the current resource-command codegen.

Test plan

  • go test ./pkg/cmd/ -run 'MetricRef|BuildRequestBody|ParseMetricFilters|DataMetricsRun|NewDataCmd|NewDataMetricsRun'
  • Manual E2E in test mode against the live API

Baseline (equivalent curl request):

curl -X POST https://api.stripe.com/v2/data/analytics/metric_query \
  -H "Authorization: Bearer $STRIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Stripe-Version: unsafe-development" \
  --json '{
    "metrics": [{"name": "revenue.mrr"}],
    "starts_at": "2026-06-19T00:00:00Z",
    "ends_at": "2026-06-26T00:00:00Z",
    "granularity": "day",
    "currency": "usd"
  }'
./bin/stripe data metrics run \
  --metric revenue.mrr \
  --starts-at 2026-06-19T00:00:00Z \
  --ends-at 2026-06-26T00:00:00Z \
  --granularity day \
  --currency usd
Screenshot 2026-07-08 at 4 08 06 PM
./bin/stripe data metrics run \
  --metric metric_test_61UYCfgFqfg8KWGdo5 \
  --starts-at 2026-06-19T00:00:00Z \
  --ends-at 2026-06-26T00:00:00Z \
  --granularity day \
  --currency usd
Screenshot 2026-07-08 at 4 08 39 PM

@kamenrider-cyber kamenrider-cyber requested a review from a team as a code owner July 2, 2026 21:46

@benanthony-stripe benanthony-stripe left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great first pass, awesome work! A few small comments mostly about stuff you couldn't have possibly known.

One other small request, could you add some snippets of the output of this command in your PR description? I saw you have the actual CLI commands but would be really helpful to see the output too!

Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/analytics.go Outdated
Comment thread pkg/cmd/root.go Outdated

@billmei-stripe billmei-stripe left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting this together!

Comment thread pkg/cmd/data.go
Comment thread pkg/cmd/data.go
Comment thread pkg/cmd/data.go Outdated
Comment thread pkg/cmd/data.go Outdated
Comment thread pkg/cmd/data.go Outdated
Comment thread pkg/cmd/data.go
Comment thread pkg/cmd/data.go
Comment thread pkg/cmd/data.go
c.cmd.Flags().BoolVarP(&c.rb.DarkStyle, "dark-style", "", false, "Use a darker color scheme better suited for lighter command-lines")

c.cmd.Flags().StringVar(&c.rb.APIBaseURL, "api-base", stripe.DefaultAPIBaseURL, "Sets the API base URL")
c.cmd.Flags().MarkHidden("api-base") // #nosec G104

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this mean?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi,
--api-base overrides the API host (used for local/dev testing), and i think it is in listen and login=D

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant, what does #nosec G104 mean?

Comment thread pkg/cmd/data.go
Comment thread pkg/cmd/data_test.go
Comment thread pkg/cmd/data.go Outdated

@billmei-stripe billmei-stripe left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work!

Comment thread pkg/cmd/data.go

See the supported metrics at https://docs.stripe.com/data/analytics/supported-metrics
and the API reference at
https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create?api-version=preview`,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Comment thread pkg/cmd/data.go
c.cmd.Flags().BoolVarP(&c.rb.DarkStyle, "dark-style", "", false, "Use a darker color scheme better suited for lighter command-lines")

c.cmd.Flags().StringVar(&c.rb.APIBaseURL, "api-base", stripe.DefaultAPIBaseURL, "Sets the API base URL")
c.cmd.Flags().MarkHidden("api-base") // #nosec G104

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant, what does #nosec G104 mean?

Comment thread pkg/cmd/data.go
// the API so we don't duplicate logic that could drift out of sync.
if len(c.metrics) == 0 {
return fmt.Errorf("at least one --metric is required")
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants