From 11a3ed5ca9e8c69710384e95263c78f686b12c09 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 11:50:37 -0500 Subject: [PATCH 1/8] [TW-8105] Add nylas deliverability commands for send events, tracking events and send alerts Adds the 17 SendEvents, TrackingEvents and send alert routes to the CLI under `nylas deliverability {send-events,tracking-events,send-alerts}`, grouped the same way as the "Deliverability & Engagement" API reference section. Co-Authored-By: Claude Opus 5.5 --- cmd/nylas/main.go | 2 + docs/ARCHITECTURE.md | 1 + docs/COMMANDS.md | 22 ++ docs/DEVELOPMENT.md | 2 + docs/INDEX.md | 2 + docs/commands/deliverability.md | 111 ++++++++ .../adapters/nylas/deliverability_activity.go | 124 ++++++++ .../adapters/nylas/deliverability_alerts.go | 79 ++++++ .../adapters/nylas/deliverability_metrics.go | 74 +++++ .../adapters/nylas/deliverability_test.go | 266 ++++++++++++++++++ .../adapters/nylas/demo_deliverability.go | 155 ++++++++++ internal/adapters/nylas/mock_client.go | 19 ++ .../adapters/nylas/mock_deliverability.go | 126 +++++++++ internal/cli/deliverability/deliverability.go | 71 +++++ .../cli/deliverability/deliverability_test.go | 235 ++++++++++++++++ internal/cli/deliverability/helpers.go | 120 ++++++++ internal/cli/deliverability/metrics.go | 164 +++++++++++ internal/cli/deliverability/metrics_render.go | 134 +++++++++ internal/cli/deliverability/send_alerts.go | 204 ++++++++++++++ internal/cli/deliverability/send_events.go | 208 ++++++++++++++ .../cli/deliverability/tracking_events.go | 198 +++++++++++++ .../cli/integration/deliverability_test.go | 171 +++++++++++ internal/domain/deliverability_activity.go | 204 ++++++++++++++ internal/domain/deliverability_alerts.go | 31 ++ internal/domain/deliverability_metrics.go | 188 +++++++++++++ internal/ports/deliverability.go | 31 ++ internal/ports/nylas.go | 1 + 27 files changed, 2943 insertions(+) create mode 100644 docs/commands/deliverability.md create mode 100644 internal/adapters/nylas/deliverability_activity.go create mode 100644 internal/adapters/nylas/deliverability_alerts.go create mode 100644 internal/adapters/nylas/deliverability_metrics.go create mode 100644 internal/adapters/nylas/deliverability_test.go create mode 100644 internal/adapters/nylas/demo_deliverability.go create mode 100644 internal/adapters/nylas/mock_deliverability.go create mode 100644 internal/cli/deliverability/deliverability.go create mode 100644 internal/cli/deliverability/deliverability_test.go create mode 100644 internal/cli/deliverability/helpers.go create mode 100644 internal/cli/deliverability/metrics.go create mode 100644 internal/cli/deliverability/metrics_render.go create mode 100644 internal/cli/deliverability/send_alerts.go create mode 100644 internal/cli/deliverability/send_events.go create mode 100644 internal/cli/deliverability/tracking_events.go create mode 100644 internal/cli/integration/deliverability_test.go create mode 100644 internal/domain/deliverability_activity.go create mode 100644 internal/domain/deliverability_alerts.go create mode 100644 internal/domain/deliverability_metrics.go create mode 100644 internal/ports/deliverability.go diff --git a/cmd/nylas/main.go b/cmd/nylas/main.go index 246b74c..82ded7f 100644 --- a/cmd/nylas/main.go +++ b/cmd/nylas/main.go @@ -16,6 +16,7 @@ import ( "github.com/nylas/cli/internal/cli/config" "github.com/nylas/cli/internal/cli/contacts" "github.com/nylas/cli/internal/cli/dashboard" + "github.com/nylas/cli/internal/cli/deliverability" "github.com/nylas/cli/internal/cli/demo" "github.com/nylas/cli/internal/cli/email" "github.com/nylas/cli/internal/cli/mcp" @@ -49,6 +50,7 @@ func main() { rootCmd.AddCommand(calendar.NewCalendarCmd()) rootCmd.AddCommand(contacts.NewContactsCmd()) rootCmd.AddCommand(dashboard.NewDashboardCmd()) + rootCmd.AddCommand(deliverability.NewDeliverabilityCmd()) rootCmd.AddCommand(oauthcmd.NewOAuthCmd()) // The dashboard commands renew OAuth-backed sessions through `nylas oauth`. oauthcmd.WireDashboard() diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7768d6a..771e6f6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -37,6 +37,7 @@ internal/ auth/ # Authentication calendar/ # Calendar & events contacts/ # Contact management + deliverability/ # Send/tracking events, metrics, send alerts email/ # Email operations integration/ # CLI integration tests mcp/ # MCP server command diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 89781d4..79ff61d 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -523,6 +523,28 @@ nylas workflow delete --yes --- +## Deliverability + +```bash +nylas deliverability send-events list [--event-type bounced] [--start 24h] # Send activity +nylas deliverability send-events show # One send event +nylas deliverability send-events message # Per-recipient timeline +nylas deliverability send-events summary [--start YYYY-MM-DD --end YYYY-MM-DD] # Health, totals, rates +nylas deliverability send-events timeseries [--granularity day|week|month] +nylas deliverability send-events breakdown [--group-by recipient_domain] +nylas deliverability tracking-events list|show|message|summary|timeseries|breakdown +nylas deliverability send-alerts list +nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1 +nylas deliverability send-alerts update --threshold 3 +nylas deliverability send-alerts delete --yes +``` + +**Auth:** application-level (API key, no grant). **Time:** activity `--start/--end` take timestamps or look-backs (`24h`, `7d`); metrics take UTC dates `YYYY-MM-DD`. + +**Details:** `docs/commands/deliverability.md` + +--- + ## Folders & Threads ```bash diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 422115d..d1e500c 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -68,6 +68,8 @@ make test-integration **CRITICAL:** Integration tests create real resources. Always use `make ci-full` for automatic cleanup. +`internal/cli/integration/deliverability_test.go` needs only `NYLAS_API_KEY` (no grant). It reads send and tracking activity and metrics, and creates, updates and deletes one send alert rule. It skips the rule test when the application already has 20 rules. + ### OAuth authorization server tests `internal/cli/integration/oauth_test.go` drives a real dashboard-account diff --git a/docs/INDEX.md b/docs/INDEX.md index 66440e4..4a23b36 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -81,6 +81,7 @@ Quick navigation guide to find the right documentation for your needs. - **TUI** → [commands/tui.md](commands/tui.md) - **Workflows (OTP)** → [commands/workflows.md](commands/workflows.md) - **Templates** → [commands/templates.md](commands/templates.md) +- **Deliverability (send/tracking events, send alerts)** → [commands/deliverability.md](commands/deliverability.md) ### AI & MCP @@ -141,6 +142,7 @@ docs/ │ ├── audit.md # Audit logging & invoker tracking │ ├── tui.md # Terminal UI │ ├── templates.md # Email templates +│ ├── deliverability.md # Send/tracking events & send alerts │ └── workflows.md # OTP & automation │ ├── ai/ # AI configuration (8 files) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md new file mode 100644 index 0000000..9acf0bf --- /dev/null +++ b/docs/commands/deliverability.md @@ -0,0 +1,111 @@ +# Deliverability + +Use `nylas deliverability` to see what happened to the email your application sends. The commands follow the "Deliverability & Engagement" section of the Nylas API reference: + +| Command group | Data | API routes | +|---|---|---| +| `send-events` | Send activity and send metrics | `/v3/activity/send`, `/v3/metrics/send` | +| `tracking-events` | Opens, link clicks and engagement metrics | `/v3/activity/tracking`, `/v3/metrics/tracking` | +| `send-alerts` | Alert rules on send rates | `/v3/alerts/send` | + +All of these routes are application-level. They use your API key (`nylas auth config` or `NYLAS_API_KEY`) and do not take a grant. A grant access token gets `403 api.forbidden`. + +--- + +## Time windows + +The two kinds of command take different time formats: + +| Commands | `--start` / `--end` | Default | Limit | +|---|---|---|---| +| `list` (activity) | Unix timestamp, `YYYY-MM-DD`, RFC3339, or a look-back such as `24h`, `7d`, `2w` | UTC midnight 6 days ago → now | 90 days. An older start is moved to 90 days ago. | +| `summary`, `timeseries`, `breakdown` (metrics) | UTC date, `YYYY-MM-DD`, both days included | `--end` = today, `--start` = 6 days before `--end` | 365 days | + +A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". + +--- + +## Send events + +```bash +# Activity feed, newest first +nylas deliverability send-events list +nylas deliverability send-events list --event-type bounced --event-type complaint --start 7d +nylas deliverability send-events list --recipient-domain gmail.com --bounce-class hard +nylas deliverability send-events list --message-id "" --json + +# One event, with the SMTP / bounce / complaint detail +nylas deliverability send-events show + +# Every recipient's timeline for one message +nylas deliverability send-events message + +# Metrics +nylas deliverability send-events summary +nylas deliverability send-events summary --start 2026-10-01 --end 2026-10-31 --sending-domain mail.example.com +nylas deliverability send-events timeseries --granularity week --start 2026-08-01 +nylas deliverability send-events breakdown --group-by recipient_domain --sort bounce_rate:desc +``` + +**`list` filters:** `--event-type` (repeatable: `accepted`, `delivered`, `bounced`, `complaint`, `rejected`), `--bounce-class` (`hard`, `soft`, `undetermined`), `--sending-domain`, `--from`, `--grant-id`, `--recipient`, `--recipient-domain`, `--message-id`, `--thread-id`, `--order asc|desc`. + +**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query. + +**`summary`:** health is always graded on the **last 7 days**, whatever window you ask for. The states are `healthy`, `at_risk`, `critical` and `insufficient_data` (fewer than 100 sends). Totals and rate tiles use your window and compare it with the period of the same length just before it. When the state is `at_risk` or `critical`, `summary` also lists up to 3 findings. + +**`timeseries`:** `--granularity auto|day|week|month`. `auto` uses days up to 21 days, weeks up to 92 days, and months after that. + +**`breakdown`:** `--group-by sending_domain|agent_account|recipient_domain`, `--sort :` (keys: `key`, `sent`, `delivery_rate`, `bounce_rate`, `complaint_rate`), `--limit` 1–100 (default 25). Rows after the limit are added together into one `(others)` row. A `recipient_domain` breakdown only covers the last 90 days. + +**Rates:** a rate shows `—` when its denominator is 0. That means "no data", not 0%. The bounce rate counts hard bounces only. + +--- + +## Tracking events + +```bash +nylas deliverability tracking-events list --event-type link_clicked --start 7d +nylas deliverability tracking-events list --label welcome-campaign --json +nylas deliverability tracking-events show +nylas deliverability tracking-events message + +nylas deliverability tracking-events summary --start 2026-10-01 +nylas deliverability tracking-events timeseries --granularity day +nylas deliverability tracking-events breakdown --group-by agent_account --sort open_rate:desc +``` + +**`list` filters:** `--event-type` (repeatable: `opened`, `link_clicked`), `--sending-domain`, `--from`, `--grant-id`, `--message-id`, `--thread-id`, `--label`. + +**`message`:** shows open and click totals, clicks per link, and the newest 100 interactions. The totals count every interaction, not only the 100 shown. + +**Rates:** open rate = first opens ÷ messages sent with open tracking. Click rate = first clicks ÷ messages sent with link tracking. `breakdown` sort keys: `key`, `tracked_opens`, `tracked_links`, `open_rate`, `click_rate`. + +--- + +## Send alerts + +A send alert rule watches one send rate for each sending domain. When the rate crosses the threshold, Nylas sends the `alert.triggered` webhook to your application's webhook subscriptions. An application can have at most 20 rules. + +```bash +nylas deliverability send-alerts list +nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1 --min-volume 50 +nylas deliverability send-alerts create --metric delivery_rate --threshold 95 --window-hours 24 +nylas deliverability send-alerts show +nylas deliverability send-alerts update --threshold 3 +nylas deliverability send-alerts delete --yes +``` + +| Flag | Meaning | +|---|---| +| `--metric` | `bounce_rate`, `complaint_rate` or `delivery_rate` | +| `--threshold` | Percentage with at most 2 decimals. `bounce_rate` and `complaint_rate` fire **above** it (0 to <100). `delivery_rate` fires **below** it (>0 to 100). | +| `--window-hours` | Look-back window, 1–24 hours | +| `--min-volume` | Sends needed in the window before the rule can fire (default 0) | + +`create` needs `--metric`, `--threshold` and `--window-hours`. `update` sends only the flags you give and keeps every other field. + +--- + +## Output + +All commands support `--json`, `--format yaml` and `--quiet`. For `list`, the JSON output is the full API response (`data`, `next_cursor`, `request_id`), so a script can page through results. `--quiet` prints one ID per line. diff --git a/internal/adapters/nylas/deliverability_activity.go b/internal/adapters/nylas/deliverability_activity.go new file mode 100644 index 0000000..10ffb25 --- /dev/null +++ b/internal/adapters/nylas/deliverability_activity.go @@ -0,0 +1,124 @@ +package nylas + +import ( + "context" + "net/url" + "strconv" + + "github.com/nylas/cli/internal/domain" +) + +// ListSendEvents returns one page of GET /v3/activity/send. +func (c *HTTPClient) ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) { + if params == nil { + params = &domain.SendEventListParams{} + } + // event_type repeats as separate keys; the API rejects a comma-joined value. + queryURL := activityWindowQuery(params.Start, params.End, params.Order, params.Limit, params.PageToken). + AddSlice("event_type", params.EventTypes). + Add("bounce_class", params.BounceClass). + Add("sending_domain", params.SendingDomain). + Add("from", params.From). + Add("grant_id", params.GrantID). + Add("recipient", params.Recipient). + Add("recipient_domain", params.RecipientDomain). + Add("message_id", params.MessageID). + Add("thread_id", params.ThreadID). + BuildURL(c.baseURL + "/v3/activity/send") + + var result domain.SendEventListResponse + if err := c.doGet(ctx, queryURL, &result); err != nil { + return nil, err + } + return &result, nil +} + +// GetSendEvent returns one send event by its 64-hex ID. +func (c *HTTPClient) GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) { + if err := validateRequired("event ID", eventID); err != nil { + return nil, err + } + var result struct { + Data domain.SendEvent `json:"data"` + } + if err := c.doGet(ctx, c.baseURL+"/v3/activity/send/"+url.PathEscape(eventID), &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// GetSendMessageActivity returns every recipient's send timeline for one message. +func (c *HTTPClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { + if err := validateRequired("message ID", messageID); err != nil { + return nil, err + } + var result struct { + Data domain.SendMessageActivity `json:"data"` + } + if err := c.doGet(ctx, c.baseURL+"/v3/activity/send/messages/"+url.PathEscape(messageID), &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// ListTrackingEvents returns one page of GET /v3/activity/tracking. +func (c *HTTPClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { + if params == nil { + params = &domain.TrackingEventListParams{} + } + queryURL := activityWindowQuery(params.Start, params.End, params.Order, params.Limit, params.PageToken). + AddSlice("event_type", params.EventTypes). + Add("sending_domain", params.SendingDomain). + Add("from", params.From). + Add("grant_id", params.GrantID). + Add("message_id", params.MessageID). + Add("thread_id", params.ThreadID). + Add("label", params.Label). + BuildURL(c.baseURL + "/v3/activity/tracking") + + var result domain.TrackingEventListResponse + if err := c.doGet(ctx, queryURL, &result); err != nil { + return nil, err + } + return &result, nil +} + +// GetTrackingEvent returns one tracking event by its 64-hex ID. +func (c *HTTPClient) GetTrackingEvent(ctx context.Context, eventID string) (*domain.TrackingEvent, error) { + if err := validateRequired("event ID", eventID); err != nil { + return nil, err + } + var result struct { + Data domain.TrackingEvent `json:"data"` + } + if err := c.doGet(ctx, c.baseURL+"/v3/activity/tracking/"+url.PathEscape(eventID), &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// GetTrackingMessageActivity returns open and click totals and recent interactions for one message. +func (c *HTTPClient) GetTrackingMessageActivity(ctx context.Context, messageID string) (*domain.TrackingMessageActivity, error) { + if err := validateRequired("message ID", messageID); err != nil { + return nil, err + } + var result struct { + Data domain.TrackingMessageActivity `json:"data"` + } + if err := c.doGet(ctx, c.baseURL+"/v3/activity/tracking/messages/"+url.PathEscape(messageID), &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// activityWindowQuery adds the window and paging params shared by both feeds; zero means server default. +func activityWindowQuery(start, end int64, order string, limit int, pageToken string) *QueryBuilder { + qb := NewQueryBuilder() + if start != 0 { + qb.Add("start", strconv.FormatInt(start, 10)) + } + if end != 0 { + qb.Add("end", strconv.FormatInt(end, 10)) + } + return qb.Add("order", order).AddInt("limit", limit).Add("page_token", pageToken) +} diff --git a/internal/adapters/nylas/deliverability_alerts.go b/internal/adapters/nylas/deliverability_alerts.go new file mode 100644 index 0000000..2e67d2a --- /dev/null +++ b/internal/adapters/nylas/deliverability_alerts.go @@ -0,0 +1,79 @@ +package nylas + +import ( + "context" + "net/http" + "net/url" + + "github.com/nylas/cli/internal/domain" +) + +// ListSendAlertRules returns every send alert rule for the application (at most 20, unpaginated). +func (c *HTTPClient) ListSendAlertRules(ctx context.Context) ([]domain.SendAlertRule, error) { + var result struct { + Data []domain.SendAlertRule `json:"data"` + } + if err := c.doGet(ctx, c.baseURL+"/v3/alerts/send", &result); err != nil { + return nil, err + } + return result.Data, nil +} + +// GetSendAlertRule returns one send alert rule. +func (c *HTTPClient) GetSendAlertRule(ctx context.Context, ruleID string) (*domain.SendAlertRule, error) { + if err := validateRequired("rule ID", ruleID); err != nil { + return nil, err + } + var result struct { + Data domain.SendAlertRule `json:"data"` + } + if err := c.doGet(ctx, sendAlertRuleURL(c.baseURL, ruleID), &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// CreateSendAlertRule creates a send alert rule. It does not retry, so a timeout cannot create a duplicate. +func (c *HTTPClient) CreateSendAlertRule(ctx context.Context, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + resp, err := c.doJSONRequestNoRetry(ctx, http.MethodPost, c.baseURL+"/v3/alerts/send", req, http.StatusCreated) + if err != nil { + return nil, err + } + var result struct { + Data domain.SendAlertRule `json:"data"` + } + if err := c.decodeJSONResponse(resp, &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// UpdateSendAlertRule changes only the fields set in req (PUT with partial semantics). +func (c *HTTPClient) UpdateSendAlertRule(ctx context.Context, ruleID string, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + if err := validateRequired("rule ID", ruleID); err != nil { + return nil, err + } + resp, err := c.doJSONRequest(ctx, http.MethodPut, sendAlertRuleURL(c.baseURL, ruleID), req, http.StatusOK) + if err != nil { + return nil, err + } + var result struct { + Data domain.SendAlertRule `json:"data"` + } + if err := c.decodeJSONResponse(resp, &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +// DeleteSendAlertRule deletes a send alert rule. +func (c *HTTPClient) DeleteSendAlertRule(ctx context.Context, ruleID string) error { + if err := validateRequired("rule ID", ruleID); err != nil { + return err + } + return c.doDelete(ctx, sendAlertRuleURL(c.baseURL, ruleID)) +} + +func sendAlertRuleURL(baseURL, ruleID string) string { + return baseURL + "/v3/alerts/send/" + url.PathEscape(ruleID) +} diff --git a/internal/adapters/nylas/deliverability_metrics.go b/internal/adapters/nylas/deliverability_metrics.go new file mode 100644 index 0000000..98b7c64 --- /dev/null +++ b/internal/adapters/nylas/deliverability_metrics.go @@ -0,0 +1,74 @@ +package nylas + +import ( + "context" + + "github.com/nylas/cli/internal/domain" +) + +// GetSendMetricsSummary returns GET /v3/metrics/send/summary. +func (c *HTTPClient) GetSendMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsSummary, error) { + return getMetrics[domain.SendMetricsSummary](ctx, c, metricsWindowQuery(params).BuildURL(c.baseURL+"/v3/metrics/send/summary")) +} + +// GetSendMetricsTimeseries returns GET /v3/metrics/send/timeseries. +func (c *HTTPClient) GetSendMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsTimeseries, error) { + return getMetrics[domain.SendMetricsTimeseries](ctx, c, metricsTimeseriesURL(c.baseURL+"/v3/metrics/send/timeseries", params)) +} + +// GetSendMetricsBreakdown returns GET /v3/metrics/send. +func (c *HTTPClient) GetSendMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsBreakdown, error) { + return getMetrics[domain.SendMetricsBreakdown](ctx, c, metricsBreakdownURL(c.baseURL+"/v3/metrics/send", params)) +} + +// GetTrackingMetricsSummary returns GET /v3/metrics/tracking/summary. +func (c *HTTPClient) GetTrackingMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsSummary, error) { + return getMetrics[domain.TrackingMetricsSummary](ctx, c, metricsWindowQuery(params).BuildURL(c.baseURL+"/v3/metrics/tracking/summary")) +} + +// GetTrackingMetricsTimeseries returns GET /v3/metrics/tracking/timeseries. +func (c *HTTPClient) GetTrackingMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsTimeseries, error) { + return getMetrics[domain.TrackingMetricsTimeseries](ctx, c, metricsTimeseriesURL(c.baseURL+"/v3/metrics/tracking/timeseries", params)) +} + +// GetTrackingMetricsBreakdown returns GET /v3/metrics/tracking. +func (c *HTTPClient) GetTrackingMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsBreakdown, error) { + return getMetrics[domain.TrackingMetricsBreakdown](ctx, c, metricsBreakdownURL(c.baseURL+"/v3/metrics/tracking", params)) +} + +// getMetrics GETs a metrics route and unwraps its data envelope. +func getMetrics[T any](ctx context.Context, c *HTTPClient, queryURL string) (*T, error) { + var result struct { + Data T `json:"data"` + } + if err := c.doGet(ctx, queryURL, &result); err != nil { + return nil, err + } + return &result.Data, nil +} + +func metricsWindowQuery(params *domain.MetricsParams) *QueryBuilder { + if params == nil { + params = &domain.MetricsParams{} + } + return NewQueryBuilder(). + Add("start", params.Start). + Add("end", params.End). + Add("sending_domain", params.SendingDomain) +} + +func metricsTimeseriesURL(base string, params *domain.MetricsParams) string { + qb := metricsWindowQuery(params) + if params != nil { + qb.Add("granularity", params.Granularity) + } + return qb.BuildURL(base) +} + +func metricsBreakdownURL(base string, params *domain.MetricsParams) string { + qb := metricsWindowQuery(params) + if params != nil { + qb.Add("group_by", params.GroupBy).Add("sort", params.Sort).AddInt("limit", params.Limit) + } + return qb.BuildURL(base) +} diff --git a/internal/adapters/nylas/deliverability_test.go b/internal/adapters/nylas/deliverability_test.go new file mode 100644 index 0000000..622f857 --- /dev/null +++ b/internal/adapters/nylas/deliverability_test.go @@ -0,0 +1,266 @@ +package nylas + +import ( + "context" + "encoding/json" + "errors" + "io" + "net/http" + "net/http/httptest" + "testing" + + "github.com/nylas/cli/internal/domain" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func newDeliverabilityTestClient(t *testing.T, handler http.HandlerFunc) *HTTPClient { + t.Helper() + server := httptest.NewServer(handler) + t.Cleanup(server.Close) + client := NewHTTPClient() + client.baseURL = server.URL + client.SetCredentials("", "", "test-api-key") + return client +} + +func TestListSendEvents_QueryString(t *testing.T) { + var gotQuery map[string][]string + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, http.MethodGet, r.Method) + assert.Equal(t, "/v3/activity/send", r.URL.Path) + gotQuery = r.URL.Query() + _, _ = io.WriteString(w, `{"request_id":"req-1","data":[{"id":"e1","event_type":"bounced","bounce_class":"hard","timestamp":1730000000}],"next_cursor":"tok-2"}`) + }) + + resp, err := client.ListSendEvents(context.Background(), &domain.SendEventListParams{ + EventTypes: []string{"bounced", "complaint"}, + RecipientDomain: "gmail.com", + Start: 1729000000, + Limit: 10, + PageToken: "tok-1", + }) + require.NoError(t, err) + + // The API rejects a comma-joined event_type, so each value must be its own key. + assert.Equal(t, []string{"bounced", "complaint"}, gotQuery["event_type"]) + assert.Equal(t, []string{"gmail.com"}, gotQuery["recipient_domain"]) + assert.Equal(t, []string{"1729000000"}, gotQuery["start"]) + assert.Equal(t, []string{"10"}, gotQuery["limit"]) + assert.Equal(t, []string{"tok-1"}, gotQuery["page_token"]) + // The API returns 400 for any empty filter, so unset filters must not be sent at all. + for _, key := range []string{"end", "order", "from", "grant_id", "recipient", "bounce_class", "sending_domain", "message_id", "thread_id"} { + _, present := gotQuery[key] + assert.False(t, present, "unset filter %q was sent", key) + } + + assert.Equal(t, "tok-2", resp.NextCursor) + assert.Equal(t, "req-1", resp.RequestID) + require.Len(t, resp.Data, 1) + assert.Equal(t, "hard", resp.Data[0].BounceClass) +} + +func TestListTrackingEvents_SendsOnlyTrackingFilters(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/v3/activity/tracking", r.URL.Path) + assert.Equal(t, "event_type=link_clicked&label=welcome", r.URL.RawQuery) + _, _ = io.WriteString(w, `{"data":[]}`) + }) + + resp, err := client.ListTrackingEvents(context.Background(), &domain.TrackingEventListParams{ + EventTypes: []string{"link_clicked"}, + Label: "welcome", + }) + require.NoError(t, err) + assert.Empty(t, resp.NextCursor) +} + +func TestGetSendMessageActivity_EscapesMessageID(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + // Message IDs can contain characters that are not path-safe. + assert.Equal(t, "/v3/activity/send/messages/%3Cabc%2Fdef@mail.example.com%3E", r.RequestURI) + _, _ = io.WriteString(w, `{"data":{"message":{"message_id":""},"recipients":[]}}`) + }) + + activity, err := client.GetSendMessageActivity(context.Background(), "") + require.NoError(t, err) + assert.Equal(t, "", activity.Message.MessageID) +} + +func TestDeliverabilityRoutes(t *testing.T) { + const eventID = "5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f" + tests := []struct { + name string + path string + call func(*HTTPClient) error + }{ + {"send event", "/v3/activity/send/" + eventID, func(c *HTTPClient) error { + _, err := c.GetSendEvent(context.Background(), eventID) + return err + }}, + {"tracking event", "/v3/activity/tracking/" + eventID, func(c *HTTPClient) error { + _, err := c.GetTrackingEvent(context.Background(), eventID) + return err + }}, + {"tracking message", "/v3/activity/tracking/messages/m1", func(c *HTTPClient) error { + _, err := c.GetTrackingMessageActivity(context.Background(), "m1") + return err + }}, + {"send summary", "/v3/metrics/send/summary", func(c *HTTPClient) error { + _, err := c.GetSendMetricsSummary(context.Background(), nil) + return err + }}, + {"send timeseries", "/v3/metrics/send/timeseries", func(c *HTTPClient) error { + _, err := c.GetSendMetricsTimeseries(context.Background(), nil) + return err + }}, + {"send breakdown", "/v3/metrics/send", func(c *HTTPClient) error { + _, err := c.GetSendMetricsBreakdown(context.Background(), nil) + return err + }}, + {"tracking summary", "/v3/metrics/tracking/summary", func(c *HTTPClient) error { + _, err := c.GetTrackingMetricsSummary(context.Background(), nil) + return err + }}, + {"tracking timeseries", "/v3/metrics/tracking/timeseries", func(c *HTTPClient) error { + _, err := c.GetTrackingMetricsTimeseries(context.Background(), nil) + return err + }}, + {"tracking breakdown", "/v3/metrics/tracking", func(c *HTTPClient) error { + _, err := c.GetTrackingMetricsBreakdown(context.Background(), nil) + return err + }}, + {"list alert rules", "/v3/alerts/send", func(c *HTTPClient) error { + _, err := c.ListSendAlertRules(context.Background()) + return err + }}, + {"get alert rule", "/v3/alerts/send/r1", func(c *HTTPClient) error { + _, err := c.GetSendAlertRule(context.Background(), "r1") + return err + }}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + body := `{"data":{}}` + if tt.path == "/v3/alerts/send" { + body = `{"data":[]}` + } + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, http.MethodGet, r.Method) + assert.Equal(t, tt.path, r.URL.Path) + assert.Empty(t, r.URL.RawQuery) + _, _ = io.WriteString(w, body) + }) + require.NoError(t, tt.call(client)) + }) + } +} + +func TestGetSendMetricsBreakdown_QueryAndNullRates(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "/v3/metrics/send", r.URL.Path) + assert.Equal(t, "end=2026-10-31&group_by=recipient_domain&limit=5&sort=bounce_rate%3Adesc&start=2026-10-01", r.URL.RawQuery) + _, _ = io.WriteString(w, `{"data":{"group_by":"recipient_domain","window":null,"rows":[{"key":"x.com","sent":0,"delivery_rate":null,"is_others":false}]}}`) + }) + + breakdown, err := client.GetSendMetricsBreakdown(context.Background(), &domain.MetricsParams{ + Start: "2026-10-01", End: "2026-10-31", GroupBy: "recipient_domain", Sort: "bounce_rate:desc", Limit: 5, + Granularity: "week", // timeseries-only, must not leak into the breakdown query + }) + require.NoError(t, err) + // A null window and null rates mean "no data", which must stay distinguishable from 0. + assert.Nil(t, breakdown.Window) + require.Len(t, breakdown.Rows, 1) + assert.Nil(t, breakdown.Rows[0].DeliveryRate) +} + +func TestGetSendMetricsSummary_DecodesHealth(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, "sending_domain=mail.example.com", r.URL.RawQuery) + _, _ = io.WriteString(w, `{"data":{"health":{"state":"critical","window":{"start":"2026-10-27","end":"2026-11-02"},"min_assess_volume":100, + "findings":[{"rule":"concentration","severity":"high","title":"Bounces concentrate on x.com","evidence":{"metric":"bounce_rate","value":12.5,"threshold":10,"totals":{"sent":400}}}]}, + "totals":{"sent":400,"bounced_hard":50},"metrics":{"bounce_rate":{"value":12.5,"delta_pp":4,"prior_value":8.5,"status":"crit"}, + "delivery_rate":{"value":null,"delta_pp":null,"prior_value":null,"status":null},"complaint_rate":{"value":0,"delta_pp":null,"prior_value":null,"status":"ok"}}, + "prior_period":null}}`) + }) + + s, err := client.GetSendMetricsSummary(context.Background(), &domain.MetricsParams{SendingDomain: "mail.example.com"}) + require.NoError(t, err) + assert.Equal(t, "critical", s.Health.State) + require.Len(t, s.Health.Findings, 1) + assert.Equal(t, int64(400), s.Health.Findings[0].Evidence.Totals.Sent) + require.NotNil(t, s.Metrics.BounceRate.Status) + assert.Equal(t, "crit", *s.Metrics.BounceRate.Status) + assert.Nil(t, s.Metrics.DeliveryRate.Value) + require.NotNil(t, s.Metrics.ComplaintRate.Value) + assert.Zero(t, *s.Metrics.ComplaintRate.Value) + assert.Nil(t, s.PriorPeriod) +} + +func TestCreateSendAlertRule_BodyAndStatus(t *testing.T) { + var body map[string]json.RawMessage + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, http.MethodPost, r.Method) + assert.Equal(t, "/v3/alerts/send", r.URL.Path) + require.NoError(t, json.NewDecoder(r.Body).Decode(&body)) + w.WriteHeader(http.StatusCreated) + _, _ = io.WriteString(w, `{"request_id":"r","data":{"id":"rule-1","metric":"bounce_rate","direction":"above","threshold":0.25,"window_hours":1}}`) + }) + + metric := "bounce_rate" + threshold := json.Number("0.25") + hours := int64(1) + rule, err := client.CreateSendAlertRule(context.Background(), &domain.SendAlertRuleRequest{ + Metric: &metric, Threshold: &threshold, WindowHours: &hours, + }) + require.NoError(t, err) + assert.Equal(t, "rule-1", rule.ID) + + // The API rejects string thresholds and unknown or null fields, so the body must be exactly these. + assert.JSONEq(t, `"bounce_rate"`, string(body["metric"])) + assert.Equal(t, "0.25", string(body["threshold"])) + assert.Equal(t, "1", string(body["window_hours"])) + _, hasMinVolume := body["min_volume"] + assert.False(t, hasMinVolume) +} + +func TestUpdateSendAlertRule_PartialBody(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, http.MethodPut, r.Method) + assert.Equal(t, "/v3/alerts/send/rule-1", r.URL.Path) + raw, _ := io.ReadAll(r.Body) + // PUT is partial: only the changed field may be sent, or other fields would be reset. + assert.JSONEq(t, `{"threshold":3}`, string(raw)) + _, _ = io.WriteString(w, `{"data":{"id":"rule-1","threshold":3}}`) + }) + + threshold := json.Number("3") + rule, err := client.UpdateSendAlertRule(context.Background(), "rule-1", &domain.SendAlertRuleRequest{Threshold: &threshold}) + require.NoError(t, err) + assert.InDelta(t, 3.0, rule.Threshold, 0) +} + +func TestDeleteSendAlertRule(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + assert.Equal(t, http.MethodDelete, r.Method) + assert.Equal(t, "/v3/alerts/send/rule-1", r.URL.Path) + _, _ = io.WriteString(w, `{"request_id":"r"}`) + }) + require.NoError(t, client.DeleteSendAlertRule(context.Background(), "rule-1")) +} + +func TestDeliverability_APIErrorKeepsTypeAndMessage(t *testing.T) { + client := newDeliverabilityTestClient(t, func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusForbidden) + _, _ = io.WriteString(w, `{"request_id":"r","error":{"type":"api.forbidden","message":"this endpoint requires an application API key"}}`) + }) + + _, err := client.ListSendEvents(context.Background(), nil) + require.Error(t, err) + // Users hitting this with a grant token need the server's explanation, not a generic failure. + var apiErr *domain.APIError + require.True(t, errors.As(err, &apiErr)) + assert.Equal(t, http.StatusForbidden, apiErr.StatusCode) + assert.Equal(t, "api.forbidden", apiErr.Type) + assert.Contains(t, apiErr.Message, "application API key") +} diff --git a/internal/adapters/nylas/demo_deliverability.go b/internal/adapters/nylas/demo_deliverability.go new file mode 100644 index 0000000..8d9dfb0 --- /dev/null +++ b/internal/adapters/nylas/demo_deliverability.go @@ -0,0 +1,155 @@ +package nylas + +import ( + "context" + "time" + + "github.com/nylas/cli/internal/domain" +) + +const ( + demoDeliverabilityApp = "demo-app-id" + demoDeliverabilityDomain = "mail.example.com" + demoDeliverabilityFrom = "agent@mail.example.com" + demoDeliverabilityMsgID = "" + demoSendEventID = "5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f" + demoTrackingEventID = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" + demoSendAlertRuleID = "3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60" +) + +func demoRate(v float64) *float64 { return &v } + +func (d *DemoClient) ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) { + now := time.Now().Unix() + return &domain.SendEventListResponse{ + Data: []domain.SendEvent{ + {ID: demoSendEventID, EventType: "delivered", Timestamp: now - 60, ApplicationID: demoDeliverabilityApp, + MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, + Recipient: "alice@example.org", RecipientDomain: "example.org", Reason: "250 2.0.0 OK"}, + {ID: demoTrackingEventID, EventType: "bounced", BounceClass: "hard", Timestamp: now - 120, + ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, + SendingDomain: demoDeliverabilityDomain, Recipient: "bob@example.net", RecipientDomain: "example.net", + Reason: "General (5.1.1)"}, + }, + RequestID: "demo-request-id", + }, nil +} + +func (d *DemoClient) GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) { + return &domain.SendEvent{ID: eventID, EventType: "delivered", Timestamp: time.Now().Unix() - 60, + ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, + SendingDomain: demoDeliverabilityDomain, Recipient: "alice@example.org", RecipientDomain: "example.org", + Reason: "250 2.0.0 OK", Detail: &domain.SendEventDetail{SMTPResponse: "250 2.0.0 OK", ProcessingTimeMs: 812}}, nil +} + +func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { + now := time.Now().Unix() + return &domain.SendMessageActivity{ + Message: domain.SendMessageEnvelope{MessageID: messageID, ApplicationID: demoDeliverabilityApp, + From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, SentAt: now - 120, LastEventAt: now - 60}, + Recipients: []domain.SendMessageRecipient{{ + Recipient: "alice@example.org", RecipientDomain: "example.org", CurrentStatus: "delivered", + Events: []domain.SendTimelineEvent{ + {ID: demoSendEventID, EventType: "accepted", Timestamp: now - 120}, + {ID: demoTrackingEventID, EventType: "delivered", Timestamp: now - 60, Reason: "250 2.0.0 OK"}, + }, + }}, + }, nil +} + +func (d *DemoClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { + event, _ := d.GetTrackingEvent(ctx, demoTrackingEventID) + return &domain.TrackingEventListResponse{Data: []domain.TrackingEvent{*event}, RequestID: "demo-request-id"}, nil +} + +func (d *DemoClient) GetTrackingEvent(ctx context.Context, eventID string) (*domain.TrackingEvent, error) { + return &domain.TrackingEvent{ID: eventID, EventType: "opened", Timestamp: time.Now().Unix() - 30, + ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, + SendingDomain: demoDeliverabilityDomain, Label: "welcome", IsFirst: true, UserAgent: "Mozilla/5.0"}, nil +} + +func (d *DemoClient) GetTrackingMessageActivity(ctx context.Context, messageID string) (*domain.TrackingMessageActivity, error) { + first := time.Now().Unix() - 30 + return &domain.TrackingMessageActivity{ + MessageID: messageID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, Label: "welcome", + Tracking: domain.TrackingFlags{Opens: true, Links: true}, + Opens: domain.TrackingTotals{Total: 1, FirstAt: &first, LastAt: &first}, + Clicks: domain.TrackingClickTotals{Links: []domain.TrackingLinkClicks{}}, + Events: []domain.TrackingInteraction{ + {ID: demoTrackingEventID, EventType: "opened", Timestamp: first, IsFirst: true, UserAgent: "Mozilla/5.0"}, + }, + }, nil +} + +func (d *DemoClient) GetSendMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsSummary, error) { + ok := "ok" + return &domain.SendMetricsSummary{ + Health: domain.SendHealth{State: "healthy", MinAssessVolume: 100, Findings: []domain.SendHealthFinding{}}, + Totals: domain.SendCounts{Sent: 1200, Delivered: 1180, BouncedHard: 12, BouncedSoft: 5, Complaints: 1}, + Metrics: domain.SendRateTiles{ + DeliveryRate: domain.GradedRateTile{RateTile: domain.RateTile{Value: demoRate(98.33), DeltaPP: demoRate(0.4)}, Status: &ok}, + BounceRate: domain.GradedRateTile{RateTile: domain.RateTile{Value: demoRate(1.0), DeltaPP: demoRate(-0.2)}, Status: &ok}, + ComplaintRate: domain.GradedRateTile{RateTile: domain.RateTile{Value: demoRate(0.08)}, Status: &ok}, + }, + }, nil +} + +func (d *DemoClient) GetSendMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsTimeseries, error) { + day := time.Now().UTC().Format("2006-01-02") + return &domain.SendMetricsTimeseries{Granularity: "day", Buckets: []domain.SendMetricsBucket{{ + Start: day, End: day, SendCounts: domain.SendCounts{Sent: 180, Delivered: 177, BouncedHard: 2}, + BounceRate: demoRate(1.11), ComplaintRate: demoRate(0), + }}}, nil +} + +func (d *DemoClient) GetSendMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsBreakdown, error) { + return &domain.SendMetricsBreakdown{GroupBy: "sending_domain", Rows: []domain.SendMetricsRow{{ + Key: demoDeliverabilityDomain, Sent: 1200, Delivered: 1180, BouncedHard: 12, Complaints: 1, + DeliveryRate: demoRate(98.33), BounceRate: demoRate(1.0), ComplaintRate: demoRate(0.08), + }}}, nil +} + +func (d *DemoClient) GetTrackingMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsSummary, error) { + return &domain.TrackingMetricsSummary{ + Totals: domain.EngagementCounts{TrackedOpens: 900, TrackedLinks: 600, Opened: 410, Clicked: 75, OpensTotal: 820, ClicksTotal: 110}, + Metrics: domain.EngagementRateTiles{OpenRate: domain.RateTile{Value: demoRate(45.56)}, ClickRate: domain.RateTile{Value: demoRate(12.5)}}, + }, nil +} + +func (d *DemoClient) GetTrackingMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsTimeseries, error) { + day := time.Now().UTC().Format("2006-01-02") + return &domain.TrackingMetricsTimeseries{Granularity: "day", Buckets: []domain.TrackingMetricsBucket{{ + Start: day, End: day, EngagementCounts: domain.EngagementCounts{TrackedOpens: 120, Opened: 50}, + OpenRate: demoRate(41.67), + }}}, nil +} + +func (d *DemoClient) GetTrackingMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsBreakdown, error) { + return &domain.TrackingMetricsBreakdown{GroupBy: "sending_domain", Rows: []domain.TrackingMetricsRow{{ + Key: demoDeliverabilityDomain, EngagementCounts: domain.EngagementCounts{TrackedOpens: 900, TrackedLinks: 600, Opened: 410, Clicked: 75}, + OpenRate: demoRate(45.56), ClickRate: demoRate(12.5), + }}}, nil +} + +func (d *DemoClient) ListSendAlertRules(ctx context.Context) ([]domain.SendAlertRule, error) { + rule, _ := d.GetSendAlertRule(ctx, demoSendAlertRuleID) + return []domain.SendAlertRule{*rule}, nil +} + +func (d *DemoClient) GetSendAlertRule(ctx context.Context, ruleID string) (*domain.SendAlertRule, error) { + now := time.Now().Unix() + return &domain.SendAlertRule{ID: ruleID, ApplicationID: demoDeliverabilityApp, Metric: "bounce_rate", + Direction: "above", Threshold: 5, WindowHours: 1, MinVolume: 50, CreatedAt: now - 86400, UpdatedAt: now - 86400}, nil +} + +func (d *DemoClient) CreateSendAlertRule(ctx context.Context, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + return d.GetSendAlertRule(ctx, demoSendAlertRuleID) +} + +func (d *DemoClient) UpdateSendAlertRule(ctx context.Context, ruleID string, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + return d.GetSendAlertRule(ctx, ruleID) +} + +func (d *DemoClient) DeleteSendAlertRule(ctx context.Context, ruleID string) error { + return nil +} diff --git a/internal/adapters/nylas/mock_client.go b/internal/adapters/nylas/mock_client.go index 51c5bfb..b35be56 100644 --- a/internal/adapters/nylas/mock_client.go +++ b/internal/adapters/nylas/mock_client.go @@ -175,6 +175,25 @@ type MockClient struct { // Contact functions GetContactsFunc func(ctx context.Context, grantID string, params *domain.ContactQueryParams) ([]domain.Contact, error) + + // Deliverability functions + ListSendEventsFunc func(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) + GetSendEventFunc func(ctx context.Context, eventID string) (*domain.SendEvent, error) + GetSendMessageActivityFunc func(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) + ListTrackingEventsFunc func(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) + GetTrackingEventFunc func(ctx context.Context, eventID string) (*domain.TrackingEvent, error) + GetTrackingMessageActivityFunc func(ctx context.Context, messageID string) (*domain.TrackingMessageActivity, error) + GetSendMetricsSummaryFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsSummary, error) + GetSendMetricsTimeseriesFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsTimeseries, error) + GetSendMetricsBreakdownFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsBreakdown, error) + GetTrackingMetricsSummaryFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsSummary, error) + GetTrackingMetricsTimeseriesFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsTimeseries, error) + GetTrackingMetricsBreakdownFunc func(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsBreakdown, error) + ListSendAlertRulesFunc func(ctx context.Context) ([]domain.SendAlertRule, error) + GetSendAlertRuleFunc func(ctx context.Context, ruleID string) (*domain.SendAlertRule, error) + CreateSendAlertRuleFunc func(ctx context.Context, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) + UpdateSendAlertRuleFunc func(ctx context.Context, ruleID string, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) + DeleteSendAlertRuleFunc func(ctx context.Context, ruleID string) error } // NewMockClient creates a new MockClient. diff --git a/internal/adapters/nylas/mock_deliverability.go b/internal/adapters/nylas/mock_deliverability.go new file mode 100644 index 0000000..0bb07e5 --- /dev/null +++ b/internal/adapters/nylas/mock_deliverability.go @@ -0,0 +1,126 @@ +package nylas + +import ( + "context" + + "github.com/nylas/cli/internal/domain" +) + +func (m *MockClient) ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) { + if m.ListSendEventsFunc != nil { + return m.ListSendEventsFunc(ctx, params) + } + return &domain.SendEventListResponse{Data: []domain.SendEvent{}}, nil +} + +func (m *MockClient) GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) { + if m.GetSendEventFunc != nil { + return m.GetSendEventFunc(ctx, eventID) + } + return &domain.SendEvent{ID: eventID, EventType: "delivered"}, nil +} + +func (m *MockClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { + if m.GetSendMessageActivityFunc != nil { + return m.GetSendMessageActivityFunc(ctx, messageID) + } + return &domain.SendMessageActivity{Message: domain.SendMessageEnvelope{MessageID: messageID}}, nil +} + +func (m *MockClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { + if m.ListTrackingEventsFunc != nil { + return m.ListTrackingEventsFunc(ctx, params) + } + return &domain.TrackingEventListResponse{Data: []domain.TrackingEvent{}}, nil +} + +func (m *MockClient) GetTrackingEvent(ctx context.Context, eventID string) (*domain.TrackingEvent, error) { + if m.GetTrackingEventFunc != nil { + return m.GetTrackingEventFunc(ctx, eventID) + } + return &domain.TrackingEvent{ID: eventID, EventType: "opened"}, nil +} + +func (m *MockClient) GetTrackingMessageActivity(ctx context.Context, messageID string) (*domain.TrackingMessageActivity, error) { + if m.GetTrackingMessageActivityFunc != nil { + return m.GetTrackingMessageActivityFunc(ctx, messageID) + } + return &domain.TrackingMessageActivity{MessageID: messageID}, nil +} + +func (m *MockClient) GetSendMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsSummary, error) { + if m.GetSendMetricsSummaryFunc != nil { + return m.GetSendMetricsSummaryFunc(ctx, params) + } + return &domain.SendMetricsSummary{Health: domain.SendHealth{State: "insufficient_data"}}, nil +} + +func (m *MockClient) GetSendMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsTimeseries, error) { + if m.GetSendMetricsTimeseriesFunc != nil { + return m.GetSendMetricsTimeseriesFunc(ctx, params) + } + return &domain.SendMetricsTimeseries{Granularity: "day"}, nil +} + +func (m *MockClient) GetSendMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsBreakdown, error) { + if m.GetSendMetricsBreakdownFunc != nil { + return m.GetSendMetricsBreakdownFunc(ctx, params) + } + return &domain.SendMetricsBreakdown{GroupBy: "sending_domain"}, nil +} + +func (m *MockClient) GetTrackingMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsSummary, error) { + if m.GetTrackingMetricsSummaryFunc != nil { + return m.GetTrackingMetricsSummaryFunc(ctx, params) + } + return &domain.TrackingMetricsSummary{}, nil +} + +func (m *MockClient) GetTrackingMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsTimeseries, error) { + if m.GetTrackingMetricsTimeseriesFunc != nil { + return m.GetTrackingMetricsTimeseriesFunc(ctx, params) + } + return &domain.TrackingMetricsTimeseries{Granularity: "day"}, nil +} + +func (m *MockClient) GetTrackingMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsBreakdown, error) { + if m.GetTrackingMetricsBreakdownFunc != nil { + return m.GetTrackingMetricsBreakdownFunc(ctx, params) + } + return &domain.TrackingMetricsBreakdown{GroupBy: "sending_domain"}, nil +} + +func (m *MockClient) ListSendAlertRules(ctx context.Context) ([]domain.SendAlertRule, error) { + if m.ListSendAlertRulesFunc != nil { + return m.ListSendAlertRulesFunc(ctx) + } + return []domain.SendAlertRule{}, nil +} + +func (m *MockClient) GetSendAlertRule(ctx context.Context, ruleID string) (*domain.SendAlertRule, error) { + if m.GetSendAlertRuleFunc != nil { + return m.GetSendAlertRuleFunc(ctx, ruleID) + } + return &domain.SendAlertRule{ID: ruleID, Metric: "bounce_rate", Direction: "above"}, nil +} + +func (m *MockClient) CreateSendAlertRule(ctx context.Context, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + if m.CreateSendAlertRuleFunc != nil { + return m.CreateSendAlertRuleFunc(ctx, req) + } + return &domain.SendAlertRule{ID: "rule-mock"}, nil +} + +func (m *MockClient) UpdateSendAlertRule(ctx context.Context, ruleID string, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) { + if m.UpdateSendAlertRuleFunc != nil { + return m.UpdateSendAlertRuleFunc(ctx, ruleID, req) + } + return &domain.SendAlertRule{ID: ruleID}, nil +} + +func (m *MockClient) DeleteSendAlertRule(ctx context.Context, ruleID string) error { + if m.DeleteSendAlertRuleFunc != nil { + return m.DeleteSendAlertRuleFunc(ctx, ruleID) + } + return nil +} diff --git a/internal/cli/deliverability/deliverability.go b/internal/cli/deliverability/deliverability.go new file mode 100644 index 0000000..58e1421 --- /dev/null +++ b/internal/cli/deliverability/deliverability.go @@ -0,0 +1,71 @@ +// Package deliverability implements `nylas deliverability`: send and tracking +// activity, send and tracking metrics, and send alert rules. +package deliverability + +import "github.com/spf13/cobra" + +// NewDeliverabilityCmd creates the deliverability command group. +func NewDeliverabilityCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "deliverability", + Short: "Inspect send and tracking events, metrics, and send alerts", + Long: `Inspect what happened to the email your application sends. + + send-events Send activity (accepted, delivered, bounced, complaint, rejected) and send metrics + tracking-events Open and link-click activity and engagement metrics + send-alerts Rules that fire the alert.triggered webhook when a send rate crosses a threshold + +These commands are application-level: they use your API key and do not take a grant. +Activity covers the last 90 days. Metrics accept windows of up to 365 days.`, + } + + cmd.AddCommand(newSendEventsCmd()) + cmd.AddCommand(newTrackingEventsCmd()) + cmd.AddCommand(newSendAlertsCmd()) + + return cmd +} + +func newSendEventsCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "send-events", + Short: "Send activity and send metrics", + } + cmd.AddCommand(newSendEventsListCmd()) + cmd.AddCommand(newSendEventsShowCmd()) + cmd.AddCommand(newSendEventsMessageCmd()) + cmd.AddCommand(newSendSummaryCmd()) + cmd.AddCommand(newSendTimeseriesCmd()) + cmd.AddCommand(newSendBreakdownCmd()) + return cmd +} + +func newTrackingEventsCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "tracking-events", + Short: "Open and click activity and engagement metrics", + } + cmd.AddCommand(newTrackingEventsListCmd()) + cmd.AddCommand(newTrackingEventsShowCmd()) + cmd.AddCommand(newTrackingEventsMessageCmd()) + cmd.AddCommand(newTrackingSummaryCmd()) + cmd.AddCommand(newTrackingTimeseriesCmd()) + cmd.AddCommand(newTrackingBreakdownCmd()) + return cmd +} + +func newSendAlertsCmd() *cobra.Command { + cmd := &cobra.Command{ + Use: "send-alerts", + Short: "Manage send alert rules", + Long: `Manage send alert rules. Each rule is evaluated per sending domain. When it fires, +Nylas sends the alert.triggered webhook to your application's webhook subscriptions. +An application can have at most 20 rules.`, + } + cmd.AddCommand(newSendAlertsListCmd()) + cmd.AddCommand(newSendAlertsShowCmd()) + cmd.AddCommand(newSendAlertsCreateCmd()) + cmd.AddCommand(newSendAlertsUpdateCmd()) + cmd.AddCommand(newSendAlertsDeleteCmd()) + return cmd +} diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go new file mode 100644 index 0000000..4b2c7bb --- /dev/null +++ b/internal/cli/deliverability/deliverability_test.go @@ -0,0 +1,235 @@ +package deliverability + +import ( + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strconv" + "testing" + "time" + + "github.com/nylas/cli/internal/cli/testutil" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +type capturedRequest struct { + method string + path string + query map[string][]string + body string +} + +// runAgainstFakeAPI runs the real command tree against a fake Nylas API that answers every request with respBody. +func runAgainstFakeAPI(t *testing.T, status int, respBody string, args ...string) (string, []capturedRequest, error) { + t.Helper() + var requests []capturedRequest + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + requests = append(requests, capturedRequest{method: r.Method, path: r.URL.Path, query: r.URL.Query(), body: string(body)}) + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(status) + _, _ = io.WriteString(w, respBody) + })) + t.Cleanup(server.Close) + + // Isolate from the developer's real config/keyring; env API key wins. + t.Setenv("HOME", t.TempDir()) + t.Setenv("XDG_CONFIG_HOME", t.TempDir()) + t.Setenv("NYLAS_API_KEY", "test-api-key") + t.Setenv("NYLAS_API_BASE_URL", server.URL) + + stdout, _, err := testutil.ExecuteSubCommand(NewDeliverabilityCmd(), args...) + return stdout, requests, err +} + +const sendEventsPage = `{"request_id":"req-1","next_cursor":"tok-2","data":[ + {"id":"aaa","event_type":"bounced","bounce_class":"hard","timestamp":1730000000,"recipient":"bob@example.net","from":"agent@mail.example.com","reason":"General (5.1.1)"}, + {"id":"bbb","event_type":"delivered","timestamp":1730000100,"recipient":"alice@example.org","from":"agent@mail.example.com","reason":"250 OK"}]}` + +func TestSendEventsList_FlagsBecomeQuery(t *testing.T) { + before := time.Now().Add(-24 * time.Hour).Unix() + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, + "send-events", "list", "--event-type", "bounced", "--event-type", "complaint", "--start", "24h", "--recipient-domain", "example.net") + require.NoError(t, err) + require.Len(t, reqs, 1) + q := reqs[0].query + assert.Equal(t, "/v3/activity/send", reqs[0].path) + // Repeated --event-type must reach the API as repeated keys; it rejects "bounced,complaint". + assert.Equal(t, []string{"bounced", "complaint"}, q["event_type"]) + assert.Equal(t, []string{"example.net"}, q["recipient_domain"]) + // "24h" is a look-back: start is 24 hours ago, not 24 hours from now. + start, convErr := strconv.ParseInt(q["start"][0], 10, 64) + require.NoError(t, convErr) + assert.InDelta(t, before, start, 5) + + assert.Contains(t, out, "bounced (hard)") + assert.Contains(t, out, "Next page token: tok-2") +} + +func TestSendEventsList_JSONKeepsEnvelope(t *testing.T) { + out, _, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--json") + require.NoError(t, err) + // Scripts page with next_cursor, so JSON output must keep the envelope, not just the rows. + var resp struct { + Data []map[string]any `json:"data"` + NextCursor string `json:"next_cursor"` + } + require.NoError(t, json.Unmarshal([]byte(out), &resp)) + assert.Len(t, resp.Data, 2) + assert.Equal(t, "tok-2", resp.NextCursor) +} + +func TestSendEventsList_QuietPrintsIDs(t *testing.T) { + out, _, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--quiet") + require.NoError(t, err) + assert.Equal(t, "aaa\nbbb\n", out) +} + +func TestSendEventsList_RejectsBadStartWithoutCallingAPI(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "last tuesday-ish") + require.Error(t, err) + assert.Empty(t, reqs) +} + +func TestShow_RejectsMalformedEventID(t *testing.T) { + // The API returns a non-JSON 404 for IDs that are not 64 hex characters, so catch them first. + for _, group := range []string{"send-events", "tracking-events"} { + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, `{}`, group, "show", "not-an-id") + require.Error(t, err, group) + assert.Contains(t, err.Error(), "invalid event ID") + assert.Empty(t, reqs, group) + } +} + +func TestSendSummary_NullRatesAreNotZero(t *testing.T) { + resp := `{"data":{"health":{"state":"critical","window":{"start":"2026-10-27","end":"2026-11-02"},"min_assess_volume":100, + "findings":[{"rule":"concentration","severity":"high","title":"Hard bounces concentrate on example.net","recommendation":"Clean your list"}]}, + "totals":{"sent":400,"delivered":0,"bounced_hard":50}, + "metrics":{"delivery_rate":{"value":null,"delta_pp":null,"prior_value":null,"status":null}, + "bounce_rate":{"value":12.5,"delta_pp":4,"prior_value":8.5,"status":"crit"}, + "complaint_rate":{"value":null,"delta_pp":null,"prior_value":null,"status":null}},"prior_period":null}}` + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, resp, "send-events", "summary", "--start", "2026-10-01", "--end", "2026-10-31") + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, "/v3/metrics/send/summary", reqs[0].path) + assert.Equal(t, []string{"2026-10-01"}, reqs[0].query["start"]) + + // A null rate means a zero denominator; printing 0% would claim a perfect complaint rate. + assert.NotContains(t, out, "0.00%") + assert.Contains(t, out, "—") + assert.Contains(t, out, "12.50%") + assert.Contains(t, out, "+4.00 pp") + assert.Contains(t, out, "Hard bounces concentrate on example.net") +} + +func TestMetrics_RejectsNonDateWindowWithoutCallingAPI(t *testing.T) { + // Metrics take UTC dates; an epoch here is a common mix-up with the activity feed. + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, `{}`, "tracking-events", "summary", "--start", "1730000000") + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid --start") + assert.Empty(t, reqs) +} + +func TestSendBreakdown_NullWindowExplainsNoData(t *testing.T) { + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, `{"data":{"group_by":"recipient_domain","window":null,"rows":[]}}`, + "send-events", "breakdown", "--group-by", "recipient_domain", "--start", "2025-01-01", "--end", "2025-01-31") + require.NoError(t, err) + assert.Equal(t, []string{"recipient_domain"}, reqs[0].query["group_by"]) + assert.Equal(t, []string{"25"}, reqs[0].query["limit"]) + assert.Contains(t, out, "only cover the last 90 days") +} + +func TestTrackingMessage_ShowsPerLinkClicks(t *testing.T) { + resp := `{"data":{"message_id":"m1","from":"agent@mail.example.com","tracking":{"opens":true,"links":true}, + "opens":{"total":2,"first_at":1730000000,"last_at":1730000500}, + "clicks":{"total":3,"first_at":1730000100,"last_at":1730000400,"links":[{"link_index":0,"url":"https://example.com/a","clicks":3}]}, + "events":[]}}` + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, resp, "tracking-events", "message", "m1") + require.NoError(t, err) + assert.Equal(t, "/v3/activity/tracking/messages/m1", reqs[0].path) + assert.Contains(t, out, "https://example.com/a") + assert.Contains(t, out, "opens on, links on") +} + +const ruleResp = `{"data":{"id":"3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60","metric":"bounce_rate","direction":"above","threshold":0.25,"window_hours":1,"min_volume":0}}` + +func TestSendAlertsCreate_SendsExactBody(t *testing.T) { + out, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, + "send-alerts", "create", "--metric", "bounce_rate", "--threshold", "0.25", "--window-hours", "1") + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, http.MethodPost, reqs[0].method) + // threshold must be a JSON number with the user's decimals; min_volume was not set so it is omitted. + assert.JSONEq(t, `{"metric":"bounce_rate","threshold":0.25,"window_hours":1}`, reqs[0].body) + assert.Contains(t, out, "bounce_rate above 0.25%") +} + +func TestSendAlertsCreate_RequiresCoreFlags(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, "send-alerts", "create", "--metric", "bounce_rate") + require.Error(t, err) + assert.Empty(t, reqs) +} + +func TestSendAlertsCreate_RejectsNonNumericThreshold(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, + "send-alerts", "create", "--metric", "bounce_rate", "--threshold", "five", "--window-hours", "1") + require.Error(t, err) + assert.Contains(t, err.Error(), "invalid --threshold") + assert.Empty(t, reqs) +} + +func TestSendAlertsUpdate_SendsOnlyChangedFields(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, ruleResp, "send-alerts", "update", "rule-1", "--min-volume", "0") + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, http.MethodPut, reqs[0].method) + assert.Equal(t, "/v3/alerts/send/rule-1", reqs[0].path) + // PUT is partial: sending unset flags as zero values would overwrite the rule. An explicit 0 must still be sent. + assert.JSONEq(t, `{"min_volume":0}`, reqs[0].body) +} + +func TestSendAlertsUpdate_NoFlagsDoesNotCallAPI(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, ruleResp, "send-alerts", "update", "rule-1") + require.Error(t, err) + assert.Contains(t, err.Error(), "nothing to update") + assert.Empty(t, reqs) +} + +func TestSendAlertsDelete_RequiresYes(t *testing.T) { + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, `{"request_id":"r"}`, "send-alerts", "delete", "rule-1") + require.Error(t, err) + assert.Empty(t, reqs) + + _, reqs, err = runAgainstFakeAPI(t, http.StatusOK, `{"request_id":"r"}`, "send-alerts", "delete", "rule-1", "--yes") + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, http.MethodDelete, reqs[0].method) +} + +func TestAPIErrorMessageReachesUser(t *testing.T) { + _, _, err := runAgainstFakeAPI(t, http.StatusForbidden, + `{"request_id":"r","error":{"type":"api.forbidden","message":"this endpoint requires an application API key"}}`, + "send-alerts", "list") + require.Error(t, err) + assert.Contains(t, err.Error(), "application API key") +} + +func TestCommandTree(t *testing.T) { + cmd := NewDeliverabilityCmd() + want := map[string][]string{ + "send-events": {"list", "show", "message", "summary", "timeseries", "breakdown"}, + "tracking-events": {"list", "show", "message", "summary", "timeseries", "breakdown"}, + "send-alerts": {"list", "show", "create", "update", "delete"}, + } + for group, subs := range want { + g, _, err := cmd.Find([]string{group}) + require.NoError(t, err, group) + var got []string + for _, c := range g.Commands() { + got = append(got, c.Name()) + } + assert.ElementsMatch(t, subs, got, group) + } +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go new file mode 100644 index 0000000..50c9b47 --- /dev/null +++ b/internal/cli/deliverability/helpers.go @@ -0,0 +1,120 @@ +package deliverability + +import ( + "context" + "fmt" + "io" + "regexp" + "strconv" + "strings" + "time" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +const metricsDateLayout = "2006-01-02" + +var eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) + +// withClient runs fn with an application-level client (no grant needed). +func withClient(fn func(ctx context.Context, client ports.NylasClient) error) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + return struct{}{}, fn(ctx, client) + }) + return err +} + +// parseActivityTime turns a --start/--end value into Unix seconds; a duration such as 24h or 7d means that long ago. +func parseActivityTime(flag, value string, now time.Time) (int64, error) { + value = strings.TrimSpace(value) + if value == "" { + return 0, nil + } + if d, err := common.ParseDuration(value); err == nil { + return now.Add(-d).Unix(), nil + } + t, err := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now}) + if err != nil { + return 0, common.NewUserError( + fmt.Sprintf("invalid --%s value %q", flag, value), + "Use a Unix timestamp, YYYY-MM-DD, RFC3339, or a look-back such as 24h or 7d", + ) + } + return t.Unix(), nil +} + +// validateMetricsDate checks a --start/--end metrics value is YYYY-MM-DD. +func validateMetricsDate(flag, value string) error { + if value == "" { + return nil + } + if _, err := time.Parse(metricsDateLayout, value); err != nil { + return common.NewUserError(fmt.Sprintf("invalid --%s value %q", flag, value), "Use a UTC date in YYYY-MM-DD form") + } + return nil +} + +// validateEventID rejects IDs the API cannot route (they get a non-JSON 404). +func validateEventID(id string) error { + if !eventIDPattern.MatchString(id) { + return common.NewUserError(fmt.Sprintf("invalid event ID %q", id), "Event IDs are 64 lowercase hex characters, as shown by the list command") + } + return nil +} + +func formatUnix(ts int64) string { + if ts == 0 { + return "" + } + return time.Unix(ts, 0).Local().Format("2006-01-02 15:04:05") +} + +// formatRate prints a percentage; nil means no data (a zero denominator), never 0%. +func formatRate(v *float64) string { + if v == nil { + return "—" + } + return strconv.FormatFloat(*v, 'f', 2, 64) + "%" +} + +func formatDelta(v *float64) string { + if v == nil { + return "—" + } + return fmt.Sprintf("%+.2f pp", *v) +} + +func formatCount(v int64) string { return strconv.FormatInt(v, 10) } + +func formatThreshold(v float64) string { return strconv.FormatFloat(v, 'f', -1, 64) + "%" } + +func newTable(w io.Writer, headers ...string) *common.Table { + return common.NewTable(headers...).SetWriter(w) +} + +func nextCursorNote(cmd *cobra.Command, nextCursor string) { + if nextCursor == "" { + return + } + _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page token: %s\n", nextCursor) +} + +// writeStructuredList writes a list response as JSON/YAML, or only the row IDs in quiet mode. +func writeStructuredList(cmd *cobra.Command, resp, rows any) (bool, error) { + quiet, _ := cmd.Flags().GetBool("quiet") + format, _ := cmd.Flags().GetString("format") + if quiet || format == "quiet" { + return true, common.GetOutputWriter(cmd).WriteList(rows, nil) + } + return writeStructured(cmd, resp) +} + +// writeStructured writes v as JSON/YAML/quiet and reports whether it did. +func writeStructured(cmd *cobra.Command, v any) (bool, error) { + if !common.IsStructuredOutput(cmd) { + return false, nil + } + return true, common.GetOutputWriter(cmd).Write(v) +} diff --git a/internal/cli/deliverability/metrics.go b/internal/cli/deliverability/metrics.go new file mode 100644 index 0000000..36855ec --- /dev/null +++ b/internal/cli/deliverability/metrics.go @@ -0,0 +1,164 @@ +package deliverability + +import ( + "context" + "strings" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +type metricsRunner func(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error + +// newMetricsCmd builds a metrics command with the shared --start/--end/--sending-domain flags. +func newMetricsCmd(use, short, example string, run metricsRunner, extraFlags func(*cobra.Command, *domain.MetricsParams)) *cobra.Command { + var params domain.MetricsParams + cmd := &cobra.Command{ + Use: use, + Short: short, + Example: example, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + if err := validateMetricsDate("start", params.Start); err != nil { + return err + } + if err := validateMetricsDate("end", params.End); err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + return run(ctx, cmd, client, ¶ms) + }) + }, + } + cmd.Flags().StringVar(¶ms.Start, "start", "", "First UTC day, YYYY-MM-DD (default: 6 days before --end)") + cmd.Flags().StringVar(¶ms.End, "end", "", "Last UTC day, YYYY-MM-DD, inclusive (default: today)") + cmd.Flags().StringVar(¶ms.SendingDomain, "sending-domain", "", "Only this sending domain") + if extraFlags != nil { + extraFlags(cmd, ¶ms) + } + return cmd +} + +func addGranularityFlag(cmd *cobra.Command, params *domain.MetricsParams) { + cmd.Flags().StringVar(¶ms.Granularity, "granularity", "", + "Bucket size: "+strings.Join(domain.MetricsGranularities, ", ")+" (default auto: day ≤21 days, week ≤92, else month)") +} + +func addBreakdownFlags(groupBy []string, sortKeys string) func(*cobra.Command, *domain.MetricsParams) { + return func(cmd *cobra.Command, params *domain.MetricsParams) { + cmd.Flags().StringVar(¶ms.GroupBy, "group-by", "", "Dimension: "+strings.Join(groupBy, ", ")+" (default sending_domain)") + cmd.Flags().StringVar(¶ms.Sort, "sort", "", "Sort as :; keys: "+sortKeys) + cmd.Flags().IntVarP(¶ms.Limit, "limit", "n", 25, "Rows to show before the rest are summed into (others), 1-100") + } +} + +func newSendSummaryCmd() *cobra.Command { + return newMetricsCmd("summary", "Show send health, totals, and rates", + ` nylas deliverability send-events summary + nylas deliverability send-events summary --start 2026-10-01 --end 2026-10-31 --sending-domain mail.example.com`, + runSendSummary, nil) +} + +func newSendTimeseriesCmd() *cobra.Command { + return newMetricsCmd("timeseries", "Show send counts and rates per day, week, or month", + ` nylas deliverability send-events timeseries --granularity week --start 2026-08-01`, + runSendTimeseries, addGranularityFlag) +} + +func newSendBreakdownCmd() *cobra.Command { + return newMetricsCmd("breakdown", "Show send counts and rates per sending domain, agent account, or recipient domain", + ` nylas deliverability send-events breakdown --group-by recipient_domain --sort bounce_rate:desc`, + runSendBreakdown, addBreakdownFlags(domain.SendMetricsGroupBy, "key, sent, delivery_rate, bounce_rate, complaint_rate (default sent:desc)")) +} + +func newTrackingSummaryCmd() *cobra.Command { + return newMetricsCmd("summary", "Show engagement totals and open and click rates", + ` nylas deliverability tracking-events summary --start 2026-10-01`, + runTrackingSummary, nil) +} + +func newTrackingTimeseriesCmd() *cobra.Command { + return newMetricsCmd("timeseries", "Show engagement counts and rates per day, week, or month", + ` nylas deliverability tracking-events timeseries --granularity day`, + runTrackingTimeseries, addGranularityFlag) +} + +func newTrackingBreakdownCmd() *cobra.Command { + return newMetricsCmd("breakdown", "Show engagement per sending domain or agent account", + ` nylas deliverability tracking-events breakdown --group-by agent_account --sort open_rate:desc`, + runTrackingBreakdown, addBreakdownFlags(domain.TrackingMetricsGroupBy, "key, tracked_opens, tracked_links, open_rate, click_rate (default tracked_opens:desc)")) +} + +func runSendSummary(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + summary, err := client.GetSendMetricsSummary(ctx, params) + if err != nil { + return common.WrapGetError("send metrics summary", err) + } + if done, err := writeStructured(cmd, summary); done { + return err + } + renderSendSummary(cmd.OutOrStdout(), summary) + return nil +} + +func runSendTimeseries(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + series, err := client.GetSendMetricsTimeseries(ctx, params) + if err != nil { + return common.WrapGetError("send metrics timeseries", err) + } + if done, err := writeStructured(cmd, series); done { + return err + } + renderSendTimeseries(cmd.OutOrStdout(), series) + return nil +} + +func runSendBreakdown(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + breakdown, err := client.GetSendMetricsBreakdown(ctx, params) + if err != nil { + return common.WrapGetError("send metrics breakdown", err) + } + if done, err := writeStructured(cmd, breakdown); done { + return err + } + renderSendBreakdown(cmd.OutOrStdout(), breakdown) + return nil +} + +func runTrackingSummary(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + summary, err := client.GetTrackingMetricsSummary(ctx, params) + if err != nil { + return common.WrapGetError("tracking metrics summary", err) + } + if done, err := writeStructured(cmd, summary); done { + return err + } + renderTrackingSummary(cmd.OutOrStdout(), summary) + return nil +} + +func runTrackingTimeseries(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + series, err := client.GetTrackingMetricsTimeseries(ctx, params) + if err != nil { + return common.WrapGetError("tracking metrics timeseries", err) + } + if done, err := writeStructured(cmd, series); done { + return err + } + renderTrackingTimeseries(cmd.OutOrStdout(), series) + return nil +} + +func runTrackingBreakdown(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error { + breakdown, err := client.GetTrackingMetricsBreakdown(ctx, params) + if err != nil { + return common.WrapGetError("tracking metrics breakdown", err) + } + if done, err := writeStructured(cmd, breakdown); done { + return err + } + renderTrackingBreakdown(cmd.OutOrStdout(), breakdown) + return nil +} diff --git a/internal/cli/deliverability/metrics_render.go b/internal/cli/deliverability/metrics_render.go new file mode 100644 index 0000000..ebfe510 --- /dev/null +++ b/internal/cli/deliverability/metrics_render.go @@ -0,0 +1,134 @@ +package deliverability + +import ( + "fmt" + "io" + + "github.com/fatih/color" + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" +) + +// healthColor maps send health states and tile statuses to colors. +func healthColor(state string) *color.Color { + switch state { + case "healthy", "ok": + return common.Green + case "at_risk", "warn": + return common.Yellow + case "critical", "crit": + return common.Red + default: + return common.Dim + } +} + +func windowString(w *domain.MetricsWindow) string { + if w == nil { + return "—" + } + return w.Start + " → " + w.End +} + +func renderSendSummary(w io.Writer, s *domain.SendMetricsSummary) { + _, _ = fmt.Fprintf(w, "Health: %s (last 7 days, %s)\n", + healthColor(s.Health.State).Sprint(s.Health.State), windowString(&s.Health.Window)) + if s.Health.State == "insufficient_data" { + _, _ = fmt.Fprintf(w, " fewer than %d sends in the last 7 days, so health is not graded\n", s.Health.MinAssessVolume) + } + _, _ = fmt.Fprintf(w, "Prior period: %s\n\n", windowString(s.PriorPeriod)) + + totals := newTable(w, "SENT", "DELIVERED", "HARD BOUNCES", "SOFT BOUNCES", "UNDETERMINED", "REJECTED", "COMPLAINTS") + t := s.Totals + totals.AddRow(formatCount(t.Sent), formatCount(t.Delivered), formatCount(t.BouncedHard), formatCount(t.BouncedSoft), + formatCount(t.BouncedUndetermined), formatCount(t.Rejected), formatCount(t.Complaints)) + totals.Render() + _, _ = fmt.Fprintln(w) + + rates := newTable(w, "RATE", "VALUE", "CHANGE", "PRIOR", "STATUS") + addGradedTile(rates, "delivery", s.Metrics.DeliveryRate) + addGradedTile(rates, "bounce (hard)", s.Metrics.BounceRate) + addGradedTile(rates, "complaint", s.Metrics.ComplaintRate) + rates.Render() + + if len(s.Health.Findings) > 0 { + _, _ = fmt.Fprintln(w, "\nFindings:") + for _, f := range s.Health.Findings { + _, _ = fmt.Fprintf(w, " [%s] %s\n", f.Severity, f.Title) + if f.Recommendation != "" { + _, _ = fmt.Fprintf(w, " %s\n", f.Recommendation) + } + } + } +} + +func addGradedTile(table *common.Table, name string, tile domain.GradedRateTile) { + status := "—" + if tile.Status != nil { + status = healthColor(*tile.Status).Sprint(*tile.Status) + } + table.AddRow(name, formatRate(tile.Value), formatDelta(tile.DeltaPP), formatRate(tile.PriorValue), status) +} + +func renderSendTimeseries(w io.Writer, s *domain.SendMetricsTimeseries) { + _, _ = fmt.Fprintf(w, "Granularity: %s\n\n", s.Granularity) + table := newTable(w, "START", "END", "SENT", "DELIVERED", "HARD BOUNCES", "COMPLAINTS", "BOUNCE RATE", "COMPLAINT RATE") + for _, b := range s.Buckets { + table.AddRow(b.Start, b.End, formatCount(b.Sent), formatCount(b.Delivered), formatCount(b.BouncedHard), + formatCount(b.Complaints), formatRate(b.BounceRate), formatRate(b.ComplaintRate)) + } + table.Render() +} + +func renderSendBreakdown(w io.Writer, b *domain.SendMetricsBreakdown) { + _, _ = fmt.Fprintf(w, "Grouped by: %s\nWindow: %s\n\n", b.GroupBy, windowString(b.Window)) + if b.Window == nil { + _, _ = fmt.Fprintln(w, "No data: recipient_domain breakdowns only cover the last 90 days.") + return + } + table := newTable(w, "KEY", "SENT", "DELIVERED", "HARD BOUNCES", "COMPLAINTS", "DELIVERY", "BOUNCE", "COMPLAINT") + for _, r := range b.Rows { + table.AddRow(r.Key, formatCount(r.Sent), formatCount(r.Delivered), formatCount(r.BouncedHard), formatCount(r.Complaints), + formatRate(r.DeliveryRate), formatRate(r.BounceRate), formatRate(r.ComplaintRate)) + } + table.Render() +} + +func renderTrackingSummary(w io.Writer, s *domain.TrackingMetricsSummary) { + _, _ = fmt.Fprintf(w, "Prior period: %s\n\n", windowString(s.PriorPeriod)) + t := s.Totals + totals := newTable(w, "TRACKED OPENS", "OPENED", "OPENS TOTAL", "TRACKED LINKS", "CLICKED", "CLICKS TOTAL") + totals.AddRow(formatCount(t.TrackedOpens), formatCount(t.Opened), formatCount(t.OpensTotal), + formatCount(t.TrackedLinks), formatCount(t.Clicked), formatCount(t.ClicksTotal)) + totals.Render() + _, _ = fmt.Fprintln(w) + + rates := newTable(w, "RATE", "VALUE", "CHANGE", "PRIOR") + for _, r := range []struct { + name string + tile domain.RateTile + }{{"open", s.Metrics.OpenRate}, {"click", s.Metrics.ClickRate}} { + rates.AddRow(r.name, formatRate(r.tile.Value), formatDelta(r.tile.DeltaPP), formatRate(r.tile.PriorValue)) + } + rates.Render() +} + +func renderTrackingTimeseries(w io.Writer, s *domain.TrackingMetricsTimeseries) { + _, _ = fmt.Fprintf(w, "Granularity: %s\n\n", s.Granularity) + table := newTable(w, "START", "END", "TRACKED OPENS", "OPENED", "OPEN RATE", "TRACKED LINKS", "CLICKED", "CLICK RATE") + for _, b := range s.Buckets { + table.AddRow(b.Start, b.End, formatCount(b.TrackedOpens), formatCount(b.Opened), formatRate(b.OpenRate), + formatCount(b.TrackedLinks), formatCount(b.Clicked), formatRate(b.ClickRate)) + } + table.Render() +} + +func renderTrackingBreakdown(w io.Writer, b *domain.TrackingMetricsBreakdown) { + _, _ = fmt.Fprintf(w, "Grouped by: %s\nWindow: %s\n\n", b.GroupBy, windowString(b.Window)) + table := newTable(w, "KEY", "TRACKED OPENS", "OPENED", "OPEN RATE", "TRACKED LINKS", "CLICKED", "CLICK RATE") + for _, r := range b.Rows { + table.AddRow(r.Key, formatCount(r.TrackedOpens), formatCount(r.Opened), formatRate(r.OpenRate), + formatCount(r.TrackedLinks), formatCount(r.Clicked), formatRate(r.ClickRate)) + } + table.Render() +} diff --git a/internal/cli/deliverability/send_alerts.go b/internal/cli/deliverability/send_alerts.go new file mode 100644 index 0000000..e4a0285 --- /dev/null +++ b/internal/cli/deliverability/send_alerts.go @@ -0,0 +1,204 @@ +package deliverability + +import ( + "context" + "encoding/json" + "fmt" + "strconv" + "strings" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +type alertRuleFlags struct { + metric string + threshold string + windowHours int64 + minVolume int64 +} + +func addAlertRuleFlags(cmd *cobra.Command, f *alertRuleFlags) { + cmd.Flags().StringVar(&f.metric, "metric", "", "Metric: "+strings.Join(domain.SendAlertMetrics, ", ")) + cmd.Flags().StringVar(&f.threshold, "threshold", "", + "Threshold percent, up to 2 decimals; bounce/complaint fire above it (0 to <100), delivery fires below it (>0 to 100)") + cmd.Flags().Int64Var(&f.windowHours, "window-hours", 0, "Look-back window in hours, 1-24") + cmd.Flags().Int64Var(&f.minVolume, "min-volume", 0, "Minimum sends in the window before the rule can fire (default 0)") +} + +// buildAlertRuleRequest includes only the flags the user set, so update leaves the rest unchanged. +func buildAlertRuleRequest(cmd *cobra.Command, f *alertRuleFlags) (*domain.SendAlertRuleRequest, error) { + req := &domain.SendAlertRuleRequest{} + if cmd.Flags().Changed("metric") { + req.Metric = &f.metric + } + if cmd.Flags().Changed("threshold") { + if _, err := strconv.ParseFloat(f.threshold, 64); err != nil { + return nil, common.NewUserError(fmt.Sprintf("invalid --threshold value %q", f.threshold), "Use a percentage such as 5 or 0.25") + } + n := json.Number(strings.TrimSpace(f.threshold)) + req.Threshold = &n + } + if cmd.Flags().Changed("window-hours") { + req.WindowHours = &f.windowHours + } + if cmd.Flags().Changed("min-volume") { + req.MinVolume = &f.minVolume + } + return req, nil +} + +func newSendAlertsListCmd() *cobra.Command { + return &cobra.Command{ + Use: "list", + Short: "List send alert rules", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + return withClient(func(ctx context.Context, client ports.NylasClient) error { + rules, err := client.ListSendAlertRules(ctx) + if err != nil { + return common.WrapListError("send alert rules", err) + } + if done, err := writeStructuredList(cmd, rules, rules); done { + return err + } + if len(rules) == 0 { + common.PrintEmptyStateWithHint("send alert rules", + "Create one with: nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1") + return nil + } + table := newTable(cmd.OutOrStdout(), "ID", "FIRES WHEN", "WINDOW", "MIN VOLUME", "UPDATED") + for _, r := range rules { + table.AddRow(r.ID, ruleCondition(r), fmt.Sprintf("%dh", r.WindowHours), formatCount(r.MinVolume), formatUnix(r.UpdatedAt)) + } + table.Render() + return nil + }) + }, + } +} + +func newSendAlertsShowCmd() *cobra.Command { + return &cobra.Command{ + Use: "show ", + Short: "Show a send alert rule", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + return withClient(func(ctx context.Context, client ports.NylasClient) error { + rule, err := client.GetSendAlertRule(ctx, args[0]) + if err != nil { + return common.WrapGetError("send alert rule", err) + } + return writeRule(cmd, rule) + }) + }, + } +} + +func newSendAlertsCreateCmd() *cobra.Command { + var flags alertRuleFlags + cmd := &cobra.Command{ + Use: "create", + Short: "Create a send alert rule", + Example: ` nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1 --min-volume 50 + nylas deliverability send-alerts create --metric delivery_rate --threshold 95 --window-hours 24`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + req, err := buildAlertRuleRequest(cmd, &flags) + if err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + rule, err := client.CreateSendAlertRule(ctx, req) + if err != nil { + return common.WrapCreateError("send alert rule", err) + } + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Created send alert rule %s", rule.ID) + } + return writeRule(cmd, rule) + }) + }, + } + addAlertRuleFlags(cmd, &flags) + _ = cmd.MarkFlagRequired("metric") + _ = cmd.MarkFlagRequired("threshold") + _ = cmd.MarkFlagRequired("window-hours") + return cmd +} + +func newSendAlertsUpdateCmd() *cobra.Command { + var flags alertRuleFlags + cmd := &cobra.Command{ + Use: "update ", + Short: "Change a send alert rule; flags you leave out keep their value", + Example: ` nylas deliverability send-alerts update --threshold 3`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + req, err := buildAlertRuleRequest(cmd, &flags) + if err != nil { + return err + } + if *req == (domain.SendAlertRuleRequest{}) { + return common.NewUserError("nothing to update", "Set at least one of --metric, --threshold, --window-hours, --min-volume") + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + rule, err := client.UpdateSendAlertRule(ctx, args[0], req) + if err != nil { + return common.WrapUpdateError("send alert rule", err) + } + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Updated send alert rule %s", rule.ID) + } + return writeRule(cmd, rule) + }) + }, + } + addAlertRuleFlags(cmd, &flags) + return cmd +} + +func newSendAlertsDeleteCmd() *cobra.Command { + var yes bool + cmd := &cobra.Command{ + Use: "delete ", + Short: "Delete a send alert rule", + Example: ` nylas deliverability send-alerts delete --yes`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + if !yes { + return common.NewUserError("deletion requires confirmation", "Re-run with --yes to delete the rule") + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + if err := client.DeleteSendAlertRule(ctx, args[0]); err != nil { + return common.WrapDeleteError("send alert rule", err) + } + common.PrintSuccess("Deleted send alert rule %s", args[0]) + return nil + }) + }, + } + common.AddYesFlag(cmd, &yes) + return cmd +} + +func writeRule(cmd *cobra.Command, r *domain.SendAlertRule) error { + if done, err := writeStructured(cmd, r); done { + return err + } + w := cmd.OutOrStdout() + _, _ = fmt.Fprintf(w, "ID: %s\n", r.ID) + _, _ = fmt.Fprintf(w, "Fires when: %s\n", ruleCondition(*r)) + _, _ = fmt.Fprintf(w, "Window: %d hour(s)\n", r.WindowHours) + _, _ = fmt.Fprintf(w, "Min volume: %d\n", r.MinVolume) + _, _ = fmt.Fprintf(w, "Created: %s\n", formatUnix(r.CreatedAt)) + _, _ = fmt.Fprintf(w, "Updated: %s\n", formatUnix(r.UpdatedAt)) + return nil +} + +// ruleCondition reads like "bounce_rate above 5%". +func ruleCondition(r domain.SendAlertRule) string { + return fmt.Sprintf("%s %s %s", r.Metric, r.Direction, formatThreshold(r.Threshold)) +} diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go new file mode 100644 index 0000000..c1295ae --- /dev/null +++ b/internal/cli/deliverability/send_events.go @@ -0,0 +1,208 @@ +package deliverability + +import ( + "context" + "fmt" + "strings" + "time" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +type activityWindowFlags struct { + start, end string +} + +func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { + cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD, RFC3339, or look-back like 24h/7d (default: 6 days ago, UTC midnight)") + cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive (same formats; default: now)") + cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") + common.AddLimitFlag(cmd, limit, 50) + common.AddPageTokenFlag(cmd, pageToken) +} + +func (f activityWindowFlags) resolve(now time.Time) (int64, int64, error) { + start, err := parseActivityTime("start", f.start, now) + if err != nil { + return 0, 0, err + } + end, err := parseActivityTime("end", f.end, now) + if err != nil { + return 0, 0, err + } + return start, end, nil +} + +func newSendEventsListCmd() *cobra.Command { + var window activityWindowFlags + var params domain.SendEventListParams + + cmd := &cobra.Command{ + Use: "list", + Short: "List send events (newest first)", + Example: ` nylas deliverability send-events list --event-type bounced --start 24h + nylas deliverability send-events list --recipient-domain gmail.com --event-type bounced --event-type complaint + nylas deliverability send-events list --message-id "" --json`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + var err error + if params.Start, params.End, err = window.resolve(time.Now()); err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + return runSendEventsList(ctx, cmd, client, ¶ms) + }) + }, + } + + cmd.Flags().StringArrayVar(¶ms.EventTypes, "event-type", nil, + "Event type, repeatable: accepted, delivered, bounced, complaint, rejected") + cmd.Flags().StringVar(¶ms.BounceClass, "bounce-class", "", "Bounce class: hard, soft, or undetermined") + cmd.Flags().StringVar(¶ms.SendingDomain, "sending-domain", "", "Sending domain") + cmd.Flags().StringVar(¶ms.From, "from", "", "From address") + cmd.Flags().StringVar(¶ms.GrantID, "grant-id", "", "Only events for this grant (agent account)") + cmd.Flags().StringVar(¶ms.Recipient, "recipient", "", "Recipient address") + cmd.Flags().StringVar(¶ms.RecipientDomain, "recipient-domain", "", "Recipient domain") + cmd.Flags().StringVar(¶ms.MessageID, "message-id", "", "Message ID") + cmd.Flags().StringVar(¶ms.ThreadID, "thread-id", "", "Thread ID") + addActivityWindowFlags(cmd, &window, ¶ms.Order, ¶ms.Limit, ¶ms.PageToken) + + return cmd +} + +func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.SendEventListParams) error { + resp, err := client.ListSendEvents(ctx, params) + if err != nil { + return common.WrapListError("send events", err) + } + if done, err := writeStructuredList(cmd, resp, resp.Data); done { + return err + } + if len(resp.Data) == 0 { + common.PrintEmptyStateWithHint("send events", "Widen the window with --start (activity is kept for 90 days)") + return nil + } + + table := newTable(cmd.OutOrStdout(), "TIME", "EVENT", "RECIPIENT", "FROM", "REASON", "EVENT ID") + table.SetMaxWidth(4, 40) + for _, e := range resp.Data { + table.AddRow(formatUnix(e.Timestamp), sendEventLabel(e.EventType, e.BounceClass), e.Recipient, e.From, e.Reason, e.ID) + } + table.Render() + nextCursorNote(cmd, resp.NextCursor) + return nil +} + +func newSendEventsShowCmd() *cobra.Command { + return &cobra.Command{ + Use: "show ", + Short: "Show one send event with its provider detail", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + if err := validateEventID(args[0]); err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + event, err := client.GetSendEvent(ctx, args[0]) + if err != nil { + return common.WrapGetError("send event", err) + } + if done, err := writeStructured(cmd, event); done { + return err + } + printSendEvent(cmd, event) + return nil + }) + }, + } +} + +func printSendEvent(cmd *cobra.Command, e *domain.SendEvent) { + fields := [][2]string{ + {"Event ID", e.ID}, + {"Event", sendEventLabel(e.EventType, e.BounceClass)}, + {"Time", formatUnix(e.Timestamp)}, + {"Message ID", e.MessageID}, + {"Thread ID", e.ThreadID}, + {"Grant ID", e.GrantID}, + {"From", e.From}, + {"Recipient", e.Recipient}, + {"Subject", derefString(e.Subject)}, + {"Reason", e.Reason}, + } + if d := e.Detail; d != nil { + fields = append(fields, + [2]string{"SMTP response", d.SMTPResponse}, + [2]string{"Diagnostic", d.DiagnosticCode}, + [2]string{"Bounce type", strings.TrimSpace(d.BounceType + " " + d.BounceSubtype)}, + [2]string{"Status", d.Status}, + [2]string{"Action", d.Action}, + [2]string{"Reporting MTA", d.ReportingMTA}, + [2]string{"Remote MTA IP", d.RemoteMTAIP}, + [2]string{"Feedback type", strings.TrimSpace(d.FeedbackType + " " + d.ComplaintSubtype)}, + ) + if d.ProcessingTimeMs > 0 { + fields = append(fields, [2]string{"Processing", fmt.Sprintf("%d ms", d.ProcessingTimeMs)}) + } + } + for _, f := range fields { + if f[1] != "" { + _, _ = fmt.Fprintf(cmd.OutOrStdout(), "%-15s %s\n", f[0]+":", f[1]) + } + } +} + +func newSendEventsMessageCmd() *cobra.Command { + return &cobra.Command{ + Use: "message ", + Short: "Show every recipient's send timeline for one message", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + return withClient(func(ctx context.Context, client ports.NylasClient) error { + activity, err := client.GetSendMessageActivity(ctx, args[0]) + if err != nil { + return common.WrapGetError("send activity for message", err) + } + if done, err := writeStructured(cmd, activity); done { + return err + } + printSendMessageActivity(cmd, activity) + return nil + }) + }, + } +} + +func printSendMessageActivity(cmd *cobra.Command, a *domain.SendMessageActivity) { + w := cmd.OutOrStdout() + m := a.Message + _, _ = fmt.Fprintf(w, "Message ID: %s\n", m.MessageID) + _, _ = fmt.Fprintf(w, "From: %s\n", m.From) + if m.Subject != nil { + _, _ = fmt.Fprintf(w, "Subject: %s\n", *m.Subject) + } + _, _ = fmt.Fprintf(w, "Sent: %s\n", formatUnix(m.SentAt)) + _, _ = fmt.Fprintf(w, "Last event: %s\n", formatUnix(m.LastEventAt)) + + for _, r := range a.Recipients { + _, _ = fmt.Fprintf(w, "\n%s [%s]\n", r.Recipient, sendEventLabel(r.CurrentStatus, r.BounceClass)) + for _, e := range r.Events { + line := fmt.Sprintf(" %s %-18s", formatUnix(e.Timestamp), sendEventLabel(e.EventType, e.BounceClass)) + if e.Reason != "" { + line += " " + e.Reason + } + _, _ = fmt.Fprintln(w, line) + } + } +} + +// sendEventLabel shows the bounce class next to bounced events. +func sendEventLabel(eventType, bounceClass string) string { + if bounceClass == "" { + return eventType + } + return eventType + " (" + bounceClass + ")" +} diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go new file mode 100644 index 0000000..9ec977d --- /dev/null +++ b/internal/cli/deliverability/tracking_events.go @@ -0,0 +1,198 @@ +package deliverability + +import ( + "context" + "fmt" + "time" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +func newTrackingEventsListCmd() *cobra.Command { + var window activityWindowFlags + var params domain.TrackingEventListParams + + cmd := &cobra.Command{ + Use: "list", + Short: "List opens and link clicks (newest first)", + Example: ` nylas deliverability tracking-events list --event-type link_clicked --start 7d + nylas deliverability tracking-events list --label welcome-campaign --json`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + var err error + if params.Start, params.End, err = window.resolve(time.Now()); err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + return runTrackingEventsList(ctx, cmd, client, ¶ms) + }) + }, + } + + cmd.Flags().StringArrayVar(¶ms.EventTypes, "event-type", nil, "Event type, repeatable: opened, link_clicked") + cmd.Flags().StringVar(¶ms.SendingDomain, "sending-domain", "", "Sending domain") + cmd.Flags().StringVar(¶ms.From, "from", "", "From address") + cmd.Flags().StringVar(¶ms.GrantID, "grant-id", "", "Only events for this grant (agent account)") + cmd.Flags().StringVar(¶ms.MessageID, "message-id", "", "Message ID") + cmd.Flags().StringVar(¶ms.ThreadID, "thread-id", "", "Thread ID") + cmd.Flags().StringVar(¶ms.Label, "label", "", "Tracking label set when the message was sent") + addActivityWindowFlags(cmd, &window, ¶ms.Order, ¶ms.Limit, ¶ms.PageToken) + + return cmd +} + +func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.TrackingEventListParams) error { + resp, err := client.ListTrackingEvents(ctx, params) + if err != nil { + return common.WrapListError("tracking events", err) + } + if done, err := writeStructuredList(cmd, resp, resp.Data); done { + return err + } + if len(resp.Data) == 0 { + common.PrintEmptyStateWithHint("tracking events", "Widen the window with --start (activity is kept for 90 days)") + return nil + } + + table := newTable(cmd.OutOrStdout(), "TIME", "EVENT", "FIRST", "FROM", "LABEL", "URL", "EVENT ID") + table.SetMaxWidth(5, 40) + for _, e := range resp.Data { + table.AddRow(formatUnix(e.Timestamp), e.EventType, yesNo(e.IsFirst), e.From, e.Label, derefString(e.URL), e.ID) + } + table.Render() + nextCursorNote(cmd, resp.NextCursor) + return nil +} + +func newTrackingEventsShowCmd() *cobra.Command { + return &cobra.Command{ + Use: "show ", + Short: "Show one open or link click", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + if err := validateEventID(args[0]); err != nil { + return err + } + return withClient(func(ctx context.Context, client ports.NylasClient) error { + event, err := client.GetTrackingEvent(ctx, args[0]) + if err != nil { + return common.WrapGetError("tracking event", err) + } + if done, err := writeStructured(cmd, event); done { + return err + } + printTrackingEvent(cmd, event) + return nil + }) + }, + } +} + +func printTrackingEvent(cmd *cobra.Command, e *domain.TrackingEvent) { + w := cmd.OutOrStdout() + _, _ = fmt.Fprintf(w, "Event ID: %s\n", e.ID) + _, _ = fmt.Fprintf(w, "Event: %s\n", e.EventType) + _, _ = fmt.Fprintf(w, "Time: %s\n", formatUnix(e.Timestamp)) + _, _ = fmt.Fprintf(w, "First: %s\n", yesNo(e.IsFirst)) + _, _ = fmt.Fprintf(w, "Message ID: %s\n", e.MessageID) + _, _ = fmt.Fprintf(w, "From: %s\n", e.From) + if e.Label != "" { + _, _ = fmt.Fprintf(w, "Label: %s\n", e.Label) + } + if e.URL != nil { + _, _ = fmt.Fprintf(w, "URL: %s\n", *e.URL) + } + if e.LinkIndex != nil { + _, _ = fmt.Fprintf(w, "Link index: %d\n", *e.LinkIndex) + } + if e.IP != "" { + _, _ = fmt.Fprintf(w, "IP: %s\n", e.IP) + } + if e.UserAgent != "" { + _, _ = fmt.Fprintf(w, "User agent: %s\n", e.UserAgent) + } +} + +func newTrackingEventsMessageCmd() *cobra.Command { + return &cobra.Command{ + Use: "message ", + Short: "Show open and click totals and the newest 100 interactions for one message", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + return withClient(func(ctx context.Context, client ports.NylasClient) error { + activity, err := client.GetTrackingMessageActivity(ctx, args[0]) + if err != nil { + return common.WrapGetError("tracking activity for message", err) + } + if done, err := writeStructured(cmd, activity); done { + return err + } + printTrackingMessageActivity(cmd, activity) + return nil + }) + }, + } +} + +func printTrackingMessageActivity(cmd *cobra.Command, a *domain.TrackingMessageActivity) { + w := cmd.OutOrStdout() + _, _ = fmt.Fprintf(w, "Message ID: %s\n", a.MessageID) + _, _ = fmt.Fprintf(w, "From: %s\n", a.From) + if a.Label != "" { + _, _ = fmt.Fprintf(w, "Label: %s\n", a.Label) + } + _, _ = fmt.Fprintf(w, "Tracking: opens %s, links %s\n", onOff(a.Tracking.Opens), onOff(a.Tracking.Links)) + _, _ = fmt.Fprintf(w, "Opens: %d%s\n", a.Opens.Total, totalsRange(a.Opens)) + _, _ = fmt.Fprintf(w, "Clicks: %d%s\n", a.Clicks.Total, totalsRange(a.Clicks.TrackingTotals)) + + if len(a.Clicks.Links) > 0 { + _, _ = fmt.Fprintln(w) + table := newTable(w, "LINK", "URL", "CLICKS") + table.AlignRight(2) + for _, l := range a.Clicks.Links { + table.AddRow(formatCount(l.LinkIndex), l.URL, formatCount(l.Clicks)) + } + table.Render() + } + + if len(a.Events) > 0 { + _, _ = fmt.Fprintln(w) + table := newTable(w, "TIME", "EVENT", "FIRST", "URL", "USER AGENT") + table.SetMaxWidth(3, 40).SetMaxWidth(4, 40) + for _, e := range a.Events { + table.AddRow(formatUnix(e.Timestamp), e.EventType, yesNo(e.IsFirst), derefString(e.URL), e.UserAgent) + } + table.Render() + } +} + +func totalsRange(t domain.TrackingTotals) string { + if t.FirstAt == nil || t.LastAt == nil { + return "" + } + return fmt.Sprintf(" (first %s, last %s)", formatUnix(*t.FirstAt), formatUnix(*t.LastAt)) +} + +func yesNo(b bool) string { + if b { + return "yes" + } + return "no" +} + +func onOff(b bool) string { + if b { + return "on" + } + return "off" +} + +func derefString(s *string) string { + if s == nil { + return "" + } + return *s +} diff --git a/internal/cli/integration/deliverability_test.go b/internal/cli/integration/deliverability_test.go new file mode 100644 index 0000000..8439c95 --- /dev/null +++ b/internal/cli/integration/deliverability_test.go @@ -0,0 +1,171 @@ +//go:build integration +// +build integration + +package integration + +import ( + "encoding/json" + "strings" + "testing" + + "github.com/nylas/cli/internal/domain" +) + +// skipIfMissingAppCreds skips tests of application-level routes, which need an API key but no grant. +func skipIfMissingAppCreds(t *testing.T) { + t.Helper() + if testBinary == "" { + t.Skip("CLI binary not found - run 'go build -o bin/nylas ./cmd/nylas' first") + } + if testAPIKey == "" { + t.Skip("NYLAS_API_KEY not set") + } +} + +func TestCLI_DeliverabilityHelp(t *testing.T) { + if testBinary == "" { + t.Skip("CLI binary not found") + } + + stdout, stderr, err := runCLI("deliverability", "--help") + if err != nil { + t.Fatalf("deliverability --help failed: %v\nstderr: %s", err, stderr) + } + for _, expected := range []string{"send-events", "tracking-events", "send-alerts"} { + if !strings.Contains(stdout, expected) { + t.Fatalf("expected help output to contain %q, got: %s", expected, stdout) + } + } +} + +// TestCLI_DeliverabilityReads checks each read command decodes a live response. The app may have no +// recent sends, so the tests assert response shape, not content. +func TestCLI_DeliverabilityReads(t *testing.T) { + skipIfMissingAppCreds(t) + + tests := []struct { + name string + args []string + decode any + check func(t *testing.T, v any) + }{ + {"send-events list", []string{"deliverability", "send-events", "list", "--limit", "5", "--json"}, + &domain.SendEventListResponse{}, func(t *testing.T, v any) { + if v.(*domain.SendEventListResponse).Data == nil { + t.Fatal("send events list has no data array") + } + }}, + {"tracking-events list", []string{"deliverability", "tracking-events", "list", "--limit", "5", "--json"}, + &domain.TrackingEventListResponse{}, func(t *testing.T, v any) { + if v.(*domain.TrackingEventListResponse).Data == nil { + t.Fatal("tracking events list has no data array") + } + }}, + {"send-events summary", []string{"deliverability", "send-events", "summary", "--json"}, + &domain.SendMetricsSummary{}, func(t *testing.T, v any) { + if v.(*domain.SendMetricsSummary).Health.State == "" { + t.Fatal("send summary has no health state") + } + }}, + {"send-events timeseries", []string{"deliverability", "send-events", "timeseries", "--json"}, + &domain.SendMetricsTimeseries{}, func(t *testing.T, v any) { + // The default 7-day window resolves to daily buckets, one per day, empty or not. + s := v.(*domain.SendMetricsTimeseries) + if s.Granularity != "day" || len(s.Buckets) != 7 { + t.Fatalf("expected 7 daily buckets, got %q with %d", s.Granularity, len(s.Buckets)) + } + }}, + {"send-events breakdown", []string{"deliverability", "send-events", "breakdown", "--json"}, + &domain.SendMetricsBreakdown{}, func(t *testing.T, v any) { + if v.(*domain.SendMetricsBreakdown).GroupBy != "sending_domain" { + t.Fatal("send breakdown did not default to sending_domain") + } + }}, + {"tracking-events summary", []string{"deliverability", "tracking-events", "summary", "--json"}, + &domain.TrackingMetricsSummary{}, func(t *testing.T, v any) {}}, + {"tracking-events breakdown", []string{"deliverability", "tracking-events", "breakdown", "--group-by", "agent_account", "--json"}, + &domain.TrackingMetricsBreakdown{}, func(t *testing.T, v any) { + if v.(*domain.TrackingMetricsBreakdown).GroupBy != "agent_account" { + t.Fatal("tracking breakdown ignored --group-by") + } + }}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + acquireRateLimit(t) + stdout, stderr, err := runCLI(tt.args...) + if err != nil { + t.Fatalf("%s failed: %v\nstderr: %s", tt.name, err, stderr) + } + if err := json.Unmarshal([]byte(stdout), tt.decode); err != nil { + t.Fatalf("%s returned invalid JSON: %v\n%s", tt.name, err, stdout) + } + tt.check(t, tt.decode) + }) + } +} + +func TestCLI_SendAlertRuleLifecycle(t *testing.T) { + skipIfMissingAppCreds(t) + + acquireRateLimit(t) + stdout, stderr, err := runCLI("deliverability", "send-alerts", "list", "--json") + if err != nil { + t.Fatalf("send-alerts list failed: %v\nstderr: %s", err, stderr) + } + var existing []domain.SendAlertRule + if err := json.Unmarshal([]byte(stdout), &existing); err != nil { + t.Fatalf("send-alerts list returned invalid JSON: %v\n%s", err, stdout) + } + if len(existing) >= 20 { + t.Skip("application already has the maximum of 20 send alert rules") + } + + acquireRateLimit(t) + stdout, stderr, err = runCLI("deliverability", "send-alerts", "create", + "--metric", "bounce_rate", "--threshold", "99.5", "--window-hours", "24", "--min-volume", "1000000", "--json") + if err != nil { + t.Fatalf("send-alerts create failed: %v\nstderr: %s", err, stderr) + } + var created domain.SendAlertRule + if err := json.Unmarshal([]byte(stdout), &created); err != nil { + t.Fatalf("send-alerts create returned invalid JSON: %v\n%s", err, stdout) + } + t.Cleanup(func() { + acquireRateLimit(t) + _, _, _ = runCLI("deliverability", "send-alerts", "delete", created.ID, "--yes") + }) + if created.Direction != "above" || created.Threshold != 99.5 || created.WindowHours != 24 { + t.Fatalf("created rule does not match flags: %+v", created) + } + + // A partial update must change only the given field and keep the rest. + acquireRateLimit(t) + stdout, stderr, err = runCLI("deliverability", "send-alerts", "update", created.ID, "--threshold", "98.25", "--json") + if err != nil { + t.Fatalf("send-alerts update failed: %v\nstderr: %s", err, stderr) + } + var updated domain.SendAlertRule + if err := json.Unmarshal([]byte(stdout), &updated); err != nil { + t.Fatalf("send-alerts update returned invalid JSON: %v\n%s", err, stdout) + } + if updated.Threshold != 98.25 || updated.WindowHours != 24 || updated.MinVolume != 1000000 { + t.Fatalf("partial update changed other fields: %+v", updated) + } + + acquireRateLimit(t) + if _, stderr, err := runCLI("deliverability", "send-alerts", "show", created.ID); err != nil { + t.Fatalf("send-alerts show failed: %v\nstderr: %s", err, stderr) + } + + acquireRateLimit(t) + if _, stderr, err := runCLI("deliverability", "send-alerts", "delete", created.ID, "--yes"); err != nil { + t.Fatalf("send-alerts delete failed: %v\nstderr: %s", err, stderr) + } + + acquireRateLimit(t) + if _, _, err := runCLI("deliverability", "send-alerts", "show", created.ID); err == nil { + t.Fatal("deleted rule can still be shown") + } +} diff --git a/internal/domain/deliverability_activity.go b/internal/domain/deliverability_activity.go new file mode 100644 index 0000000..52b5155 --- /dev/null +++ b/internal/domain/deliverability_activity.go @@ -0,0 +1,204 @@ +package domain + +// Send event types accepted by GET /v3/activity/send. +var SendEventTypes = []string{"accepted", "delivered", "bounced", "complaint", "rejected"} + +// Tracking event types accepted by GET /v3/activity/tracking. +var TrackingEventTypes = []string{"opened", "link_clicked"} + +// SendEventListParams filters GET /v3/activity/send. Start and End are Unix seconds. +type SendEventListParams struct { + EventTypes []string + BounceClass string + SendingDomain string + From string + GrantID string + Recipient string + RecipientDomain string + MessageID string + ThreadID string + Start int64 + End int64 + Order string + Limit int + PageToken string +} + +// TrackingEventListParams filters GET /v3/activity/tracking. Start and End are Unix seconds. +type TrackingEventListParams struct { + EventTypes []string + SendingDomain string + From string + GrantID string + MessageID string + ThreadID string + Label string + Start int64 + End int64 + Order string + Limit int + PageToken string +} + +// SendEventDetail carries provider (SES) detail for a send event. +type SendEventDetail struct { + SMTPResponse string `json:"smtp_response,omitempty"` + ProcessingTimeMs int64 `json:"processing_time_ms,omitempty"` + ReportingMTA string `json:"reporting_mta,omitempty"` + RemoteMTAIP string `json:"remote_mta_ip,omitempty"` + BounceType string `json:"bounce_type,omitempty"` + BounceSubtype string `json:"bounce_subtype,omitempty"` + Status string `json:"status,omitempty"` + Action string `json:"action,omitempty"` + DiagnosticCode string `json:"diagnostic_code,omitempty"` + FeedbackType string `json:"feedback_type,omitempty"` + ComplaintSubtype string `json:"complaint_subtype,omitempty"` +} + +// SendEvent is one row of the send activity feed. +type SendEvent struct { + ID string `json:"id"` + EventType string `json:"event_type"` + BounceClass string `json:"bounce_class,omitempty"` + Timestamp int64 `json:"timestamp"` + ApplicationID string `json:"application_id"` + GrantID string `json:"grant_id"` + MessageID string `json:"message_id"` + ThreadID string `json:"thread_id"` + From string `json:"from"` + SendingDomain string `json:"sending_domain"` + Recipient string `json:"recipient"` + RecipientDomain string `json:"recipient_domain"` + Subject *string `json:"subject,omitempty"` + Reason string `json:"reason"` + Detail *SendEventDetail `json:"detail,omitempty"` +} + +// QuietField returns the event ID for quiet output. +func (e SendEvent) QuietField() string { return e.ID } + +// SendEventListResponse is one page of the send activity feed. +type SendEventListResponse struct { + Data []SendEvent `json:"data"` + NextCursor string `json:"next_cursor,omitempty"` + RequestID string `json:"request_id,omitempty"` +} + +// SendMessageEnvelope describes the message in a per-message send view. +type SendMessageEnvelope struct { + MessageID string `json:"message_id"` + ThreadID string `json:"thread_id"` + GrantID string `json:"grant_id"` + ApplicationID string `json:"application_id"` + From string `json:"from"` + SendingDomain string `json:"sending_domain"` + Subject *string `json:"subject,omitempty"` + SentAt int64 `json:"sent_at"` + LastEventAt int64 `json:"last_event_at"` +} + +// SendTimelineEvent is one event in a recipient's timeline. +type SendTimelineEvent struct { + ID string `json:"id"` + EventType string `json:"event_type"` + Timestamp int64 `json:"timestamp"` + BounceClass string `json:"bounce_class,omitempty"` + Reason string `json:"reason"` + Detail *SendEventDetail `json:"detail,omitempty"` +} + +// SendMessageRecipient is one recipient's status and timeline. +type SendMessageRecipient struct { + Recipient string `json:"recipient"` + RecipientDomain string `json:"recipient_domain"` + CurrentStatus string `json:"current_status"` + BounceClass string `json:"bounce_class,omitempty"` + Events []SendTimelineEvent `json:"events"` +} + +// SendMessageActivity is the response of GET /v3/activity/send/messages/{message_id}. +type SendMessageActivity struct { + Message SendMessageEnvelope `json:"message"` + Recipients []SendMessageRecipient `json:"recipients"` +} + +// TrackingEvent is one row of the tracking activity feed. +type TrackingEvent struct { + ID string `json:"id"` + EventType string `json:"event_type"` + Timestamp int64 `json:"timestamp"` + ApplicationID string `json:"application_id"` + GrantID string `json:"grant_id"` + MessageID string `json:"message_id"` + ThreadID string `json:"thread_id"` + From string `json:"from"` + SendingDomain string `json:"sending_domain"` + Label string `json:"label"` + IsFirst bool `json:"is_first"` + URL *string `json:"url,omitempty"` + LinkIndex *int64 `json:"link_index,omitempty"` + IP string `json:"ip"` + UserAgent string `json:"user_agent"` +} + +// QuietField returns the event ID for quiet output. +func (e TrackingEvent) QuietField() string { return e.ID } + +// TrackingEventListResponse is one page of the tracking activity feed. +type TrackingEventListResponse struct { + Data []TrackingEvent `json:"data"` + NextCursor string `json:"next_cursor,omitempty"` + RequestID string `json:"request_id,omitempty"` +} + +// TrackingFlags reports which tracking was enabled for a message. +type TrackingFlags struct { + Opens bool `json:"opens"` + Links bool `json:"links"` +} + +// TrackingTotals counts interactions; FirstAt and LastAt are nil when Total is 0. +type TrackingTotals struct { + Total int64 `json:"total"` + FirstAt *int64 `json:"first_at"` + LastAt *int64 `json:"last_at"` +} + +// TrackingLinkClicks counts clicks on one tracked link. +type TrackingLinkClicks struct { + LinkIndex int64 `json:"link_index"` + URL string `json:"url"` + Clicks int64 `json:"clicks"` +} + +// TrackingClickTotals counts clicks overall and per link. +type TrackingClickTotals struct { + TrackingTotals + Links []TrackingLinkClicks `json:"links"` +} + +// TrackingInteraction is one open or click in a per-message tracking view. +type TrackingInteraction struct { + ID string `json:"id"` + EventType string `json:"event_type"` + Timestamp int64 `json:"timestamp"` + IsFirst bool `json:"is_first"` + URL *string `json:"url,omitempty"` + LinkIndex *int64 `json:"link_index,omitempty"` + IP string `json:"ip"` + UserAgent string `json:"user_agent"` +} + +// TrackingMessageActivity is the response of GET /v3/activity/tracking/messages/{message_id}. +type TrackingMessageActivity struct { + MessageID string `json:"message_id"` + ThreadID string `json:"thread_id"` + GrantID string `json:"grant_id"` + From string `json:"from"` + SendingDomain string `json:"sending_domain"` + Label string `json:"label"` + Tracking TrackingFlags `json:"tracking"` + Opens TrackingTotals `json:"opens"` + Clicks TrackingClickTotals `json:"clicks"` + Events []TrackingInteraction `json:"events"` +} diff --git a/internal/domain/deliverability_alerts.go b/internal/domain/deliverability_alerts.go new file mode 100644 index 0000000..c8ba86f --- /dev/null +++ b/internal/domain/deliverability_alerts.go @@ -0,0 +1,31 @@ +package domain + +import "encoding/json" + +// SendAlertMetrics are the metrics a send alert rule can watch. +var SendAlertMetrics = []string{"bounce_rate", "complaint_rate", "delivery_rate"} + +// SendAlertRule is a send alert rule. Direction is "below" for delivery_rate and "above" otherwise. +type SendAlertRule struct { + ID string `json:"id"` + ApplicationID string `json:"application_id"` + Metric string `json:"metric"` + Direction string `json:"direction"` + Threshold float64 `json:"threshold"` + WindowHours int64 `json:"window_hours"` + MinVolume int64 `json:"min_volume"` + CreatedAt int64 `json:"created_at"` + UpdatedAt int64 `json:"updated_at"` +} + +// QuietField returns the rule ID for quiet output. +func (r SendAlertRule) QuietField() string { return r.ID } + +// SendAlertRuleRequest is the body of POST and PUT /v3/alerts/send. Nil fields are left out, +// so PUT updates only the fields that are set. Threshold keeps the caller's exact decimals. +type SendAlertRuleRequest struct { + Metric *string `json:"metric,omitempty"` + Threshold *json.Number `json:"threshold,omitempty"` + WindowHours *int64 `json:"window_hours,omitempty"` + MinVolume *int64 `json:"min_volume,omitempty"` +} diff --git a/internal/domain/deliverability_metrics.go b/internal/domain/deliverability_metrics.go new file mode 100644 index 0000000..31e6509 --- /dev/null +++ b/internal/domain/deliverability_metrics.go @@ -0,0 +1,188 @@ +package domain + +// MetricsGranularities are the timeseries bucket sizes the API accepts. +var MetricsGranularities = []string{"auto", "day", "week", "month"} + +// SendMetricsGroupBy are the send breakdown dimensions. +var SendMetricsGroupBy = []string{"sending_domain", "agent_account", "recipient_domain"} + +// TrackingMetricsGroupBy are the tracking breakdown dimensions. +var TrackingMetricsGroupBy = []string{"sending_domain", "agent_account"} + +// MetricsParams configures the /v3/metrics routes. Start and End are YYYY-MM-DD (UTC, inclusive). +type MetricsParams struct { + Start string + End string + SendingDomain string + Granularity string // timeseries only + GroupBy string // breakdown only + Sort string // breakdown only, ":" + Limit int // breakdown only +} + +// MetricsWindow is an inclusive UTC date range. +type MetricsWindow struct { + Start string `json:"start"` + End string `json:"end"` +} + +// SendCounts are send outcome counts. +type SendCounts struct { + Sent int64 `json:"sent"` + Delivered int64 `json:"delivered"` + BouncedHard int64 `json:"bounced_hard"` + BouncedSoft int64 `json:"bounced_soft"` + BouncedUndetermined int64 `json:"bounced_undetermined"` + Rejected int64 `json:"rejected"` + Complaints int64 `json:"complaints"` +} + +// RateTile is a percentage with its change against the prior period. Nil means no data. +type RateTile struct { + Value *float64 `json:"value"` + DeltaPP *float64 `json:"delta_pp"` + PriorValue *float64 `json:"prior_value"` +} + +// GradedRateTile is a RateTile with a health status: ok, warn, crit or nil. +type GradedRateTile struct { + RateTile + Status *string `json:"status"` +} + +// SendHealthEvidence is the data behind a health finding. +type SendHealthEvidence struct { + Metric string `json:"metric"` + Value float64 `json:"value"` + Threshold float64 `json:"threshold"` + Dimension string `json:"dimension"` + DimensionValue string `json:"dimension_value"` + ShareOfExcess *float64 `json:"share_of_excess,omitempty"` + Day *string `json:"day,omitempty"` + BaselineValue *float64 `json:"baseline_value,omitempty"` + Totals SendCounts `json:"totals"` + Window MetricsWindow `json:"window"` +} + +// SendHealthFinding explains an at_risk or critical health state. +type SendHealthFinding struct { + Rule string `json:"rule"` + Severity string `json:"severity"` + Title string `json:"title"` + Evidence SendHealthEvidence `json:"evidence"` + Recommendation string `json:"recommendation"` + LogsFilter map[string]any `json:"logs_filter"` +} + +// SendHealth grades the last 7 days, whatever window was requested. +type SendHealth struct { + State string `json:"state"` + Window MetricsWindow `json:"window"` + MinAssessVolume int64 `json:"min_assess_volume"` + Findings []SendHealthFinding `json:"findings"` +} + +// SendRateTiles are the three graded send rates. +type SendRateTiles struct { + DeliveryRate GradedRateTile `json:"delivery_rate"` + BounceRate GradedRateTile `json:"bounce_rate"` + ComplaintRate GradedRateTile `json:"complaint_rate"` +} + +// SendMetricsSummary is the response of GET /v3/metrics/send/summary. +type SendMetricsSummary struct { + Health SendHealth `json:"health"` + Totals SendCounts `json:"totals"` + Metrics SendRateTiles `json:"metrics"` + PriorPeriod *MetricsWindow `json:"prior_period"` +} + +// SendMetricsBucket is one timeseries bucket of send counts. +type SendMetricsBucket struct { + Start string `json:"start"` + End string `json:"end"` + SendCounts + BounceRate *float64 `json:"bounce_rate"` + ComplaintRate *float64 `json:"complaint_rate"` +} + +// SendMetricsTimeseries is the response of GET /v3/metrics/send/timeseries. +type SendMetricsTimeseries struct { + Granularity string `json:"granularity"` + Buckets []SendMetricsBucket `json:"buckets"` +} + +// SendMetricsRow is one breakdown row; Key is "(others)" when IsOthers is true. +type SendMetricsRow struct { + Key string `json:"key"` + Sent int64 `json:"sent"` + Delivered int64 `json:"delivered"` + BouncedHard int64 `json:"bounced_hard"` + Complaints int64 `json:"complaints"` + DeliveryRate *float64 `json:"delivery_rate"` + BounceRate *float64 `json:"bounce_rate"` + ComplaintRate *float64 `json:"complaint_rate"` + IsOthers bool `json:"is_others"` +} + +// SendMetricsBreakdown is the response of GET /v3/metrics/send. Window is nil when +// a recipient_domain breakdown falls entirely outside the last 90 days. +type SendMetricsBreakdown struct { + GroupBy string `json:"group_by"` + Window *MetricsWindow `json:"window"` + Rows []SendMetricsRow `json:"rows"` +} + +// EngagementCounts are tracking counts; Opened and Clicked count first interactions. +type EngagementCounts struct { + TrackedOpens int64 `json:"tracked_opens"` + TrackedLinks int64 `json:"tracked_links"` + Opened int64 `json:"opened"` + Clicked int64 `json:"clicked"` + OpensTotal int64 `json:"opens_total"` + ClicksTotal int64 `json:"clicks_total"` +} + +// EngagementRateTiles are the open and click rate tiles. +type EngagementRateTiles struct { + OpenRate RateTile `json:"open_rate"` + ClickRate RateTile `json:"click_rate"` +} + +// TrackingMetricsSummary is the response of GET /v3/metrics/tracking/summary. +type TrackingMetricsSummary struct { + Totals EngagementCounts `json:"totals"` + Metrics EngagementRateTiles `json:"metrics"` + PriorPeriod *MetricsWindow `json:"prior_period"` +} + +// TrackingMetricsBucket is one timeseries bucket of engagement counts. +type TrackingMetricsBucket struct { + Start string `json:"start"` + End string `json:"end"` + EngagementCounts + OpenRate *float64 `json:"open_rate"` + ClickRate *float64 `json:"click_rate"` +} + +// TrackingMetricsTimeseries is the response of GET /v3/metrics/tracking/timeseries. +type TrackingMetricsTimeseries struct { + Granularity string `json:"granularity"` + Buckets []TrackingMetricsBucket `json:"buckets"` +} + +// TrackingMetricsRow is one breakdown row; Key is "(others)" when IsOthers is true. +type TrackingMetricsRow struct { + Key string `json:"key"` + EngagementCounts + OpenRate *float64 `json:"open_rate"` + ClickRate *float64 `json:"click_rate"` + IsOthers bool `json:"is_others"` +} + +// TrackingMetricsBreakdown is the response of GET /v3/metrics/tracking. +type TrackingMetricsBreakdown struct { + GroupBy string `json:"group_by"` + Window *MetricsWindow `json:"window"` + Rows []TrackingMetricsRow `json:"rows"` +} diff --git a/internal/ports/deliverability.go b/internal/ports/deliverability.go new file mode 100644 index 0000000..327e6ac --- /dev/null +++ b/internal/ports/deliverability.go @@ -0,0 +1,31 @@ +package ports + +import ( + "context" + + "github.com/nylas/cli/internal/domain" +) + +// DeliverabilityClient reads send and tracking activity and metrics, and manages send alert rules. +// Every route is application-level: it needs an API key and rejects grant tokens. +type DeliverabilityClient interface { + ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) + GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) + GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) + ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) + GetTrackingEvent(ctx context.Context, eventID string) (*domain.TrackingEvent, error) + GetTrackingMessageActivity(ctx context.Context, messageID string) (*domain.TrackingMessageActivity, error) + + GetSendMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsSummary, error) + GetSendMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsTimeseries, error) + GetSendMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.SendMetricsBreakdown, error) + GetTrackingMetricsSummary(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsSummary, error) + GetTrackingMetricsTimeseries(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsTimeseries, error) + GetTrackingMetricsBreakdown(ctx context.Context, params *domain.MetricsParams) (*domain.TrackingMetricsBreakdown, error) + + ListSendAlertRules(ctx context.Context) ([]domain.SendAlertRule, error) + GetSendAlertRule(ctx context.Context, ruleID string) (*domain.SendAlertRule, error) + CreateSendAlertRule(ctx context.Context, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) + UpdateSendAlertRule(ctx context.Context, ruleID string, req *domain.SendAlertRuleRequest) (*domain.SendAlertRule, error) + DeleteSendAlertRule(ctx context.Context, ruleID string) error +} diff --git a/internal/ports/nylas.go b/internal/ports/nylas.go index e7f39b8..ef0ee8b 100644 --- a/internal/ports/nylas.go +++ b/internal/ports/nylas.go @@ -25,6 +25,7 @@ type NylasClient interface { AdminClient TransactionalClient TemplateWorkflowClient + DeliverabilityClient // Configuration methods SetRegion(region string) From cddeeda3d1efb6d401c4b5ba9fd6c46a6820b227 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 12:06:03 -0500 Subject: [PATCH 2/8] [TW-8105] Address review: UTC activity dates, threshold validation, direct client helper - Activity --start/--end accept a bare YYYY-MM-DD as a UTC day (--end is the day's last second); zoneless times are UTC; non-positive look-backs are rejected. - --threshold must be a plain JSON number, so values like .5 or NaN fail with an input error instead of a marshal error. - send-alerts delete prints no text under --json/--format yaml. - Call common.WithClientNoGrant directly instead of a package-local wrapper. - Reuse QueryBuilder.AddInt64, normalise nil MetricsParams once, fix demo event IDs. Co-Authored-By: Claude Opus 5.5 --- docs/commands/deliverability.md | 2 +- .../adapters/nylas/deliverability_activity.go | 15 ++--- .../adapters/nylas/deliverability_metrics.go | 29 +++++----- .../adapters/nylas/demo_deliverability.go | 14 ++++- .../cli/deliverability/deliverability_test.go | 58 +++++++++++++++++++ internal/cli/deliverability/helpers.go | 42 ++++++++------ internal/cli/deliverability/metrics.go | 5 +- internal/cli/deliverability/send_alerts.go | 49 +++++++++------- internal/cli/deliverability/send_events.go | 31 +++++----- .../cli/deliverability/tracking_events.go | 23 ++++---- 10 files changed, 174 insertions(+), 94 deletions(-) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 9acf0bf..38eb289 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -21,7 +21,7 @@ The two kinds of command take different time formats: | `list` (activity) | Unix timestamp, `YYYY-MM-DD`, RFC3339, or a look-back such as `24h`, `7d`, `2w` | UTC midnight 6 days ago → now | 90 days. An older start is moved to 90 days ago. | | `summary`, `timeseries`, `breakdown` (metrics) | UTC date, `YYYY-MM-DD`, both days included | `--end` = today, `--start` = 6 days before `--end` | 365 days | -A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". +A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, a time without a zone is UTC, and a bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. --- diff --git a/internal/adapters/nylas/deliverability_activity.go b/internal/adapters/nylas/deliverability_activity.go index 10ffb25..297e7be 100644 --- a/internal/adapters/nylas/deliverability_activity.go +++ b/internal/adapters/nylas/deliverability_activity.go @@ -3,7 +3,6 @@ package nylas import ( "context" "net/url" - "strconv" "github.com/nylas/cli/internal/domain" ) @@ -113,12 +112,10 @@ func (c *HTTPClient) GetTrackingMessageActivity(ctx context.Context, messageID s // activityWindowQuery adds the window and paging params shared by both feeds; zero means server default. func activityWindowQuery(start, end int64, order string, limit int, pageToken string) *QueryBuilder { - qb := NewQueryBuilder() - if start != 0 { - qb.Add("start", strconv.FormatInt(start, 10)) - } - if end != 0 { - qb.Add("end", strconv.FormatInt(end, 10)) - } - return qb.Add("order", order).AddInt("limit", limit).Add("page_token", pageToken) + return NewQueryBuilder(). + AddInt64("start", start). + AddInt64("end", end). + Add("order", order). + AddInt("limit", limit). + Add("page_token", pageToken) } diff --git a/internal/adapters/nylas/deliverability_metrics.go b/internal/adapters/nylas/deliverability_metrics.go index 98b7c64..34c07c1 100644 --- a/internal/adapters/nylas/deliverability_metrics.go +++ b/internal/adapters/nylas/deliverability_metrics.go @@ -47,28 +47,25 @@ func getMetrics[T any](ctx context.Context, c *HTTPClient, queryURL string) (*T, return &result.Data, nil } +// metricsWindowQuery adds the window params every metrics route takes. func metricsWindowQuery(params *domain.MetricsParams) *QueryBuilder { - if params == nil { - params = &domain.MetricsParams{} - } - return NewQueryBuilder(). - Add("start", params.Start). - Add("end", params.End). - Add("sending_domain", params.SendingDomain) + p := orEmptyMetricsParams(params) + return NewQueryBuilder().Add("start", p.Start).Add("end", p.End).Add("sending_domain", p.SendingDomain) } func metricsTimeseriesURL(base string, params *domain.MetricsParams) string { - qb := metricsWindowQuery(params) - if params != nil { - qb.Add("granularity", params.Granularity) - } - return qb.BuildURL(base) + p := orEmptyMetricsParams(params) + return metricsWindowQuery(p).Add("granularity", p.Granularity).BuildURL(base) } func metricsBreakdownURL(base string, params *domain.MetricsParams) string { - qb := metricsWindowQuery(params) - if params != nil { - qb.Add("group_by", params.GroupBy).Add("sort", params.Sort).AddInt("limit", params.Limit) + p := orEmptyMetricsParams(params) + return metricsWindowQuery(p).Add("group_by", p.GroupBy).Add("sort", p.Sort).AddInt("limit", p.Limit).BuildURL(base) +} + +func orEmptyMetricsParams(params *domain.MetricsParams) *domain.MetricsParams { + if params == nil { + return &domain.MetricsParams{} } - return qb.BuildURL(base) + return params } diff --git a/internal/adapters/nylas/demo_deliverability.go b/internal/adapters/nylas/demo_deliverability.go index 8d9dfb0..b635e7f 100644 --- a/internal/adapters/nylas/demo_deliverability.go +++ b/internal/adapters/nylas/demo_deliverability.go @@ -13,6 +13,8 @@ const ( demoDeliverabilityFrom = "agent@mail.example.com" demoDeliverabilityMsgID = "" demoSendEventID = "5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f" + demoAcceptedEventID = "e7f9b1d3a5c70829416b8d0f2a4c6e8b1d3f5a7c9e2b4d6f8a0c3e5b7d9f1a2c" + demoBouncedEventID = "c4e6a8b0d2f41638507a9cbe1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f" demoTrackingEventID = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" demoSendAlertRuleID = "3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60" ) @@ -26,7 +28,7 @@ func (d *DemoClient) ListSendEvents(ctx context.Context, params *domain.SendEven {ID: demoSendEventID, EventType: "delivered", Timestamp: now - 60, ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, Recipient: "alice@example.org", RecipientDomain: "example.org", Reason: "250 2.0.0 OK"}, - {ID: demoTrackingEventID, EventType: "bounced", BounceClass: "hard", Timestamp: now - 120, + {ID: demoBouncedEventID, EventType: "bounced", BounceClass: "hard", Timestamp: now - 120, ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, Recipient: "bob@example.net", RecipientDomain: "example.net", Reason: "General (5.1.1)"}, @@ -36,6 +38,12 @@ func (d *DemoClient) ListSendEvents(ctx context.Context, params *domain.SendEven } func (d *DemoClient) GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) { + list, _ := d.ListSendEvents(ctx, nil) + for _, e := range list.Data { + if e.ID == eventID { + return &e, nil + } + } return &domain.SendEvent{ID: eventID, EventType: "delivered", Timestamp: time.Now().Unix() - 60, ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, Recipient: "alice@example.org", RecipientDomain: "example.org", @@ -50,8 +58,8 @@ func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID strin Recipients: []domain.SendMessageRecipient{{ Recipient: "alice@example.org", RecipientDomain: "example.org", CurrentStatus: "delivered", Events: []domain.SendTimelineEvent{ - {ID: demoSendEventID, EventType: "accepted", Timestamp: now - 120}, - {ID: demoTrackingEventID, EventType: "delivered", Timestamp: now - 60, Reason: "250 2.0.0 OK"}, + {ID: demoAcceptedEventID, EventType: "accepted", Timestamp: now - 120}, + {ID: demoSendEventID, EventType: "delivered", Timestamp: now - 60, Reason: "250 2.0.0 OK"}, }, }}, }, nil diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 4b2c7bb..447f2c7 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -233,3 +233,61 @@ func TestCommandTree(t *testing.T) { assert.ElementsMatch(t, subs, got, group) } } + +func TestParseActivityTime(t *testing.T) { + now := time.Date(2026, 11, 2, 15, 30, 0, 0, time.UTC) + tests := []struct { + name string + value string + isEnd bool + want time.Time + wantErr bool + }{ + {name: "empty means server default", value: ""}, + // Dates are UTC days and --end is inclusive, so a one-day window covers the whole day. + {name: "date start is UTC midnight", value: "2026-10-01", want: time.Date(2026, 10, 1, 0, 0, 0, 0, time.UTC)}, + {name: "date end is last second of the UTC day", value: "2026-10-01", isEnd: true, want: time.Date(2026, 10, 1, 23, 59, 59, 0, time.UTC)}, + // Without a zone the result must not depend on the laptop's time zone. + {name: "zoneless date-time is UTC", value: "2026-10-01 07:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, + {name: "look-back counts back from now", value: "7d", want: now.Add(-7 * 24 * time.Hour)}, + {name: "unix seconds", value: "1730000000", want: time.Unix(1730000000, 0)}, + // A non-positive look-back would put start at or after now and silently return nothing. + {name: "negative look-back rejected", value: "-7d", wantErr: true}, + {name: "zero look-back rejected", value: "0", wantErr: true}, + {name: "garbage rejected", value: "soon", wantErr: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := parseActivityTime("start", tt.value, now, tt.isEnd) + if tt.wantErr { + require.Error(t, err) + return + } + require.NoError(t, err) + if tt.want.IsZero() { + assert.Zero(t, got) + return + } + assert.Equal(t, tt.want.Unix(), got) + }) + } +} + +func TestSendAlertsCreate_RejectsThresholdsThatAreNotJSONNumbers(t *testing.T) { + // These parse as floats but are not JSON numbers, so they would fail when the request body is built. + for _, threshold := range []string{".5", "+5", "5.", "NaN", "1e2", "-1"} { + _, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, + "send-alerts", "create", "--metric", "bounce_rate", "--threshold", threshold, "--window-hours", "1") + require.Error(t, err, threshold) + assert.Contains(t, err.Error(), "invalid --threshold", threshold) + assert.Empty(t, reqs, threshold) + } +} + +func TestSendAlertsDelete_JSONOutputHasNoText(t *testing.T) { + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, `{"request_id":"r"}`, "send-alerts", "delete", "rule-1", "--yes", "--json") + require.NoError(t, err) + require.Len(t, reqs, 1) + // Scripts pipe --json output to a parser, so no human text may reach stdout. + assert.NotContains(t, out, "Deleted") +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 50c9b47..830535b 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -1,7 +1,6 @@ package deliverability import ( - "context" "fmt" "io" "regexp" @@ -10,37 +9,44 @@ import ( "time" "github.com/nylas/cli/internal/cli/common" - "github.com/nylas/cli/internal/ports" "github.com/spf13/cobra" ) const metricsDateLayout = "2006-01-02" -var eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) - -// withClient runs fn with an application-level client (no grant needed). -func withClient(fn func(ctx context.Context, client ports.NylasClient) error) error { - _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { - return struct{}{}, fn(ctx, client) - }) - return err -} +var ( + eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) + // thresholdPattern is a plain non-negative JSON number; the API rejects exponents and strings. + thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)(\.[0-9]+)?$`) +) -// parseActivityTime turns a --start/--end value into Unix seconds; a duration such as 24h or 7d means that long ago. -func parseActivityTime(flag, value string, now time.Time) (int64, error) { +// parseActivityTime turns a --start/--end value into Unix seconds. Times without a zone are UTC, +// a bare date is a whole UTC day (its end for --end), and a duration such as 24h or 7d means that long ago. +func parseActivityTime(flag, value string, now time.Time, isEnd bool) (int64, error) { value = strings.TrimSpace(value) if value == "" { return 0, nil } + invalid := common.NewUserError( + fmt.Sprintf("invalid --%s value %q", flag, value), + "Use a Unix timestamp, YYYY-MM-DD (UTC), RFC3339, or a look-back such as 24h or 7d", + ) + + if day, err := time.ParseInLocation(metricsDateLayout, value, time.UTC); err == nil { + if isEnd { + return day.Add(24*time.Hour - time.Second).Unix(), nil + } + return day.Unix(), nil + } if d, err := common.ParseDuration(value); err == nil { + if d <= 0 { + return 0, invalid + } return now.Add(-d).Unix(), nil } - t, err := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now}) + t, err := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now.UTC(), Loc: time.UTC}) if err != nil { - return 0, common.NewUserError( - fmt.Sprintf("invalid --%s value %q", flag, value), - "Use a Unix timestamp, YYYY-MM-DD, RFC3339, or a look-back such as 24h or 7d", - ) + return 0, invalid } return t.Unix(), nil } diff --git a/internal/cli/deliverability/metrics.go b/internal/cli/deliverability/metrics.go index 36855ec..48d2e5f 100644 --- a/internal/cli/deliverability/metrics.go +++ b/internal/cli/deliverability/metrics.go @@ -27,9 +27,10 @@ func newMetricsCmd(use, short, example string, run metricsRunner, extraFlags fun if err := validateMetricsDate("end", params.End); err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { - return run(ctx, cmd, client, ¶ms) + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + return struct{}{}, run(ctx, cmd, client, ¶ms) }) + return err }, } cmd.Flags().StringVar(¶ms.Start, "start", "", "First UTC day, YYYY-MM-DD (default: 6 days before --end)") diff --git a/internal/cli/deliverability/send_alerts.go b/internal/cli/deliverability/send_alerts.go index e4a0285..3708879 100644 --- a/internal/cli/deliverability/send_alerts.go +++ b/internal/cli/deliverability/send_alerts.go @@ -4,7 +4,6 @@ import ( "context" "encoding/json" "fmt" - "strconv" "strings" "github.com/nylas/cli/internal/cli/common" @@ -35,10 +34,11 @@ func buildAlertRuleRequest(cmd *cobra.Command, f *alertRuleFlags) (*domain.SendA req.Metric = &f.metric } if cmd.Flags().Changed("threshold") { - if _, err := strconv.ParseFloat(f.threshold, 64); err != nil { + threshold := strings.TrimSpace(f.threshold) + if !thresholdPattern.MatchString(threshold) { return nil, common.NewUserError(fmt.Sprintf("invalid --threshold value %q", f.threshold), "Use a percentage such as 5 or 0.25") } - n := json.Number(strings.TrimSpace(f.threshold)) + n := json.Number(threshold) req.Threshold = &n } if cmd.Flags().Changed("window-hours") { @@ -56,26 +56,27 @@ func newSendAlertsListCmd() *cobra.Command { Short: "List send alert rules", Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { rules, err := client.ListSendAlertRules(ctx) if err != nil { - return common.WrapListError("send alert rules", err) + return struct{}{}, common.WrapListError("send alert rules", err) } if done, err := writeStructuredList(cmd, rules, rules); done { - return err + return struct{}{}, err } if len(rules) == 0 { common.PrintEmptyStateWithHint("send alert rules", "Create one with: nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1") - return nil + return struct{}{}, nil } table := newTable(cmd.OutOrStdout(), "ID", "FIRES WHEN", "WINDOW", "MIN VOLUME", "UPDATED") for _, r := range rules { table.AddRow(r.ID, ruleCondition(r), fmt.Sprintf("%dh", r.WindowHours), formatCount(r.MinVolume), formatUnix(r.UpdatedAt)) } table.Render() - return nil + return struct{}{}, nil }) + return err }, } } @@ -86,13 +87,14 @@ func newSendAlertsShowCmd() *cobra.Command { Short: "Show a send alert rule", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { rule, err := client.GetSendAlertRule(ctx, args[0]) if err != nil { - return common.WrapGetError("send alert rule", err) + return struct{}{}, common.WrapGetError("send alert rule", err) } - return writeRule(cmd, rule) + return struct{}{}, writeRule(cmd, rule) }) + return err }, } } @@ -110,16 +112,17 @@ func newSendAlertsCreateCmd() *cobra.Command { if err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { rule, err := client.CreateSendAlertRule(ctx, req) if err != nil { - return common.WrapCreateError("send alert rule", err) + return struct{}{}, common.WrapCreateError("send alert rule", err) } if !common.IsStructuredOutput(cmd) { common.PrintSuccess("Created send alert rule %s", rule.ID) } - return writeRule(cmd, rule) + return struct{}{}, writeRule(cmd, rule) }) + return err }, } addAlertRuleFlags(cmd, &flags) @@ -144,16 +147,17 @@ func newSendAlertsUpdateCmd() *cobra.Command { if *req == (domain.SendAlertRuleRequest{}) { return common.NewUserError("nothing to update", "Set at least one of --metric, --threshold, --window-hours, --min-volume") } - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { rule, err := client.UpdateSendAlertRule(ctx, args[0], req) if err != nil { - return common.WrapUpdateError("send alert rule", err) + return struct{}{}, common.WrapUpdateError("send alert rule", err) } if !common.IsStructuredOutput(cmd) { common.PrintSuccess("Updated send alert rule %s", rule.ID) } - return writeRule(cmd, rule) + return struct{}{}, writeRule(cmd, rule) }) + return err }, } addAlertRuleFlags(cmd, &flags) @@ -171,13 +175,16 @@ func newSendAlertsDeleteCmd() *cobra.Command { if !yes { return common.NewUserError("deletion requires confirmation", "Re-run with --yes to delete the rule") } - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { if err := client.DeleteSendAlertRule(ctx, args[0]); err != nil { - return common.WrapDeleteError("send alert rule", err) + return struct{}{}, common.WrapDeleteError("send alert rule", err) } - common.PrintSuccess("Deleted send alert rule %s", args[0]) - return nil + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Deleted send alert rule %s", args[0]) + } + return struct{}{}, nil }) + return err }, } common.AddYesFlag(cmd, &yes) diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go index c1295ae..c2b0c45 100644 --- a/internal/cli/deliverability/send_events.go +++ b/internal/cli/deliverability/send_events.go @@ -17,19 +17,19 @@ type activityWindowFlags struct { } func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { - cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD, RFC3339, or look-back like 24h/7d (default: 6 days ago, UTC midnight)") - cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive (same formats; default: now)") + cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD (UTC), RFC3339, or look-back like 24h/7d (default: 6 days ago, UTC midnight)") + cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive; a date means the end of that UTC day (same formats; default: now)") cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") common.AddLimitFlag(cmd, limit, 50) common.AddPageTokenFlag(cmd, pageToken) } func (f activityWindowFlags) resolve(now time.Time) (int64, int64, error) { - start, err := parseActivityTime("start", f.start, now) + start, err := parseActivityTime("start", f.start, now, false) if err != nil { return 0, 0, err } - end, err := parseActivityTime("end", f.end, now) + end, err := parseActivityTime("end", f.end, now, true) if err != nil { return 0, 0, err } @@ -52,9 +52,10 @@ func newSendEventsListCmd() *cobra.Command { if params.Start, params.End, err = window.resolve(time.Now()); err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { - return runSendEventsList(ctx, cmd, client, ¶ms) + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + return struct{}{}, runSendEventsList(ctx, cmd, client, ¶ms) }) + return err }, } @@ -105,17 +106,18 @@ func newSendEventsShowCmd() *cobra.Command { if err := validateEventID(args[0]); err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { event, err := client.GetSendEvent(ctx, args[0]) if err != nil { - return common.WrapGetError("send event", err) + return struct{}{}, common.WrapGetError("send event", err) } if done, err := writeStructured(cmd, event); done { - return err + return struct{}{}, err } printSendEvent(cmd, event) - return nil + return struct{}{}, nil }) + return err }, } } @@ -161,17 +163,18 @@ func newSendEventsMessageCmd() *cobra.Command { Short: "Show every recipient's send timeline for one message", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { activity, err := client.GetSendMessageActivity(ctx, args[0]) if err != nil { - return common.WrapGetError("send activity for message", err) + return struct{}{}, common.WrapGetError("send activity for message", err) } if done, err := writeStructured(cmd, activity); done { - return err + return struct{}{}, err } printSendMessageActivity(cmd, activity) - return nil + return struct{}{}, nil }) + return err }, } } diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go index 9ec977d..98f1db4 100644 --- a/internal/cli/deliverability/tracking_events.go +++ b/internal/cli/deliverability/tracking_events.go @@ -26,9 +26,10 @@ func newTrackingEventsListCmd() *cobra.Command { if params.Start, params.End, err = window.resolve(time.Now()); err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { - return runTrackingEventsList(ctx, cmd, client, ¶ms) + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + return struct{}{}, runTrackingEventsList(ctx, cmd, client, ¶ms) }) + return err }, } @@ -76,17 +77,18 @@ func newTrackingEventsShowCmd() *cobra.Command { if err := validateEventID(args[0]); err != nil { return err } - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { event, err := client.GetTrackingEvent(ctx, args[0]) if err != nil { - return common.WrapGetError("tracking event", err) + return struct{}{}, common.WrapGetError("tracking event", err) } if done, err := writeStructured(cmd, event); done { - return err + return struct{}{}, err } printTrackingEvent(cmd, event) - return nil + return struct{}{}, nil }) + return err }, } } @@ -122,17 +124,18 @@ func newTrackingEventsMessageCmd() *cobra.Command { Short: "Show open and click totals and the newest 100 interactions for one message", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - return withClient(func(ctx context.Context, client ports.NylasClient) error { + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { activity, err := client.GetTrackingMessageActivity(ctx, args[0]) if err != nil { - return common.WrapGetError("tracking activity for message", err) + return struct{}{}, common.WrapGetError("tracking activity for message", err) } if done, err := writeStructured(cmd, activity); done { - return err + return struct{}{}, err } printTrackingMessageActivity(cmd, activity) - return nil + return struct{}{}, nil }) + return err }, } } From 60189df024661140658959655cd7436773673e24 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 13:42:47 -0500 Subject: [PATCH 3/8] [TW-8105] Address second review: look-back paging, --end-only window, demo consistency - A look-back --start/--end with --page-token now fails locally; page 1 prints a "Next page: --page-token ... --start --end " line to reuse. - --end without --start defaults start to UTC midnight 6 days before --end, so an older --end no longer gets "start must not be after end". - Activity times at or before 1970-01-01 are rejected instead of silently dropped. - --threshold matches the API literal (up to 9 integer digits, 2 decimals). - Demo send events come from one source, so list, show and message agree. - Tests capture fatih/color output, so the delete --json test can fail. - Docs: every zoneless activity time is UTC, including today/tomorrow/9am. Co-Authored-By: Claude Opus 5.5 --- docs/commands/deliverability.md | 6 +- .../adapters/nylas/demo_deliverability.go | 91 ++++++++++++------- internal/adapters/nylas/demo_test.go | 37 ++++++++ .../cli/deliverability/deliverability_test.go | 57 +++++++++++- internal/cli/deliverability/helpers.go | 59 +++++++----- internal/cli/deliverability/send_alerts.go | 2 +- internal/cli/deliverability/send_events.go | 41 +++++++-- .../cli/deliverability/tracking_events.go | 8 +- 8 files changed, 224 insertions(+), 77 deletions(-) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 38eb289..6b5a089 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -18,10 +18,10 @@ The two kinds of command take different time formats: | Commands | `--start` / `--end` | Default | Limit | |---|---|---|---| -| `list` (activity) | Unix timestamp, `YYYY-MM-DD`, RFC3339, or a look-back such as `24h`, `7d`, `2w` | UTC midnight 6 days ago → now | 90 days. An older start is moved to 90 days ago. | +| `list` (activity) | Unix timestamp, `YYYY-MM-DD`, RFC3339, or a look-back such as `24h`, `7d`, `2w` | `--end` = now, `--start` = UTC midnight 6 days before `--end` | 90 days. An older start is moved to 90 days ago. | | `summary`, `timeseries`, `breakdown` (metrics) | UTC date, `YYYY-MM-DD`, both days included | `--end` = today, `--start` = 6 days before `--end` | 365 days | -A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, a time without a zone is UTC, and a bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. +A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, every time without a zone is UTC, including `today`, `tomorrow`, `9am` and `Jan 2 3pm`. A bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. Times at or before 1970-01-01 are rejected. --- @@ -49,7 +49,7 @@ nylas deliverability send-events breakdown --group-by recipient_domain --sort bo **`list` filters:** `--event-type` (repeatable: `accepted`, `delivered`, `bounced`, `complaint`, `rejected`), `--bounce-class` (`hard`, `soft`, `undetermined`), `--sending-domain`, `--from`, `--grant-id`, `--recipient`, `--recipient-domain`, `--message-id`, `--thread-id`, `--order asc|desc`. -**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query. +**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start --end ` instead; use those values for the next page. Scripts that page with `--json` should pass absolute times. **`summary`:** health is always graded on the **last 7 days**, whatever window you ask for. The states are `healthy`, `at_risk`, `critical` and `insufficient_data` (fewer than 100 sends). Totals and rate tiles use your window and compare it with the period of the same length just before it. When the state is `at_risk` or `critical`, `summary` also lists up to 3 findings. diff --git a/internal/adapters/nylas/demo_deliverability.go b/internal/adapters/nylas/demo_deliverability.go index b635e7f..1fa32d5 100644 --- a/internal/adapters/nylas/demo_deliverability.go +++ b/internal/adapters/nylas/demo_deliverability.go @@ -1,7 +1,9 @@ package nylas import ( + "cmp" "context" + "slices" "time" "github.com/nylas/cli/internal/domain" @@ -21,48 +23,71 @@ const ( func demoRate(v float64) *float64 { return &v } +// demoSendEvents is the one source of demo send events, so list, show and message agree on every ID. +func demoSendEvents(now int64) []domain.SendEvent { + base := domain.SendEvent{ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, + From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain} + accepted, delivered, bounced := base, base, base + + accepted.ID, accepted.EventType, accepted.Timestamp = demoAcceptedEventID, "accepted", now-120 + accepted.Recipient, accepted.RecipientDomain = "alice@example.org", "example.org" + + delivered.ID, delivered.EventType, delivered.Timestamp = demoSendEventID, "delivered", now-60 + delivered.Recipient, delivered.RecipientDomain, delivered.Reason = "alice@example.org", "example.org", "250 2.0.0 OK" + delivered.Detail = &domain.SendEventDetail{SMTPResponse: "250 2.0.0 OK", ProcessingTimeMs: 812} + + bounced.ID, bounced.EventType, bounced.BounceClass, bounced.Timestamp = demoBouncedEventID, "bounced", "hard", now-90 + bounced.Recipient, bounced.RecipientDomain, bounced.Reason = "bob@example.net", "example.net", "General (5.1.1)" + + return []domain.SendEvent{delivered, bounced, accepted} +} + func (d *DemoClient) ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) { - now := time.Now().Unix() - return &domain.SendEventListResponse{ - Data: []domain.SendEvent{ - {ID: demoSendEventID, EventType: "delivered", Timestamp: now - 60, ApplicationID: demoDeliverabilityApp, - MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, - Recipient: "alice@example.org", RecipientDomain: "example.org", Reason: "250 2.0.0 OK"}, - {ID: demoBouncedEventID, EventType: "bounced", BounceClass: "hard", Timestamp: now - 120, - ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, - SendingDomain: demoDeliverabilityDomain, Recipient: "bob@example.net", RecipientDomain: "example.net", - Reason: "General (5.1.1)"}, - }, - RequestID: "demo-request-id", - }, nil + return &domain.SendEventListResponse{Data: demoSendEvents(time.Now().Unix()), RequestID: "demo-request-id"}, nil } func (d *DemoClient) GetSendEvent(ctx context.Context, eventID string) (*domain.SendEvent, error) { - list, _ := d.ListSendEvents(ctx, nil) - for _, e := range list.Data { - if e.ID == eventID { - return &e, nil + events := demoSendEvents(time.Now().Unix()) + for i := range events { + if events[i].ID == eventID { + return &events[i], nil } } - return &domain.SendEvent{ID: eventID, EventType: "delivered", Timestamp: time.Now().Unix() - 60, - ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, - SendingDomain: demoDeliverabilityDomain, Recipient: "alice@example.org", RecipientDomain: "example.org", - Reason: "250 2.0.0 OK", Detail: &domain.SendEventDetail{SMTPResponse: "250 2.0.0 OK", ProcessingTimeMs: 812}}, nil + fallback := events[0] + fallback.ID = eventID + return &fallback, nil } func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { - now := time.Now().Unix() - return &domain.SendMessageActivity{ - Message: domain.SendMessageEnvelope{MessageID: messageID, ApplicationID: demoDeliverabilityApp, - From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, SentAt: now - 120, LastEventAt: now - 60}, - Recipients: []domain.SendMessageRecipient{{ - Recipient: "alice@example.org", RecipientDomain: "example.org", CurrentStatus: "delivered", - Events: []domain.SendTimelineEvent{ - {ID: demoAcceptedEventID, EventType: "accepted", Timestamp: now - 120}, - {ID: demoSendEventID, EventType: "delivered", Timestamp: now - 60, Reason: "250 2.0.0 OK"}, - }, - }}, - }, nil + events := demoSendEvents(time.Now().Unix()) + recipients := map[string]*domain.SendMessageRecipient{} + var order []string + for _, e := range events { + r, ok := recipients[e.Recipient] + if !ok { + r = &domain.SendMessageRecipient{Recipient: e.Recipient, RecipientDomain: e.RecipientDomain} + recipients[e.Recipient] = r + order = append(order, e.Recipient) + } + r.Events = append(r.Events, domain.SendTimelineEvent{ID: e.ID, EventType: e.EventType, Timestamp: e.Timestamp, + BounceClass: e.BounceClass, Reason: e.Reason, Detail: e.Detail}) + } + + activity := &domain.SendMessageActivity{Message: domain.SendMessageEnvelope{MessageID: messageID, + ApplicationID: demoDeliverabilityApp, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain}} + slices.Sort(order) + for _, name := range order { + r := recipients[name] + slices.SortFunc(r.Events, func(a, b domain.SendTimelineEvent) int { return cmp.Compare(a.Timestamp, b.Timestamp) }) + last := r.Events[len(r.Events)-1] + r.CurrentStatus, r.BounceClass = last.EventType, last.BounceClass + activity.Recipients = append(activity.Recipients, *r) + if activity.Message.SentAt == 0 || r.Events[0].Timestamp < activity.Message.SentAt { + activity.Message.SentAt = r.Events[0].Timestamp + } + activity.Message.LastEventAt = max(activity.Message.LastEventAt, last.Timestamp) + } + return activity, nil } func (d *DemoClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { diff --git a/internal/adapters/nylas/demo_test.go b/internal/adapters/nylas/demo_test.go index 88f8e6a..1b04819 100644 --- a/internal/adapters/nylas/demo_test.go +++ b/internal/adapters/nylas/demo_test.go @@ -414,3 +414,40 @@ func TestDemoClientSendMessageWithTracking(t *testing.T) { } }) } + +// Demo mode is used for screenshots, so list, show and message must tell the same story for every event ID. +func TestDemoClientSendEventsAgree(t *testing.T) { + client := NewDemoClient() + ctx := context.Background() + + list, err := client.ListSendEvents(ctx, nil) + if err != nil { + t.Fatalf("ListSendEvents failed: %v", err) + } + activity, err := client.GetSendMessageActivity(ctx, demoDeliverabilityMsgID) + if err != nil { + t.Fatalf("GetSendMessageActivity failed: %v", err) + } + + want := map[string]string{} + for _, e := range list.Data { + want[e.ID] = e.EventType + } + for _, r := range activity.Recipients { + for _, e := range r.Events { + if typ, ok := want[e.ID]; ok && typ != e.EventType { + t.Errorf("event %s is %s in list but %s in the timeline", e.ID, typ, e.EventType) + } + want[e.ID] = e.EventType + } + } + for id, typ := range want { + got, err := client.GetSendEvent(ctx, id) + if err != nil { + t.Fatalf("GetSendEvent(%s) failed: %v", id, err) + } + if got.EventType != typ { + t.Errorf("show %s returns %s, want %s", id, got.EventType, typ) + } + } +} diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 447f2c7..1944671 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -1,6 +1,7 @@ package deliverability import ( + "bytes" "encoding/json" "io" "net/http" @@ -9,6 +10,7 @@ import ( "testing" "time" + "github.com/fatih/color" "github.com/nylas/cli/internal/cli/testutil" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -40,8 +42,14 @@ func runAgainstFakeAPI(t *testing.T, status int, respBody string, args ...string t.Setenv("NYLAS_API_KEY", "test-api-key") t.Setenv("NYLAS_API_BASE_URL", server.URL) + // common.PrintSuccess writes through fatih/color, whose Output is bound to the real stdout at init. + var colorOut bytes.Buffer + oldColorOut := color.Output + color.Output = &colorOut + t.Cleanup(func() { color.Output = oldColorOut }) + stdout, _, err := testutil.ExecuteSubCommand(NewDeliverabilityCmd(), args...) - return stdout, requests, err + return stdout + colorOut.String(), requests, err } const sendEventsPage = `{"request_id":"req-1","next_cursor":"tok-2","data":[ @@ -65,7 +73,7 @@ func TestSendEventsList_FlagsBecomeQuery(t *testing.T) { assert.InDelta(t, before, start, 5) assert.Contains(t, out, "bounced (hard)") - assert.Contains(t, out, "Next page token: tok-2") + assert.Contains(t, out, "Next page: --page-token tok-2") } func TestSendEventsList_JSONKeepsEnvelope(t *testing.T) { @@ -255,10 +263,13 @@ func TestParseActivityTime(t *testing.T) { {name: "negative look-back rejected", value: "-7d", wantErr: true}, {name: "zero look-back rejected", value: "0", wantErr: true}, {name: "garbage rejected", value: "soon", wantErr: true}, + // The API treats 0 and below as "not set", so these would silently become the default window. + {name: "pre-1970 date rejected", value: "1969-12-31", wantErr: true}, + {name: "epoch zero rejected", value: "1970-01-01", wantErr: true}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - got, err := parseActivityTime("start", tt.value, now, tt.isEnd) + got, _, err := parseActivityTime("start", tt.value, now, tt.isEnd) if tt.wantErr { require.Error(t, err) return @@ -274,8 +285,10 @@ func TestParseActivityTime(t *testing.T) { } func TestSendAlertsCreate_RejectsThresholdsThatAreNotJSONNumbers(t *testing.T) { - // These parse as floats but are not JSON numbers, so they would fail when the request body is built. - for _, threshold := range []string{".5", "+5", "5.", "NaN", "1e2", "-1"} { + // Rejected locally so the user gets a clear error, not a marshal failure or a server 400: + // .5, +5, 5. and NaN are not JSON numbers; the API refuses exponents, negatives, more than + // 2 decimals and more than 9 integer digits. + for _, threshold := range []string{".5", "+5", "5.", "NaN", "1e2", "-1", "0.125", "1234567890"} { _, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, "send-alerts", "create", "--metric", "bounce_rate", "--threshold", threshold, "--window-hours", "1") require.Error(t, err, threshold) @@ -291,3 +304,37 @@ func TestSendAlertsDelete_JSONOutputHasNoText(t *testing.T) { // Scripts pipe --json output to a parser, so no human text may reach stdout. assert.NotContains(t, out, "Deleted") } + +func TestSendAlertsCreate_AcceptsThresholdsTheAPIAccepts(t *testing.T) { + for _, threshold := range []string{"0", "5", "99.99"} { + _, reqs, err := runAgainstFakeAPI(t, http.StatusCreated, ruleResp, + "send-alerts", "create", "--metric", "bounce_rate", "--threshold", threshold, "--window-hours", "1") + require.NoError(t, err, threshold) + require.Len(t, reqs, 1, threshold) + } +} + +func TestSendEventsList_LookBackWithPageTokenFailsLocally(t *testing.T) { + // The page token is bound to the exact start/end, and a look-back resolves differently on every run. + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "7d", "--page-token", "tok-1") + require.Error(t, err) + assert.Contains(t, err.Error(), "--page-token") + assert.Empty(t, reqs) +} + +func TestSendEventsList_LookBackPrintsReusableNextPage(t *testing.T) { + out, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "7d") + require.NoError(t, err) + require.Len(t, reqs, 1) + // The next-page line must repeat the epoch actually sent, so pasting it reproduces the same query. + assert.Contains(t, out, "Next page: --page-token tok-2 --start "+reqs[0].query["start"][0]) +} + +func TestSendEventsList_EndOnlyAnchorsDefaultStart(t *testing.T) { + // Without this, an --end older than 6 days is before the server's default start and returns 400. + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--end", "2026-10-01") + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, []string{strconv.FormatInt(time.Date(2026, 9, 25, 0, 0, 0, 0, time.UTC).Unix(), 10)}, reqs[0].query["start"]) + assert.Equal(t, []string{strconv.FormatInt(time.Date(2026, 10, 1, 23, 59, 59, 0, time.UTC).Unix(), 10)}, reqs[0].query["end"]) +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 830535b..9dd4c7f 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -16,39 +16,47 @@ const metricsDateLayout = "2006-01-02" var ( eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) - // thresholdPattern is a plain non-negative JSON number; the API rejects exponents and strings. - thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)(\.[0-9]+)?$`) + // thresholdPattern matches the API's threshold literal: no sign or exponent, up to 9 integer digits and 2 decimals. + thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]{0,8})(\.[0-9]{1,2})?$`) ) -// parseActivityTime turns a --start/--end value into Unix seconds. Times without a zone are UTC, -// a bare date is a whole UTC day (its end for --end), and a duration such as 24h or 7d means that long ago. -func parseActivityTime(flag, value string, now time.Time, isEnd bool) (int64, error) { +// parseActivityTime turns a --start/--end value into Unix seconds. Every time without a zone is UTC +// (including today, tomorrow and 9am), a bare date is a whole UTC day (its end for --end), and a +// duration such as 24h or 7d means that long ago. relative is true for durations, which move between runs. +func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, relative bool, err error) { value = strings.TrimSpace(value) if value == "" { - return 0, nil + return 0, false, nil } invalid := common.NewUserError( fmt.Sprintf("invalid --%s value %q", flag, value), - "Use a Unix timestamp, YYYY-MM-DD (UTC), RFC3339, or a look-back such as 24h or 7d", + "Use a Unix timestamp, YYYY-MM-DD, RFC3339, or a look-back such as 24h or 7d; times without a zone are UTC", ) - if day, err := time.ParseInLocation(metricsDateLayout, value, time.UTC); err == nil { - if isEnd { - return day.Add(24*time.Hour - time.Second).Unix(), nil + switch day, dateErr := time.ParseInLocation(metricsDateLayout, value, time.UTC); { + case dateErr == nil && isEnd: + ts = day.Add(24*time.Hour - time.Second).Unix() + case dateErr == nil: + ts = day.Unix() + default: + if d, durErr := common.ParseDuration(value); durErr == nil { + if d <= 0 { + return 0, false, invalid + } + ts, relative = now.Add(-d).Unix(), true + } else { + t, parseErr := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now.UTC(), Loc: time.UTC}) + if parseErr != nil { + return 0, false, invalid + } + ts = t.Unix() } - return day.Unix(), nil } - if d, err := common.ParseDuration(value); err == nil { - if d <= 0 { - return 0, invalid - } - return now.Add(-d).Unix(), nil - } - t, err := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now.UTC(), Loc: time.UTC}) - if err != nil { - return 0, invalid + // The API reads 0 and below as "not set", so such a time would silently fall back to the default window. + if ts <= 0 { + return 0, false, invalid } - return t.Unix(), nil + return ts, relative, nil } // validateMetricsDate checks a --start/--end metrics value is YYYY-MM-DD. @@ -100,11 +108,16 @@ func newTable(w io.Writer, headers ...string) *common.Table { return common.NewTable(headers...).SetWriter(w) } -func nextCursorNote(cmd *cobra.Command, nextCursor string) { +// nextCursorNote prints the next page token; pageFlags, when set, are window flags the next page must repeat. +func nextCursorNote(cmd *cobra.Command, nextCursor, pageFlags string) { if nextCursor == "" { return } - _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page token: %s\n", nextCursor) + if pageFlags == "" { + _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page token: %s\n", nextCursor) + return + } + _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page: --page-token %s %s\n", nextCursor, pageFlags) } // writeStructuredList writes a list response as JSON/YAML, or only the row IDs in quiet mode. diff --git a/internal/cli/deliverability/send_alerts.go b/internal/cli/deliverability/send_alerts.go index 3708879..d3694a1 100644 --- a/internal/cli/deliverability/send_alerts.go +++ b/internal/cli/deliverability/send_alerts.go @@ -36,7 +36,7 @@ func buildAlertRuleRequest(cmd *cobra.Command, f *alertRuleFlags) (*domain.SendA if cmd.Flags().Changed("threshold") { threshold := strings.TrimSpace(f.threshold) if !thresholdPattern.MatchString(threshold) { - return nil, common.NewUserError(fmt.Sprintf("invalid --threshold value %q", f.threshold), "Use a percentage such as 5 or 0.25") + return nil, common.NewUserError(fmt.Sprintf("invalid --threshold value %q", f.threshold), "Use a percentage with at most 2 decimals, such as 5 or 0.25") } n := json.Number(threshold) req.Threshold = &n diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go index c2b0c45..809ebc7 100644 --- a/internal/cli/deliverability/send_events.go +++ b/internal/cli/deliverability/send_events.go @@ -14,28 +14,53 @@ import ( type activityWindowFlags struct { start, end string + // pageFlags repeats a look-back window as epochs, because the page token is bound to the exact start and end. + pageFlags string } func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { - cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD (UTC), RFC3339, or look-back like 24h/7d (default: 6 days ago, UTC midnight)") + cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD, RFC3339, or look-back like 24h/7d; no zone means UTC (default: UTC midnight 6 days before --end, or before today)") cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive; a date means the end of that UTC day (same formats; default: now)") cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") common.AddLimitFlag(cmd, limit, 50) common.AddPageTokenFlag(cmd, pageToken) } -func (f activityWindowFlags) resolve(now time.Time) (int64, int64, error) { - start, err := parseActivityTime("start", f.start, now, false) +// resolve returns the start and end to send, in Unix seconds; 0 leaves the server default. +func (f *activityWindowFlags) resolve(now time.Time, pageToken string) (int64, int64, error) { + start, startRelative, err := parseActivityTime("start", f.start, now, false) if err != nil { return 0, 0, err } - end, err := parseActivityTime("end", f.end, now, true) + end, endRelative, err := parseActivityTime("end", f.end, now, true) if err != nil { return 0, 0, err } + // Mirror the server's default start, anchored on --end, so an older --end is not before the default start. + if start == 0 && end != 0 { + endDay := time.Unix(end, 0).UTC().Truncate(24 * time.Hour) + start = endDay.AddDate(0, 0, -6).Unix() + } + if !startRelative && !endRelative { + return start, end, nil + } + if pageToken != "" { + return 0, 0, common.NewUserError( + "a look-back --start/--end cannot be used with --page-token", + "Look-backs move between runs; repeat the --start/--end values printed with the page token", + ) + } + f.pageFlags = strings.TrimSpace(epochFlag("start", start) + " " + epochFlag("end", end)) return start, end, nil } +func epochFlag(name string, ts int64) string { + if ts == 0 { + return "" + } + return fmt.Sprintf("--%s %d", name, ts) +} + func newSendEventsListCmd() *cobra.Command { var window activityWindowFlags var params domain.SendEventListParams @@ -49,11 +74,11 @@ func newSendEventsListCmd() *cobra.Command { Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { var err error - if params.Start, params.End, err = window.resolve(time.Now()); err != nil { + if params.Start, params.End, err = window.resolve(time.Now(), params.PageToken); err != nil { return err } _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { - return struct{}{}, runSendEventsList(ctx, cmd, client, ¶ms) + return struct{}{}, runSendEventsList(ctx, cmd, client, ¶ms, window.pageFlags) }) return err }, @@ -74,7 +99,7 @@ func newSendEventsListCmd() *cobra.Command { return cmd } -func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.SendEventListParams) error { +func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.SendEventListParams, pageFlags string) error { resp, err := client.ListSendEvents(ctx, params) if err != nil { return common.WrapListError("send events", err) @@ -93,7 +118,7 @@ func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.Nyl table.AddRow(formatUnix(e.Timestamp), sendEventLabel(e.EventType, e.BounceClass), e.Recipient, e.From, e.Reason, e.ID) } table.Render() - nextCursorNote(cmd, resp.NextCursor) + nextCursorNote(cmd, resp.NextCursor, pageFlags) return nil } diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go index 98f1db4..52d2d47 100644 --- a/internal/cli/deliverability/tracking_events.go +++ b/internal/cli/deliverability/tracking_events.go @@ -23,11 +23,11 @@ func newTrackingEventsListCmd() *cobra.Command { Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { var err error - if params.Start, params.End, err = window.resolve(time.Now()); err != nil { + if params.Start, params.End, err = window.resolve(time.Now(), params.PageToken); err != nil { return err } _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { - return struct{}{}, runTrackingEventsList(ctx, cmd, client, ¶ms) + return struct{}{}, runTrackingEventsList(ctx, cmd, client, ¶ms, window.pageFlags) }) return err }, @@ -45,7 +45,7 @@ func newTrackingEventsListCmd() *cobra.Command { return cmd } -func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.TrackingEventListParams) error { +func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.TrackingEventListParams, pageFlags string) error { resp, err := client.ListTrackingEvents(ctx, params) if err != nil { return common.WrapListError("tracking events", err) @@ -64,7 +64,7 @@ func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports table.AddRow(formatUnix(e.Timestamp), e.EventType, yesNo(e.IsFirst), e.From, e.Label, derefString(e.URL), e.ID) } table.Render() - nextCursorNote(cmd, resp.NextCursor) + nextCursorNote(cmd, resp.NextCursor, pageFlags) return nil } From afbe11eea124560e75b44f95e4c82cebb60fce53 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 13:54:31 -0500 Subject: [PATCH 4/8] [TW-8105] Address third review: stable activity times, 90-day --end, stderr page hint - Activity --start/--end accept only Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM" (UTC), RFC3339 and look-backs. Keyword forms (today, tomorrow, 9am) moved between runs, broke --page-token and could land in the future. - --end older than the 90-day activity retention is rejected locally instead of returning an empty list. - With --json/--format yaml/--quiet, a look-back's "Next page:" line goes to stderr. - Docs list the accepted forms and match the next-page output. - Demo: bob gets an accepted event, the timeline is a static literal, and the demo test fails if a timeline ID is missing from the list. Co-Authored-By: Claude Opus 5.5 --- docs/commands/deliverability.md | 6 +- .../adapters/nylas/demo_deliverability.go | 76 +++++++++---------- internal/adapters/nylas/demo_test.go | 9 ++- .../cli/deliverability/deliverability_test.go | 44 +++++++++-- internal/cli/deliverability/helpers.go | 56 ++++++++------ internal/cli/deliverability/send_events.go | 16 +++- .../cli/deliverability/tracking_events.go | 6 +- 7 files changed, 135 insertions(+), 78 deletions(-) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 6b5a089..2d35232 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -18,10 +18,10 @@ The two kinds of command take different time formats: | Commands | `--start` / `--end` | Default | Limit | |---|---|---|---| -| `list` (activity) | Unix timestamp, `YYYY-MM-DD`, RFC3339, or a look-back such as `24h`, `7d`, `2w` | `--end` = now, `--start` = UTC midnight 6 days before `--end` | 90 days. An older start is moved to 90 days ago. | +| `list` (activity) | Unix seconds, `YYYY-MM-DD`, `"YYYY-MM-DD HH:MM"` (UTC), RFC3339, or a look-back such as `24h`, `7d`, `2w` | `--end` = now, `--start` = UTC midnight 6 days before `--end` | 90 days. An older `--start` is moved to 90 days ago; an older `--end` is rejected. | | `summary`, `timeseries`, `breakdown` (metrics) | UTC date, `YYYY-MM-DD`, both days included | `--end` = today, `--start` = 6 days before `--end` | 365 days | -A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, every time without a zone is UTC, including `today`, `tomorrow`, `9am` and `Jan 2 3pm`. A bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. Times at or before 1970-01-01 are rejected. +A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, a time without a zone is UTC, and a bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. Words such as `today` or `9am` are not accepted, because they mean a different time on each run. --- @@ -49,7 +49,7 @@ nylas deliverability send-events breakdown --group-by recipient_domain --sort bo **`list` filters:** `--event-type` (repeatable: `accepted`, `delivered`, `bounced`, `complaint`, `rejected`), `--bounce-class` (`hard`, `soft`, `undetermined`), `--sending-domain`, `--from`, `--grant-id`, `--recipient`, `--recipient-domain`, `--message-id`, `--thread-id`, `--order asc|desc`. -**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start --end ` instead; use those values for the next page. Scripts that page with `--json` should pass absolute times. +**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start ` instead, with `--end ` too if you set `--end`. Run the next page with exactly those flags. (Without `--end`, the token itself keeps the end time.) With `--json`, `--format yaml` or `--quiet`, the same line goes to stderr, so stdout stays the plain API response. **`summary`:** health is always graded on the **last 7 days**, whatever window you ask for. The states are `healthy`, `at_risk`, `critical` and `insufficient_data` (fewer than 100 sends). Totals and rate tiles use your window and compare it with the period of the same length just before it. When the state is `at_risk` or `critical`, `summary` also lists up to 3 findings. diff --git a/internal/adapters/nylas/demo_deliverability.go b/internal/adapters/nylas/demo_deliverability.go index 1fa32d5..a44ba93 100644 --- a/internal/adapters/nylas/demo_deliverability.go +++ b/internal/adapters/nylas/demo_deliverability.go @@ -1,9 +1,7 @@ package nylas import ( - "cmp" "context" - "slices" "time" "github.com/nylas/cli/internal/domain" @@ -16,6 +14,7 @@ const ( demoDeliverabilityMsgID = "" demoSendEventID = "5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f" demoAcceptedEventID = "e7f9b1d3a5c70829416b8d0f2a4c6e8b1d3f5a7c9e2b4d6f8a0c3e5b7d9f1a2c" + demoBobAcceptedEventID = "b8d0f2a4c6e81a3c5e7092b4d6f8a1c3e5b7d9f0a2c4e6b8d1f3a5c7e9b0d2f4" demoBouncedEventID = "c4e6a8b0d2f41638507a9cbe1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f" demoTrackingEventID = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" demoSendAlertRuleID = "3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60" @@ -25,21 +24,22 @@ func demoRate(v float64) *float64 { return &v } // demoSendEvents is the one source of demo send events, so list, show and message agree on every ID. func demoSendEvents(now int64) []domain.SendEvent { - base := domain.SendEvent{ApplicationID: demoDeliverabilityApp, MessageID: demoDeliverabilityMsgID, - From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain} - accepted, delivered, bounced := base, base, base - - accepted.ID, accepted.EventType, accepted.Timestamp = demoAcceptedEventID, "accepted", now-120 - accepted.Recipient, accepted.RecipientDomain = "alice@example.org", "example.org" - - delivered.ID, delivered.EventType, delivered.Timestamp = demoSendEventID, "delivered", now-60 - delivered.Recipient, delivered.RecipientDomain, delivered.Reason = "alice@example.org", "example.org", "250 2.0.0 OK" + row := func(id, eventType string, ago int64, recipient, recipientDomain, reason string) domain.SendEvent { + return domain.SendEvent{ID: id, EventType: eventType, Timestamp: now - ago, ApplicationID: demoDeliverabilityApp, + MessageID: demoDeliverabilityMsgID, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, + Recipient: recipient, RecipientDomain: recipientDomain, Reason: reason} + } + delivered := row(demoSendEventID, "delivered", 60, "alice@example.org", "example.org", "250 2.0.0 OK") delivered.Detail = &domain.SendEventDetail{SMTPResponse: "250 2.0.0 OK", ProcessingTimeMs: 812} - - bounced.ID, bounced.EventType, bounced.BounceClass, bounced.Timestamp = demoBouncedEventID, "bounced", "hard", now-90 - bounced.Recipient, bounced.RecipientDomain, bounced.Reason = "bob@example.net", "example.net", "General (5.1.1)" - - return []domain.SendEvent{delivered, bounced, accepted} + bounced := row(demoBouncedEventID, "bounced", 90, "bob@example.net", "example.net", "General (5.1.1)") + bounced.BounceClass = "hard" + + return []domain.SendEvent{ + delivered, + bounced, + row(demoAcceptedEventID, "accepted", 120, "alice@example.org", "example.org", ""), + row(demoBobAcceptedEventID, "accepted", 120, "bob@example.net", "example.net", ""), + } } func (d *DemoClient) ListSendEvents(ctx context.Context, params *domain.SendEventListParams) (*domain.SendEventListResponse, error) { @@ -60,34 +60,28 @@ func (d *DemoClient) GetSendEvent(ctx context.Context, eventID string) (*domain. func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { events := demoSendEvents(time.Now().Unix()) - recipients := map[string]*domain.SendMessageRecipient{} - var order []string + delivered, bounced, aliceAccepted, bobAccepted := events[0], events[1], events[2], events[3] + return &domain.SendMessageActivity{ + Message: domain.SendMessageEnvelope{MessageID: messageID, ApplicationID: demoDeliverabilityApp, + From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, + SentAt: aliceAccepted.Timestamp, LastEventAt: delivered.Timestamp}, + Recipients: []domain.SendMessageRecipient{ + {Recipient: delivered.Recipient, RecipientDomain: delivered.RecipientDomain, CurrentStatus: "delivered", + Events: timelineOf(aliceAccepted, delivered)}, + {Recipient: bounced.Recipient, RecipientDomain: bounced.RecipientDomain, CurrentStatus: "bounced", BounceClass: "hard", + Events: timelineOf(bobAccepted, bounced)}, + }, + }, nil +} + +// timelineOf turns send events, oldest first, into a recipient timeline. +func timelineOf(events ...domain.SendEvent) []domain.SendTimelineEvent { + timeline := make([]domain.SendTimelineEvent, 0, len(events)) for _, e := range events { - r, ok := recipients[e.Recipient] - if !ok { - r = &domain.SendMessageRecipient{Recipient: e.Recipient, RecipientDomain: e.RecipientDomain} - recipients[e.Recipient] = r - order = append(order, e.Recipient) - } - r.Events = append(r.Events, domain.SendTimelineEvent{ID: e.ID, EventType: e.EventType, Timestamp: e.Timestamp, + timeline = append(timeline, domain.SendTimelineEvent{ID: e.ID, EventType: e.EventType, Timestamp: e.Timestamp, BounceClass: e.BounceClass, Reason: e.Reason, Detail: e.Detail}) } - - activity := &domain.SendMessageActivity{Message: domain.SendMessageEnvelope{MessageID: messageID, - ApplicationID: demoDeliverabilityApp, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain}} - slices.Sort(order) - for _, name := range order { - r := recipients[name] - slices.SortFunc(r.Events, func(a, b domain.SendTimelineEvent) int { return cmp.Compare(a.Timestamp, b.Timestamp) }) - last := r.Events[len(r.Events)-1] - r.CurrentStatus, r.BounceClass = last.EventType, last.BounceClass - activity.Recipients = append(activity.Recipients, *r) - if activity.Message.SentAt == 0 || r.Events[0].Timestamp < activity.Message.SentAt { - activity.Message.SentAt = r.Events[0].Timestamp - } - activity.Message.LastEventAt = max(activity.Message.LastEventAt, last.Timestamp) - } - return activity, nil + return timeline } func (d *DemoClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { diff --git a/internal/adapters/nylas/demo_test.go b/internal/adapters/nylas/demo_test.go index 1b04819..55ddce8 100644 --- a/internal/adapters/nylas/demo_test.go +++ b/internal/adapters/nylas/demo_test.go @@ -435,10 +435,15 @@ func TestDemoClientSendEventsAgree(t *testing.T) { } for _, r := range activity.Recipients { for _, e := range r.Events { - if typ, ok := want[e.ID]; ok && typ != e.EventType { + // GetSendEvent falls back for unknown IDs, so a timeline-only ID must be caught here. + typ, ok := want[e.ID] + if !ok { + t.Errorf("timeline event %s is missing from the list", e.ID) + continue + } + if typ != e.EventType { t.Errorf("event %s is %s in list but %s in the timeline", e.ID, typ, e.EventType) } - want[e.ID] = e.EventType } } for id, typ := range want { diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 1944671..a1f75b0 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -25,6 +25,13 @@ type capturedRequest struct { // runAgainstFakeAPI runs the real command tree against a fake Nylas API that answers every request with respBody. func runAgainstFakeAPI(t *testing.T, status int, respBody string, args ...string) (string, []capturedRequest, error) { + t.Helper() + stdout, _, requests, err := runAgainstFakeAPIWithStderr(t, status, respBody, args...) + return stdout, requests, err +} + +// runAgainstFakeAPIWithStderr is runAgainstFakeAPI that also returns stderr. +func runAgainstFakeAPIWithStderr(t *testing.T, status int, respBody string, args ...string) (string, string, []capturedRequest, error) { t.Helper() var requests []capturedRequest server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { @@ -48,8 +55,8 @@ func runAgainstFakeAPI(t *testing.T, status int, respBody string, args ...string color.Output = &colorOut t.Cleanup(func() { color.Output = oldColorOut }) - stdout, _, err := testutil.ExecuteSubCommand(NewDeliverabilityCmd(), args...) - return stdout + colorOut.String(), requests, err + stdout, stderr, err := testutil.ExecuteSubCommand(NewDeliverabilityCmd(), args...) + return stdout + colorOut.String(), stderr, requests, err } const sendEventsPage = `{"request_id":"req-1","next_cursor":"tok-2","data":[ @@ -257,6 +264,13 @@ func TestParseActivityTime(t *testing.T) { {name: "date end is last second of the UTC day", value: "2026-10-01", isEnd: true, want: time.Date(2026, 10, 1, 23, 59, 59, 0, time.UTC)}, // Without a zone the result must not depend on the laptop's time zone. {name: "zoneless date-time is UTC", value: "2026-10-01 07:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, + {name: "RFC3339 keeps its zone", value: "2026-10-01T07:00:00-04:00", want: time.Date(2026, 10, 1, 11, 0, 0, 0, time.UTC)}, + // Keyword and time-of-day forms resolve differently from run to run (and 9am rolls to tomorrow), + // which breaks --page-token, so only look-backs may move and they are flagged as relative. + {name: "today rejected", value: "today", wantErr: true}, + {name: "tomorrow rejected", value: "tomorrow", wantErr: true}, + {name: "time of day rejected", value: "9am", wantErr: true}, + {name: "month-day time rejected", value: "Jan 2 3pm", wantErr: true}, {name: "look-back counts back from now", value: "7d", want: now.Add(-7 * 24 * time.Hour)}, {name: "unix seconds", value: "1730000000", want: time.Unix(1730000000, 0)}, // A non-positive look-back would put start at or after now and silently return nothing. @@ -332,9 +346,29 @@ func TestSendEventsList_LookBackPrintsReusableNextPage(t *testing.T) { func TestSendEventsList_EndOnlyAnchorsDefaultStart(t *testing.T) { // Without this, an --end older than 6 days is before the server's default start and returns 400. - _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--end", "2026-10-01") + endDay := time.Now().UTC().AddDate(0, 0, -30).Truncate(24 * time.Hour) + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--end", endDay.Format("2006-01-02")) + require.NoError(t, err) + require.Len(t, reqs, 1) + assert.Equal(t, []string{strconv.FormatInt(endDay.AddDate(0, 0, -6).Unix(), 10)}, reqs[0].query["start"]) + assert.Equal(t, []string{strconv.FormatInt(endDay.Add(24*time.Hour-time.Second).Unix(), 10)}, reqs[0].query["end"]) +} + +func TestSendEventsList_EndOlderThanRetentionFailsLocally(t *testing.T) { + // The server clamps start to 90 days ago, so an older --end would return an empty list with no error. + old := time.Now().UTC().AddDate(0, 0, -100).Format("2006-01-02") + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--end", old) + require.Error(t, err) + assert.Contains(t, err.Error(), "90 days") + assert.Empty(t, reqs) +} + +func TestSendEventsList_JSONLookBackPrintsNextPageOnStderr(t *testing.T) { + stdout, stderr, reqs, err := runAgainstFakeAPIWithStderr(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "7d", "--json") require.NoError(t, err) require.Len(t, reqs, 1) - assert.Equal(t, []string{strconv.FormatInt(time.Date(2026, 9, 25, 0, 0, 0, 0, time.UTC).Unix(), 10)}, reqs[0].query["start"]) - assert.Equal(t, []string{strconv.FormatInt(time.Date(2026, 10, 1, 23, 59, 59, 0, time.UTC).Unix(), 10)}, reqs[0].query["end"]) + // Stdout must stay parseable; scripts need the resolved start to page, since 7d is refused with --page-token. + var resp map[string]any + require.NoError(t, json.Unmarshal([]byte(stdout), &resp)) + assert.Contains(t, stderr, "Next page: --page-token tok-2 --start "+reqs[0].query["start"][0]) } diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 9dd4c7f..dd51f65 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -16,13 +16,17 @@ const metricsDateLayout = "2006-01-02" var ( eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) + unixPattern = regexp.MustCompile(`^[0-9]{10,12}$`) // thresholdPattern matches the API's threshold literal: no sign or exponent, up to 9 integer digits and 2 decimals. thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]{0,8})(\.[0-9]{1,2})?$`) ) -// parseActivityTime turns a --start/--end value into Unix seconds. Every time without a zone is UTC -// (including today, tomorrow and 9am), a bare date is a whole UTC day (its end for --end), and a -// duration such as 24h or 7d means that long ago. relative is true for durations, which move between runs. +// activityTimeLayouts are the absolute --start/--end forms; each means the same instant on every run. +var activityTimeLayouts = []string{time.RFC3339, "2006-01-02 15:04"} + +// parseActivityTime turns a --start/--end value into Unix seconds. It accepts Unix seconds, a UTC +// date (its last second for --end), "YYYY-MM-DD HH:MM" in UTC, RFC3339, or a look-back such as 24h +// or 7d. relative is true for look-backs, the only form that moves between runs. func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, relative bool, err error) { value = strings.TrimSpace(value) if value == "" { @@ -30,27 +34,23 @@ func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, } invalid := common.NewUserError( fmt.Sprintf("invalid --%s value %q", flag, value), - "Use a Unix timestamp, YYYY-MM-DD, RFC3339, or a look-back such as 24h or 7d; times without a zone are UTC", + `Use Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM" (UTC), RFC3339, or a look-back such as 24h or 7d`, ) - switch day, dateErr := time.ParseInLocation(metricsDateLayout, value, time.UTC); { - case dateErr == nil && isEnd: - ts = day.Add(24*time.Hour - time.Second).Unix() - case dateErr == nil: + if day, dateErr := time.ParseInLocation(metricsDateLayout, value, time.UTC); dateErr == nil { ts = day.Unix() - default: - if d, durErr := common.ParseDuration(value); durErr == nil { - if d <= 0 { - return 0, false, invalid - } - ts, relative = now.Add(-d).Unix(), true - } else { - t, parseErr := common.ParseHumanTime(value, common.ParseHumanTimeOpts{Now: now.UTC(), Loc: time.UTC}) - if parseErr != nil { - return 0, false, invalid - } - ts = t.Unix() + if isEnd { + ts = day.Add(24*time.Hour - time.Second).Unix() + } + } else if unixPattern.MatchString(value) { + ts, _ = strconv.ParseInt(value, 10, 64) + } else if d, durErr := common.ParseDuration(value); durErr == nil { + if d <= 0 { + return 0, false, invalid } + ts, relative = now.Add(-d).Unix(), true + } else { + ts = parseAbsoluteTime(value) } // The API reads 0 and below as "not set", so such a time would silently fall back to the default window. if ts <= 0 { @@ -59,6 +59,16 @@ func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, return ts, relative, nil } +// parseAbsoluteTime returns 0 when value matches no activity layout. +func parseAbsoluteTime(value string) int64 { + for _, layout := range activityTimeLayouts { + if t, err := time.ParseInLocation(layout, value, time.UTC); err == nil { + return t.Unix() + } + } + return 0 +} + // validateMetricsDate checks a --start/--end metrics value is YYYY-MM-DD. func validateMetricsDate(flag, value string) error { if value == "" { @@ -109,15 +119,15 @@ func newTable(w io.Writer, headers ...string) *common.Table { } // nextCursorNote prints the next page token; pageFlags, when set, are window flags the next page must repeat. -func nextCursorNote(cmd *cobra.Command, nextCursor, pageFlags string) { +func nextCursorNote(w io.Writer, nextCursor, pageFlags string) { if nextCursor == "" { return } if pageFlags == "" { - _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page token: %s\n", nextCursor) + _, _ = fmt.Fprintf(w, "\nNext page token: %s\n", nextCursor) return } - _, _ = fmt.Fprintf(cmd.OutOrStdout(), "\nNext page: --page-token %s %s\n", nextCursor, pageFlags) + _, _ = fmt.Fprintf(w, "\nNext page: --page-token %s %s\n", nextCursor, pageFlags) } // writeStructuredList writes a list response as JSON/YAML, or only the row IDs in quiet mode. diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go index 809ebc7..43dadb8 100644 --- a/internal/cli/deliverability/send_events.go +++ b/internal/cli/deliverability/send_events.go @@ -12,6 +12,8 @@ import ( "github.com/spf13/cobra" ) +const activityRetention = 90 * 24 * time.Hour + type activityWindowFlags struct { start, end string // pageFlags repeats a look-back window as epochs, because the page token is bound to the exact start and end. @@ -19,8 +21,8 @@ type activityWindowFlags struct { } func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { - cmd.Flags().StringVar(&f.start, "start", "", "Window start: Unix timestamp, YYYY-MM-DD, RFC3339, or look-back like 24h/7d; no zone means UTC (default: UTC midnight 6 days before --end, or before today)") - cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive; a date means the end of that UTC day (same formats; default: now)") + cmd.Flags().StringVar(&f.start, "start", "", `Window start: Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM" (UTC), RFC3339, or look-back like 24h/7d (default: UTC midnight 6 days before --end, or before today)`) + cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive, within the last 90 days; a date means the end of that UTC day (same formats; default: now)") cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") common.AddLimitFlag(cmd, limit, 50) common.AddPageTokenFlag(cmd, pageToken) @@ -36,6 +38,10 @@ func (f *activityWindowFlags) resolve(now time.Time, pageToken string) (int64, i if err != nil { return 0, 0, err } + // The server clamps start to its 90-day retention, so an older --end would return nothing with no error. + if end != 0 && end < now.Add(-activityRetention).Unix() { + return 0, 0, common.NewUserError("--end is more than 90 days ago", "Activity is kept for 90 days; use a more recent --end") + } // Mirror the server's default start, anchored on --end, so an older --end is not before the default start. if start == 0 && end != 0 { endDay := time.Unix(end, 0).UTC().Truncate(24 * time.Hour) @@ -105,6 +111,10 @@ func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.Nyl return common.WrapListError("send events", err) } if done, err := writeStructuredList(cmd, resp, resp.Data); done { + // Stdout stays the API envelope; a look-back's resolved window goes to stderr so scripts can page. + if err == nil && pageFlags != "" { + nextCursorNote(cmd.ErrOrStderr(), resp.NextCursor, pageFlags) + } return err } if len(resp.Data) == 0 { @@ -118,7 +128,7 @@ func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.Nyl table.AddRow(formatUnix(e.Timestamp), sendEventLabel(e.EventType, e.BounceClass), e.Recipient, e.From, e.Reason, e.ID) } table.Render() - nextCursorNote(cmd, resp.NextCursor, pageFlags) + nextCursorNote(cmd.OutOrStdout(), resp.NextCursor, pageFlags) return nil } diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go index 52d2d47..eda9b91 100644 --- a/internal/cli/deliverability/tracking_events.go +++ b/internal/cli/deliverability/tracking_events.go @@ -51,6 +51,10 @@ func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports return common.WrapListError("tracking events", err) } if done, err := writeStructuredList(cmd, resp, resp.Data); done { + // Stdout stays the API envelope; a look-back's resolved window goes to stderr so scripts can page. + if err == nil && pageFlags != "" { + nextCursorNote(cmd.ErrOrStderr(), resp.NextCursor, pageFlags) + } return err } if len(resp.Data) == 0 { @@ -64,7 +68,7 @@ func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports table.AddRow(formatUnix(e.Timestamp), e.EventType, yesNo(e.IsFirst), e.From, e.Label, derefString(e.URL), e.ID) } table.Render() - nextCursorNote(cmd, resp.NextCursor, pageFlags) + nextCursorNote(cmd.OutOrStdout(), resp.NextCursor, pageFlags) return nil } From 2cc1fba6fc26fc813c8324038c1ee588899d3921 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 14:07:43 -0500 Subject: [PATCH 5/8] [TW-8105] Address fourth review: UTC output you can paste back, quiet paging, demo timeline - All printed times are UTC ("2026-10-29 16:13:55 UTC"), and --start/--end accept that form back, plus zoneless "YYYY-MM-DD HH:MM[:SS]" and "YYYY-MM-DDTHH:MM[:SS]". - --quiet always writes the next-page line to stderr (it was missing for absolute windows); send and tracking lists share one writeStructuredPage helper. - Demo timeline is derived from the demo events by recipient and time; the demo test checks order, current status and recipient. - Test for an --end one hour inside the 90-day retention. Co-Authored-By: Claude Opus 5.5 --- docs/commands/deliverability.md | 6 ++- .../adapters/nylas/demo_deliverability.go | 40 ++++++++--------- internal/adapters/nylas/demo_test.go | 15 +++++++ .../cli/deliverability/deliverability_test.go | 32 ++++++++++++++ internal/cli/deliverability/helpers.go | 43 ++++++++++++++----- internal/cli/deliverability/send_events.go | 8 +--- .../cli/deliverability/tracking_events.go | 6 +-- 7 files changed, 106 insertions(+), 44 deletions(-) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 2d35232..670bd78 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -18,11 +18,13 @@ The two kinds of command take different time formats: | Commands | `--start` / `--end` | Default | Limit | |---|---|---|---| -| `list` (activity) | Unix seconds, `YYYY-MM-DD`, `"YYYY-MM-DD HH:MM"` (UTC), RFC3339, or a look-back such as `24h`, `7d`, `2w` | `--end` = now, `--start` = UTC midnight 6 days before `--end` | 90 days. An older `--start` is moved to 90 days ago; an older `--end` is rejected. | +| `list` (activity) | Unix seconds, `YYYY-MM-DD`, `"YYYY-MM-DD HH:MM[:SS]"` or `YYYY-MM-DDTHH:MM[:SS]` (UTC), RFC3339, or a look-back such as `24h`, `7d`, `2w` | `--end` = now, `--start` = UTC midnight 6 days before `--end` | 90 days. An older `--start` is moved to 90 days ago; an older `--end` is rejected. | | `summary`, `timeseries`, `breakdown` (metrics) | UTC date, `YYYY-MM-DD`, both days included | `--end` = today, `--start` = 6 days before `--end` | 365 days | A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, a time without a zone is UTC, and a bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. Words such as `today` or `9am` are not accepted, because they mean a different time on each run. +All times the CLI prints are UTC, for example `2026-10-29 16:13:55 UTC`. You can paste a printed time straight into `--start` or `--end`. + --- ## Send events @@ -49,7 +51,7 @@ nylas deliverability send-events breakdown --group-by recipient_domain --sort bo **`list` filters:** `--event-type` (repeatable: `accepted`, `delivered`, `bounced`, `complaint`, `rejected`), `--bounce-class` (`hard`, `soft`, `undetermined`), `--sending-domain`, `--from`, `--grant-id`, `--recipient`, `--recipient-domain`, `--message-id`, `--thread-id`, `--order asc|desc`. -**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start ` instead, with `--end ` too if you set `--end`. Run the next page with exactly those flags. (Without `--end`, the token itself keeps the end time.) With `--json`, `--format yaml` or `--quiet`, the same line goes to stderr, so stdout stays the plain API response. +**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start ` instead, with `--end ` too if you set `--end`. Run the next page with exactly those flags. (Without `--end`, the token itself keeps the end time.) With `--quiet`, stdout is only IDs, so the next-page line always goes to stderr. With `--json` or `--format yaml`, the response body already has `next_cursor`; after a look-back the `Next page:` line also goes to stderr, because the body does not show the resolved window. **`summary`:** health is always graded on the **last 7 days**, whatever window you ask for. The states are `healthy`, `at_risk`, `critical` and `insufficient_data` (fewer than 100 sends). Totals and rate tiles use your window and compare it with the period of the same length just before it. When the state is `at_risk` or `critical`, `summary` also lists up to 3 findings. diff --git a/internal/adapters/nylas/demo_deliverability.go b/internal/adapters/nylas/demo_deliverability.go index a44ba93..21d0e41 100644 --- a/internal/adapters/nylas/demo_deliverability.go +++ b/internal/adapters/nylas/demo_deliverability.go @@ -1,7 +1,9 @@ package nylas import ( + "cmp" "context" + "slices" "time" "github.com/nylas/cli/internal/domain" @@ -60,28 +62,24 @@ func (d *DemoClient) GetSendEvent(ctx context.Context, eventID string) (*domain. func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { events := demoSendEvents(time.Now().Unix()) - delivered, bounced, aliceAccepted, bobAccepted := events[0], events[1], events[2], events[3] - return &domain.SendMessageActivity{ - Message: domain.SendMessageEnvelope{MessageID: messageID, ApplicationID: demoDeliverabilityApp, - From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, - SentAt: aliceAccepted.Timestamp, LastEventAt: delivered.Timestamp}, - Recipients: []domain.SendMessageRecipient{ - {Recipient: delivered.Recipient, RecipientDomain: delivered.RecipientDomain, CurrentStatus: "delivered", - Events: timelineOf(aliceAccepted, delivered)}, - {Recipient: bounced.Recipient, RecipientDomain: bounced.RecipientDomain, CurrentStatus: "bounced", BounceClass: "hard", - Events: timelineOf(bobAccepted, bounced)}, - }, - }, nil -} - -// timelineOf turns send events, oldest first, into a recipient timeline. -func timelineOf(events ...domain.SendEvent) []domain.SendTimelineEvent { - timeline := make([]domain.SendTimelineEvent, 0, len(events)) - for _, e := range events { - timeline = append(timeline, domain.SendTimelineEvent{ID: e.ID, EventType: e.EventType, Timestamp: e.Timestamp, - BounceClass: e.BounceClass, Reason: e.Reason, Detail: e.Detail}) + slices.SortFunc(events, func(a, b domain.SendEvent) int { return cmp.Compare(a.Timestamp, b.Timestamp) }) + + activity := &domain.SendMessageActivity{Message: domain.SendMessageEnvelope{MessageID: messageID, + ApplicationID: demoDeliverabilityApp, From: demoDeliverabilityFrom, SendingDomain: demoDeliverabilityDomain, + SentAt: events[0].Timestamp, LastEventAt: events[len(events)-1].Timestamp}} + for _, recipient := range []string{"alice@example.org", "bob@example.net"} { + r := domain.SendMessageRecipient{Recipient: recipient} + for _, e := range events { + if e.Recipient != recipient { + continue + } + r.RecipientDomain, r.CurrentStatus, r.BounceClass = e.RecipientDomain, e.EventType, e.BounceClass + r.Events = append(r.Events, domain.SendTimelineEvent{ID: e.ID, EventType: e.EventType, Timestamp: e.Timestamp, + BounceClass: e.BounceClass, Reason: e.Reason, Detail: e.Detail}) + } + activity.Recipients = append(activity.Recipients, r) } - return timeline + return activity, nil } func (d *DemoClient) ListTrackingEvents(ctx context.Context, params *domain.TrackingEventListParams) (*domain.TrackingEventListResponse, error) { diff --git a/internal/adapters/nylas/demo_test.go b/internal/adapters/nylas/demo_test.go index 55ddce8..b7d3275 100644 --- a/internal/adapters/nylas/demo_test.go +++ b/internal/adapters/nylas/demo_test.go @@ -434,7 +434,22 @@ func TestDemoClientSendEventsAgree(t *testing.T) { want[e.ID] = e.EventType } for _, r := range activity.Recipients { + if len(r.Events) == 0 { + t.Fatalf("recipient %s has no timeline", r.Recipient) + } + // A recipient's status is where its timeline ends, and the timeline reads oldest first. + if last := r.Events[len(r.Events)-1]; r.CurrentStatus != last.EventType { + t.Errorf("%s status is %s but the timeline ends with %s", r.Recipient, r.CurrentStatus, last.EventType) + } + for i := 1; i < len(r.Events); i++ { + if r.Events[i].Timestamp < r.Events[i-1].Timestamp { + t.Errorf("%s timeline is not oldest first", r.Recipient) + } + } for _, e := range r.Events { + if got, err := client.GetSendEvent(ctx, e.ID); err != nil || got.Recipient != r.Recipient { + t.Errorf("event %s is listed under %s but belongs to another recipient", e.ID, r.Recipient) + } // GetSendEvent falls back for unknown IDs, so a timeline-only ID must be caught here. typ, ok := want[e.ID] if !ok { diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index a1f75b0..9c55819 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -265,6 +265,10 @@ func TestParseActivityTime(t *testing.T) { // Without a zone the result must not depend on the laptop's time zone. {name: "zoneless date-time is UTC", value: "2026-10-01 07:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, {name: "RFC3339 keeps its zone", value: "2026-10-01T07:00:00-04:00", want: time.Date(2026, 10, 1, 11, 0, 0, 0, time.UTC)}, + {name: "zoneless ISO with seconds is UTC", value: "2026-10-01T07:00:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, + {name: "zoneless ISO without seconds is UTC", value: "2026-10-01T07:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, + {name: "date-time with seconds is UTC", value: "2026-10-01 07:00:00", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, + {name: "printed form with UTC suffix", value: "2026-10-01 07:00:00 UTC", want: time.Date(2026, 10, 1, 7, 0, 0, 0, time.UTC)}, // Keyword and time-of-day forms resolve differently from run to run (and 9am rolls to tomorrow), // which breaks --page-token, so only look-backs may move and they are flagged as relative. {name: "today rejected", value: "today", wantErr: true}, @@ -372,3 +376,31 @@ func TestSendEventsList_JSONLookBackPrintsNextPageOnStderr(t *testing.T) { require.NoError(t, json.Unmarshal([]byte(stdout), &resp)) assert.Contains(t, stderr, "Next page: --page-token tok-2 --start "+reqs[0].query["start"][0]) } + +func TestFormatUnix_RoundTripsAsInput(t *testing.T) { + // Users copy times from the tables into --start/--end, so every printed time must parse back to itself. + ts := time.Date(2026, 10, 29, 16, 13, 55, 0, time.UTC).Unix() + printed := formatUnix(ts) + assert.Equal(t, "2026-10-29 16:13:55 UTC", printed) + got, relative, err := parseActivityTime("start", printed, time.Now(), false) + require.NoError(t, err) + assert.False(t, relative) + assert.Equal(t, ts, got) +} + +func TestSendEventsList_QuietPrintsNextPageOnStderr(t *testing.T) { + stdout, stderr, _, err := runAgainstFakeAPIWithStderr(t, http.StatusOK, sendEventsPage, + "send-events", "list", "--start", "2026-10-29", "--quiet") + require.NoError(t, err) + // Quiet stdout is only IDs, so the token must go to stderr or a script can never reach page 2. + assert.Equal(t, "aaa\nbbb\n", stdout) + assert.Contains(t, stderr, "Next page token: tok-2") +} + +func TestSendEventsList_EndJustInsideRetentionIsSent(t *testing.T) { + // Guards the edge of the 90-day check: one hour inside the server's floor must still be allowed. + end := time.Now().UTC().Add(-activityRetention + time.Hour).Format("2006-01-02 15:04") + _, reqs, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--end", end) + require.NoError(t, err) + require.Len(t, reqs, 1) +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index dd51f65..5ad06b1 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -21,20 +21,27 @@ var ( thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]{0,8})(\.[0-9]{1,2})?$`) ) -// activityTimeLayouts are the absolute --start/--end forms; each means the same instant on every run. -var activityTimeLayouts = []string{time.RFC3339, "2006-01-02 15:04"} +const displayTimeLayout = "2006-01-02 15:04:05" + +// activityTimeLayouts are the absolute --start/--end forms; zoneless ones are UTC, so each means the same instant on every run. +var activityTimeLayouts = []string{ + time.RFC3339, + displayTimeLayout, "2006-01-02 15:04", + "2006-01-02T15:04:05", "2006-01-02T15:04", +} // parseActivityTime turns a --start/--end value into Unix seconds. It accepts Unix seconds, a UTC -// date (its last second for --end), "YYYY-MM-DD HH:MM" in UTC, RFC3339, or a look-back such as 24h -// or 7d. relative is true for look-backs, the only form that moves between runs. +// date (its last second for --end), a UTC date-time with or without seconds (an optional trailing +// " UTC", as the CLI prints it), RFC3339, or a look-back such as 24h or 7d. relative is true for +// look-backs, the only form that moves between runs. func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, relative bool, err error) { - value = strings.TrimSpace(value) + value = strings.TrimSuffix(strings.TrimSpace(value), " UTC") if value == "" { return 0, false, nil } invalid := common.NewUserError( fmt.Sprintf("invalid --%s value %q", flag, value), - `Use Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM" (UTC), RFC3339, or a look-back such as 24h or 7d`, + `Use Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" (UTC), RFC3339, or a look-back such as 24h or 7d`, ) if day, dateErr := time.ParseInLocation(metricsDateLayout, value, time.UTC); dateErr == nil { @@ -88,11 +95,12 @@ func validateEventID(id string) error { return nil } +// formatUnix prints a time in UTC, in a form --start/--end accept back. func formatUnix(ts int64) string { if ts == 0 { return "" } - return time.Unix(ts, 0).Local().Format("2006-01-02 15:04:05") + return time.Unix(ts, 0).UTC().Format(displayTimeLayout) + " UTC" } // formatRate prints a percentage; nil means no data (a zero denominator), never 0%. @@ -132,14 +140,29 @@ func nextCursorNote(w io.Writer, nextCursor, pageFlags string) { // writeStructuredList writes a list response as JSON/YAML, or only the row IDs in quiet mode. func writeStructuredList(cmd *cobra.Command, resp, rows any) (bool, error) { - quiet, _ := cmd.Flags().GetBool("quiet") - format, _ := cmd.Flags().GetString("format") - if quiet || format == "quiet" { + if isQuiet(cmd) { return true, common.GetOutputWriter(cmd).WriteList(rows, nil) } return writeStructured(cmd, resp) } +// writeStructuredPage is writeStructuredList for a paged feed. Stdout stays the IDs or the API +// envelope; the next-page line goes to stderr whenever stdout does not already carry it: always in +// quiet mode, and after a look-back in JSON/YAML (the envelope has next_cursor but not the window). +func writeStructuredPage(cmd *cobra.Command, resp, rows any, nextCursor, pageFlags string) (bool, error) { + done, err := writeStructuredList(cmd, resp, rows) + if done && err == nil && (isQuiet(cmd) || pageFlags != "") { + nextCursorNote(cmd.ErrOrStderr(), nextCursor, pageFlags) + } + return done, err +} + +func isQuiet(cmd *cobra.Command) bool { + quiet, _ := cmd.Flags().GetBool("quiet") + format, _ := cmd.Flags().GetString("format") + return quiet || format == "quiet" +} + // writeStructured writes v as JSON/YAML/quiet and reports whether it did. func writeStructured(cmd *cobra.Command, v any) (bool, error) { if !common.IsStructuredOutput(cmd) { diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go index 43dadb8..30b00e3 100644 --- a/internal/cli/deliverability/send_events.go +++ b/internal/cli/deliverability/send_events.go @@ -21,7 +21,7 @@ type activityWindowFlags struct { } func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { - cmd.Flags().StringVar(&f.start, "start", "", `Window start: Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM" (UTC), RFC3339, or look-back like 24h/7d (default: UTC midnight 6 days before --end, or before today)`) + cmd.Flags().StringVar(&f.start, "start", "", `Window start: Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" (UTC), RFC3339, or look-back like 24h/7d (default: UTC midnight 6 days before --end, or before today)`) cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive, within the last 90 days; a date means the end of that UTC day (same formats; default: now)") cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") common.AddLimitFlag(cmd, limit, 50) @@ -110,11 +110,7 @@ func runSendEventsList(ctx context.Context, cmd *cobra.Command, client ports.Nyl if err != nil { return common.WrapListError("send events", err) } - if done, err := writeStructuredList(cmd, resp, resp.Data); done { - // Stdout stays the API envelope; a look-back's resolved window goes to stderr so scripts can page. - if err == nil && pageFlags != "" { - nextCursorNote(cmd.ErrOrStderr(), resp.NextCursor, pageFlags) - } + if done, err := writeStructuredPage(cmd, resp, resp.Data, resp.NextCursor, pageFlags); done { return err } if len(resp.Data) == 0 { diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go index eda9b91..527798e 100644 --- a/internal/cli/deliverability/tracking_events.go +++ b/internal/cli/deliverability/tracking_events.go @@ -50,11 +50,7 @@ func runTrackingEventsList(ctx context.Context, cmd *cobra.Command, client ports if err != nil { return common.WrapListError("tracking events", err) } - if done, err := writeStructuredList(cmd, resp, resp.Data); done { - // Stdout stays the API envelope; a look-back's resolved window goes to stderr so scripts can page. - if err == nil && pageFlags != "" { - nextCursorNote(cmd.ErrOrStderr(), resp.NextCursor, pageFlags) - } + if done, err := writeStructuredPage(cmd, resp, resp.Data, resp.NextCursor, pageFlags); done { return err } if len(resp.Data) == 0 { From 64a19eac98d539b736445dd9888ab0bae045ce4c Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 14:20:14 -0500 Subject: [PATCH 6/8] [TW-8105] Quiet list output prints only IDs; document the UTC time exception - --quiet no longer writes the next-page line to stderr, so pipelines that merge stderr get only IDs; scripts page with --json (next_cursor). After a look-back, --json/--format yaml still get the "Next page:" line on stderr. - State in code and docs that deliverability prints UTC, unlike the CLI's local common.Display* layouts, so printed times paste back into --start/--end. Co-Authored-By: Claude Opus 5.5 --- docs/commands/deliverability.md | 4 ++-- .../cli/deliverability/deliverability_test.go | 17 ++++++++++------- internal/cli/deliverability/helpers.go | 9 +++++---- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 670bd78..72b555e 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -23,7 +23,7 @@ The two kinds of command take different time formats: A look-back value counts back from now. For example, `--start 24h` means "24 hours ago". On `list`, a time without a zone is UTC, and a bare date is a whole UTC day: `--start 2026-10-01` starts at 00:00:00Z and `--end 2026-10-01` ends at 23:59:59Z. Words such as `today` or `9am` are not accepted, because they mean a different time on each run. -All times the CLI prints are UTC, for example `2026-10-29 16:13:55 UTC`. You can paste a printed time straight into `--start` or `--end`. +Unlike most `nylas` commands, which show local time, deliverability commands print UTC, for example `2026-10-29 16:13:55 UTC`. This matches the API and the UTC days used by metrics, and you can paste a printed time straight into `--start` or `--end`. --- @@ -51,7 +51,7 @@ nylas deliverability send-events breakdown --group-by recipient_domain --sort bo **`list` filters:** `--event-type` (repeatable: `accepted`, `delivered`, `bounced`, `complaint`, `rejected`), `--bounce-class` (`hard`, `soft`, `undetermined`), `--sending-domain`, `--from`, `--grant-id`, `--recipient`, `--recipient-domain`, `--message-id`, `--thread-id`, `--order asc|desc`. -**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start ` instead, with `--end ` too if you set `--end`. Run the next page with exactly those flags. (Without `--end`, the token itself keeps the end time.) With `--quiet`, stdout is only IDs, so the next-page line always goes to stderr. With `--json` or `--format yaml`, the response body already has `next_cursor`; after a look-back the `Next page:` line also goes to stderr, because the body does not show the resolved window. +**Paging:** `list` shows one page (`--limit`, default 50, max 200). When there are more rows it prints `Next page token: …`. Pass that token with `--page-token`. Keep the other flags the same, because the token belongs to that exact query, including `--start` and `--end`. A look-back such as `7d` gives a different time on every run, so it cannot be used with `--page-token`. When page 1 used a look-back, the CLI prints `Next page: --page-token … --start ` instead, with `--end ` too if you set `--end`. Run the next page with exactly those flags. (Without `--end`, the token itself keeps the end time.) `--quiet` prints only IDs and never a page token. To page from a script, use `--json` and read `next_cursor` from the body. After a look-back, `--json` and `--format yaml` also write the `Next page:` line to stderr, because the body does not show the resolved window. **`summary`:** health is always graded on the **last 7 days**, whatever window you ask for. The states are `healthy`, `at_risk`, `critical` and `insufficient_data` (fewer than 100 sends). Totals and rate tiles use your window and compare it with the period of the same length just before it. When the state is `at_risk` or `critical`, `summary` also lists up to 3 findings. diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 9c55819..5f592a7 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -388,13 +388,16 @@ func TestFormatUnix_RoundTripsAsInput(t *testing.T) { assert.Equal(t, ts, got) } -func TestSendEventsList_QuietPrintsNextPageOnStderr(t *testing.T) { - stdout, stderr, _, err := runAgainstFakeAPIWithStderr(t, http.StatusOK, sendEventsPage, - "send-events", "list", "--start", "2026-10-29", "--quiet") - require.NoError(t, err) - // Quiet stdout is only IDs, so the token must go to stderr or a script can never reach page 2. - assert.Equal(t, "aaa\nbbb\n", stdout) - assert.Contains(t, stderr, "Next page token: tok-2") +func TestSendEventsList_QuietPrintsOnlyIDs(t *testing.T) { + // Pipelines such as `list -q 2>&1 | xargs ... show` merge stderr into stdout, so quiet must print + // only IDs, even when there is a next page or a look-back; scripts page with --json instead. + for _, start := range []string{"2026-10-29", "7d"} { + stdout, stderr, _, err := runAgainstFakeAPIWithStderr(t, http.StatusOK, sendEventsPage, + "send-events", "list", "--start", start, "--quiet") + require.NoError(t, err, start) + assert.Equal(t, "aaa\nbbb\n", stdout, start) + assert.Empty(t, stderr, start) + } } func TestSendEventsList_EndJustInsideRetentionIsSent(t *testing.T) { diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 5ad06b1..578d0d4 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -21,6 +21,7 @@ var ( thresholdPattern = regexp.MustCompile(`^(0|[1-9][0-9]{0,8})(\.[0-9]{1,2})?$`) ) +// displayTimeLayout is UTC, unlike the CLI's local common.Display* layouts, so printed times paste back into --start/--end. const displayTimeLayout = "2006-01-02 15:04:05" // activityTimeLayouts are the absolute --start/--end forms; zoneless ones are UTC, so each means the same instant on every run. @@ -146,12 +147,12 @@ func writeStructuredList(cmd *cobra.Command, resp, rows any) (bool, error) { return writeStructured(cmd, resp) } -// writeStructuredPage is writeStructuredList for a paged feed. Stdout stays the IDs or the API -// envelope; the next-page line goes to stderr whenever stdout does not already carry it: always in -// quiet mode, and after a look-back in JSON/YAML (the envelope has next_cursor but not the window). +// writeStructuredPage is writeStructuredList for a paged feed. Quiet prints only IDs, so pipelines +// that merge stderr stay clean; after a look-back, JSON/YAML also gets the next-page line on stderr, +// because the envelope has next_cursor but not the resolved window. func writeStructuredPage(cmd *cobra.Command, resp, rows any, nextCursor, pageFlags string) (bool, error) { done, err := writeStructuredList(cmd, resp, rows) - if done && err == nil && (isQuiet(cmd) || pageFlags != "") { + if done && err == nil && !isQuiet(cmd) && pageFlags != "" { nextCursorNote(cmd.ErrOrStderr(), nextCursor, pageFlags) } return done, err From 02223ce125f540a9c0281f85a45efdbfeb7c0775 Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 14:46:05 -0500 Subject: [PATCH 7/8] [TW-8105] Help text: Agent Account/Transactional send scope, ID hints, alert flag clarity - Every deliverability command's help states it covers only Agent Account and Transactional send messages (not connected Google/Microsoft grants), matching the API reference; tracking help adds that tracking must be on. - show/message/update/delete explain where the ID comes from and have examples. - send-alerts create marks its required flags; update says unset flags keep their value; delete --yes says it is required. - --start help and parse hint list the YYYY-MM-DDTHH:MM[:SS] form. - Docs: scope statement in docs/commands/deliverability.md and COMMANDS.md. Co-Authored-By: Claude Opus 5.5 --- docs/COMMANDS.md | 2 +- docs/commands/deliverability.md | 2 + internal/cli/deliverability/deliverability.go | 28 +++++++++-- .../cli/deliverability/deliverability_test.go | 49 +++++++++++++++++++ internal/cli/deliverability/helpers.go | 6 ++- internal/cli/deliverability/metrics.go | 9 +++- internal/cli/deliverability/send_alerts.go | 44 +++++++++++------ internal/cli/deliverability/send_events.go | 16 ++++-- .../cli/deliverability/tracking_events.go | 11 ++++- 9 files changed, 139 insertions(+), 28 deletions(-) diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 79ff61d..f971962 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -539,7 +539,7 @@ nylas deliverability send-alerts update --threshold 3 nylas deliverability send-alerts delete --yes ``` -**Auth:** application-level (API key, no grant). **Time:** activity `--start/--end` take timestamps or look-backs (`24h`, `7d`); metrics take UTC dates `YYYY-MM-DD`. +**Scope:** Agent Account and Transactional send messages only; connected-grant (Google, Microsoft) sends are not included. **Auth:** application-level (API key, no grant). **Time:** activity `--start/--end` take timestamps or look-backs (`24h`, `7d`); metrics take UTC dates `YYYY-MM-DD`. **Details:** `docs/commands/deliverability.md` diff --git a/docs/commands/deliverability.md b/docs/commands/deliverability.md index 72b555e..17248a7 100644 --- a/docs/commands/deliverability.md +++ b/docs/commands/deliverability.md @@ -8,6 +8,8 @@ Use `nylas deliverability` to see what happened to the email your application se | `tracking-events` | Opens, link clicks and engagement metrics | `/v3/activity/tracking`, `/v3/metrics/tracking` | | `send-alerts` | Alert rules on send rates | `/v3/alerts/send` | +**These commands cover Agent Account and Transactional send messages only.** Messages sent from a connected grant, such as a Google or Microsoft account, aren't included. Tracking events exist only for messages sent with open or link tracking turned on. See [Monitor delivery and engagement](https://developer.nylas.com/docs/v3/agent-accounts/monitor-delivery-engagement/) in the API docs. + All of these routes are application-level. They use your API key (`nylas auth config` or `NYLAS_API_KEY`) and do not take a grant. A grant access token gets `403 api.forbidden`. --- diff --git a/internal/cli/deliverability/deliverability.go b/internal/cli/deliverability/deliverability.go index 58e1421..37d31e9 100644 --- a/internal/cli/deliverability/deliverability.go +++ b/internal/cli/deliverability/deliverability.go @@ -2,7 +2,23 @@ // activity, send and tracking metrics, and send alert rules. package deliverability -import "github.com/spf13/cobra" +import ( + "strings" + + "github.com/spf13/cobra" +) + +// scopeNote matches the API reference: these routes cover Agent Account and Transactional send only. +const scopeNote = "Covers only messages sent from an Agent Account or through Transactional send. " + + "Messages from connected grants, such as Google or Microsoft accounts, are not included." + +// trackingNote narrows scopeNote for tracking events. +const trackingNote = "Only messages sent with open or link tracking turned on have tracking events." + +// longHelp builds a command's Long help: the short description, the scope note, then any extra lines. +func longHelp(short string, extra ...string) string { + return strings.Join(append([]string{short, scopeNote}, extra...), "\n\n") +} // NewDeliverabilityCmd creates the deliverability command group. func NewDeliverabilityCmd() *cobra.Command { @@ -16,7 +32,9 @@ func NewDeliverabilityCmd() *cobra.Command { send-alerts Rules that fire the alert.triggered webhook when a send rate crosses a threshold These commands are application-level: they use your API key and do not take a grant. -Activity covers the last 90 days. Metrics accept windows of up to 365 days.`, +Activity covers the last 90 days. Metrics accept windows of up to 365 days. + +` + scopeNote, } cmd.AddCommand(newSendEventsCmd()) @@ -30,6 +48,7 @@ func newSendEventsCmd() *cobra.Command { cmd := &cobra.Command{ Use: "send-events", Short: "Send activity and send metrics", + Long: longHelp("Send activity and send metrics."), } cmd.AddCommand(newSendEventsListCmd()) cmd.AddCommand(newSendEventsShowCmd()) @@ -44,6 +63,7 @@ func newTrackingEventsCmd() *cobra.Command { cmd := &cobra.Command{ Use: "tracking-events", Short: "Open and click activity and engagement metrics", + Long: longHelp("Open and click activity and engagement metrics.", trackingNote), } cmd.AddCommand(newTrackingEventsListCmd()) cmd.AddCommand(newTrackingEventsShowCmd()) @@ -58,9 +78,9 @@ func newSendAlertsCmd() *cobra.Command { cmd := &cobra.Command{ Use: "send-alerts", Short: "Manage send alert rules", - Long: `Manage send alert rules. Each rule is evaluated per sending domain. When it fires, + Long: longHelp(`Manage send alert rules. Each rule is evaluated per sending domain. When it fires, Nylas sends the alert.triggered webhook to your application's webhook subscriptions. -An application can have at most 20 rules.`, +An application can have at most 20 rules.`, "Rules are evaluated for those messages only."), } cmd.AddCommand(newSendAlertsListCmd()) cmd.AddCommand(newSendAlertsShowCmd()) diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 5f592a7..9f8a823 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -7,11 +7,13 @@ import ( "net/http" "net/http/httptest" "strconv" + "strings" "testing" "time" "github.com/fatih/color" "github.com/nylas/cli/internal/cli/testutil" + "github.com/spf13/cobra" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -407,3 +409,50 @@ func TestSendEventsList_EndJustInsideRetentionIsSent(t *testing.T) { require.NoError(t, err) require.Len(t, reqs, 1) } + +// allCommands returns root and every descendant command. +func allCommands(cmd *cobra.Command) []*cobra.Command { + cmds := []*cobra.Command{cmd} + for _, c := range cmd.Commands() { + cmds = append(cmds, allCommands(c)...) + } + return cmds +} + +func TestHelpStatesScope(t *testing.T) { + // Users must see that sends from connected grants (Google, Microsoft) are not in this data; + // a new subcommand without the note should fail here. + for _, c := range allCommands(NewDeliverabilityCmd()) { + assert.Contains(t, c.Long, "Agent Account", c.CommandPath()) + assert.Contains(t, c.Long, "Transactional send", c.CommandPath()) + } +} + +func TestIDCommandsHaveExamples(t *testing.T) { + // A command that takes an ID must show what the ID looks like. + for _, c := range allCommands(NewDeliverabilityCmd()) { + if strings.Contains(c.Use, "<") { + assert.NotEmpty(t, c.Example, c.CommandPath()) + } + } +} + +func TestAlertFlagHelp(t *testing.T) { + root := NewDeliverabilityCmd() + find := func(args ...string) *cobra.Command { + c, _, err := root.Find(args) + require.NoError(t, err) + return c + } + create, update, del := find("send-alerts", "create"), find("send-alerts", "update"), find("send-alerts", "delete") + // create rejects a request without these, so the help must say so up front. + for _, name := range []string{"metric", "threshold", "window-hours"} { + assert.Contains(t, create.Flags().Lookup(name).Usage, "(required)", name) + } + // update is a partial PUT, so no flag has a default that would overwrite the rule. + for _, name := range []string{"metric", "threshold", "window-hours", "min-volume"} { + assert.Contains(t, update.Flags().Lookup(name).Usage, "unchanged if not set", name) + assert.NotContains(t, update.Flags().Lookup(name).Usage, "default", name) + } + assert.Contains(t, del.Flags().Lookup("yes").Usage, "required") +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 578d0d4..0887914 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -14,6 +14,10 @@ import ( const metricsDateLayout = "2006-01-02" +// messageIDNote tells users where a message ID comes from and how to pass one with angle brackets. +const messageIDNote = "Use `message_id` from `list --json` or from the send response. For a Transactional send " + + "this is the Message-ID header, angle brackets included; quote it in the shell." + var ( eventIDPattern = regexp.MustCompile(`^[0-9a-f]{64}$`) unixPattern = regexp.MustCompile(`^[0-9]{10,12}$`) @@ -42,7 +46,7 @@ func parseActivityTime(flag, value string, now time.Time, isEnd bool) (ts int64, } invalid := common.NewUserError( fmt.Sprintf("invalid --%s value %q", flag, value), - `Use Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" (UTC), RFC3339, or a look-back such as 24h or 7d`, + `Use Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" or YYYY-MM-DDTHH:MM[:SS] (UTC), RFC3339, or a look-back such as 24h or 7d`, ) if day, dateErr := time.ParseInLocation(metricsDateLayout, value, time.UTC); dateErr == nil { diff --git a/internal/cli/deliverability/metrics.go b/internal/cli/deliverability/metrics.go index 48d2e5f..6da87d4 100644 --- a/internal/cli/deliverability/metrics.go +++ b/internal/cli/deliverability/metrics.go @@ -13,11 +13,12 @@ import ( type metricsRunner func(ctx context.Context, cmd *cobra.Command, client ports.NylasClient, params *domain.MetricsParams) error // newMetricsCmd builds a metrics command with the shared --start/--end/--sending-domain flags. -func newMetricsCmd(use, short, example string, run metricsRunner, extraFlags func(*cobra.Command, *domain.MetricsParams)) *cobra.Command { +func newMetricsCmd(use, short, long, example string, run metricsRunner, extraFlags func(*cobra.Command, *domain.MetricsParams)) *cobra.Command { var params domain.MetricsParams cmd := &cobra.Command{ Use: use, Short: short, + Long: long, Example: example, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { @@ -57,6 +58,7 @@ func addBreakdownFlags(groupBy []string, sortKeys string) func(*cobra.Command, * func newSendSummaryCmd() *cobra.Command { return newMetricsCmd("summary", "Show send health, totals, and rates", + longHelp("Show send health, totals, and rates. Health always grades the last 7 days."), ` nylas deliverability send-events summary nylas deliverability send-events summary --start 2026-10-01 --end 2026-10-31 --sending-domain mail.example.com`, runSendSummary, nil) @@ -64,30 +66,35 @@ func newSendSummaryCmd() *cobra.Command { func newSendTimeseriesCmd() *cobra.Command { return newMetricsCmd("timeseries", "Show send counts and rates per day, week, or month", + longHelp("Show send counts and rates per day, week, or month."), ` nylas deliverability send-events timeseries --granularity week --start 2026-08-01`, runSendTimeseries, addGranularityFlag) } func newSendBreakdownCmd() *cobra.Command { return newMetricsCmd("breakdown", "Show send counts and rates per sending domain, agent account, or recipient domain", + longHelp("Show send counts and rates per sending domain, agent account, or recipient domain."), ` nylas deliverability send-events breakdown --group-by recipient_domain --sort bounce_rate:desc`, runSendBreakdown, addBreakdownFlags(domain.SendMetricsGroupBy, "key, sent, delivery_rate, bounce_rate, complaint_rate (default sent:desc)")) } func newTrackingSummaryCmd() *cobra.Command { return newMetricsCmd("summary", "Show engagement totals and open and click rates", + longHelp("Show engagement totals and open and click rates.", trackingNote), ` nylas deliverability tracking-events summary --start 2026-10-01`, runTrackingSummary, nil) } func newTrackingTimeseriesCmd() *cobra.Command { return newMetricsCmd("timeseries", "Show engagement counts and rates per day, week, or month", + longHelp("Show engagement counts and rates per day, week, or month.", trackingNote), ` nylas deliverability tracking-events timeseries --granularity day`, runTrackingTimeseries, addGranularityFlag) } func newTrackingBreakdownCmd() *cobra.Command { return newMetricsCmd("breakdown", "Show engagement per sending domain or agent account", + longHelp("Show engagement per sending domain or agent account.", trackingNote), ` nylas deliverability tracking-events breakdown --group-by agent_account --sort open_rate:desc`, runTrackingBreakdown, addBreakdownFlags(domain.TrackingMetricsGroupBy, "key, tracked_opens, tracked_links, open_rate, click_rate (default tracked_opens:desc)")) } diff --git a/internal/cli/deliverability/send_alerts.go b/internal/cli/deliverability/send_alerts.go index d3694a1..730b969 100644 --- a/internal/cli/deliverability/send_alerts.go +++ b/internal/cli/deliverability/send_alerts.go @@ -12,6 +12,8 @@ import ( "github.com/spf13/cobra" ) +const ruleIDNote = "Use a rule ID from `send-alerts list`." + type alertRuleFlags struct { metric string threshold string @@ -19,12 +21,17 @@ type alertRuleFlags struct { minVolume int64 } -func addAlertRuleFlags(cmd *cobra.Command, f *alertRuleFlags) { - cmd.Flags().StringVar(&f.metric, "metric", "", "Metric: "+strings.Join(domain.SendAlertMetrics, ", ")) +// addAlertRuleFlags adds the rule flags; create marks the core three required, update says unset flags keep their value. +func addAlertRuleFlags(cmd *cobra.Command, f *alertRuleFlags, forCreate bool) { + required, minVolumeNote := " (required)", " (default 0)" + if !forCreate { + required, minVolumeNote = " (unchanged if not set)", " (unchanged if not set)" + } + cmd.Flags().StringVar(&f.metric, "metric", "", "Metric: "+strings.Join(domain.SendAlertMetrics, ", ")+required) cmd.Flags().StringVar(&f.threshold, "threshold", "", - "Threshold percent, up to 2 decimals; bounce/complaint fire above it (0 to <100), delivery fires below it (>0 to 100)") - cmd.Flags().Int64Var(&f.windowHours, "window-hours", 0, "Look-back window in hours, 1-24") - cmd.Flags().Int64Var(&f.minVolume, "min-volume", 0, "Minimum sends in the window before the rule can fire (default 0)") + "Threshold percent, up to 2 decimals; bounce/complaint fire above it (0 to <100), delivery fires below it (>0 to 100)"+required) + cmd.Flags().Int64Var(&f.windowHours, "window-hours", 0, "Look-back window in hours, 1-24"+required) + cmd.Flags().Int64Var(&f.minVolume, "min-volume", 0, "Minimum sends in the window before the rule can fire"+minVolumeNote) } // buildAlertRuleRequest includes only the flags the user set, so update leaves the rest unchanged. @@ -54,6 +61,7 @@ func newSendAlertsListCmd() *cobra.Command { return &cobra.Command{ Use: "list", Short: "List send alert rules", + Long: longHelp("List send alert rules."), Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { @@ -83,9 +91,11 @@ func newSendAlertsListCmd() *cobra.Command { func newSendAlertsShowCmd() *cobra.Command { return &cobra.Command{ - Use: "show ", - Short: "Show a send alert rule", - Args: cobra.ExactArgs(1), + Use: "show ", + Short: "Show a send alert rule", + Long: longHelp("Show a send alert rule.", ruleIDNote), + Example: ` nylas deliverability send-alerts show 3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { rule, err := client.GetSendAlertRule(ctx, args[0]) @@ -104,6 +114,7 @@ func newSendAlertsCreateCmd() *cobra.Command { cmd := &cobra.Command{ Use: "create", Short: "Create a send alert rule", + Long: longHelp("Create a send alert rule.", "--metric, --threshold and --window-hours are required."), Example: ` nylas deliverability send-alerts create --metric bounce_rate --threshold 5 --window-hours 1 --min-volume 50 nylas deliverability send-alerts create --metric delivery_rate --threshold 95 --window-hours 24`, Args: cobra.NoArgs, @@ -125,7 +136,7 @@ func newSendAlertsCreateCmd() *cobra.Command { return err }, } - addAlertRuleFlags(cmd, &flags) + addAlertRuleFlags(cmd, &flags, true) _ = cmd.MarkFlagRequired("metric") _ = cmd.MarkFlagRequired("threshold") _ = cmd.MarkFlagRequired("window-hours") @@ -135,8 +146,10 @@ func newSendAlertsCreateCmd() *cobra.Command { func newSendAlertsUpdateCmd() *cobra.Command { var flags alertRuleFlags cmd := &cobra.Command{ - Use: "update ", - Short: "Change a send alert rule; flags you leave out keep their value", + Use: "update ", + Short: "Change a send alert rule; flags you leave out keep their value", + Long: longHelp("Change a send alert rule.", ruleIDNote, + "Only the flags you set are sent; the rest of the rule keeps its value. At least one flag is required."), Example: ` nylas deliverability send-alerts update --threshold 3`, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { @@ -160,15 +173,17 @@ func newSendAlertsUpdateCmd() *cobra.Command { return err }, } - addAlertRuleFlags(cmd, &flags) + addAlertRuleFlags(cmd, &flags, false) return cmd } func newSendAlertsDeleteCmd() *cobra.Command { var yes bool cmd := &cobra.Command{ - Use: "delete ", - Short: "Delete a send alert rule", + Use: "delete ", + Short: "Delete a send alert rule", + Long: longHelp("Delete a send alert rule. It stops firing immediately.", ruleIDNote, + "--yes is required; there is no confirmation prompt."), Example: ` nylas deliverability send-alerts delete --yes`, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { @@ -188,6 +203,7 @@ func newSendAlertsDeleteCmd() *cobra.Command { }, } common.AddYesFlag(cmd, &yes) + cmd.Flags().Lookup("yes").Usage = "Confirm the deletion (required; there is no prompt)" return cmd } diff --git a/internal/cli/deliverability/send_events.go b/internal/cli/deliverability/send_events.go index 30b00e3..97e02b6 100644 --- a/internal/cli/deliverability/send_events.go +++ b/internal/cli/deliverability/send_events.go @@ -21,7 +21,7 @@ type activityWindowFlags struct { } func addActivityWindowFlags(cmd *cobra.Command, f *activityWindowFlags, order *string, limit *int, pageToken *string) { - cmd.Flags().StringVar(&f.start, "start", "", `Window start: Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" (UTC), RFC3339, or look-back like 24h/7d (default: UTC midnight 6 days before --end, or before today)`) + cmd.Flags().StringVar(&f.start, "start", "", `Window start: Unix seconds, YYYY-MM-DD, "YYYY-MM-DD HH:MM[:SS]" or YYYY-MM-DDTHH:MM[:SS] (UTC), RFC3339, or look-back like 24h/7d (default: UTC midnight 6 days before --end, or before today)`) cmd.Flags().StringVar(&f.end, "end", "", "Window end, inclusive, within the last 90 days; a date means the end of that UTC day (same formats; default: now)") cmd.Flags().StringVar(order, "order", "", "Sort order: desc (newest first, default) or asc") common.AddLimitFlag(cmd, limit, 50) @@ -74,6 +74,7 @@ func newSendEventsListCmd() *cobra.Command { cmd := &cobra.Command{ Use: "list", Short: "List send events (newest first)", + Long: longHelp("List send events, newest first."), Example: ` nylas deliverability send-events list --event-type bounced --start 24h nylas deliverability send-events list --recipient-domain gmail.com --event-type bounced --event-type complaint nylas deliverability send-events list --message-id "" --json`, @@ -132,7 +133,10 @@ func newSendEventsShowCmd() *cobra.Command { return &cobra.Command{ Use: "show ", Short: "Show one send event with its provider detail", - Args: cobra.ExactArgs(1), + Long: longHelp("Show one send event with its provider detail.", + "Use an ID from the EVENT ID column of `send-events list`, or `id` in `list --json`."), + Example: ` nylas deliverability send-events show 5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { if err := validateEventID(args[0]); err != nil { return err @@ -190,9 +194,11 @@ func printSendEvent(cmd *cobra.Command, e *domain.SendEvent) { func newSendEventsMessageCmd() *cobra.Command { return &cobra.Command{ - Use: "message ", - Short: "Show every recipient's send timeline for one message", - Args: cobra.ExactArgs(1), + Use: "message ", + Short: "Show every recipient's send timeline for one message", + Long: longHelp("Show every recipient's send timeline for one message.", messageIDNote), + Example: ` nylas deliverability send-events message ""`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { activity, err := client.GetSendMessageActivity(ctx, args[0]) diff --git a/internal/cli/deliverability/tracking_events.go b/internal/cli/deliverability/tracking_events.go index 527798e..4a25caa 100644 --- a/internal/cli/deliverability/tracking_events.go +++ b/internal/cli/deliverability/tracking_events.go @@ -18,6 +18,7 @@ func newTrackingEventsListCmd() *cobra.Command { cmd := &cobra.Command{ Use: "list", Short: "List opens and link clicks (newest first)", + Long: longHelp("List opens and link clicks, newest first.", trackingNote), Example: ` nylas deliverability tracking-events list --event-type link_clicked --start 7d nylas deliverability tracking-events list --label welcome-campaign --json`, Args: cobra.NoArgs, @@ -72,7 +73,10 @@ func newTrackingEventsShowCmd() *cobra.Command { return &cobra.Command{ Use: "show ", Short: "Show one open or link click", - Args: cobra.ExactArgs(1), + Long: longHelp("Show one open or link click.", trackingNote, + "Use an ID from the EVENT ID column of `tracking-events list`, or `id` in `list --json`."), + Example: ` nylas deliverability tracking-events show 5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { if err := validateEventID(args[0]); err != nil { return err @@ -122,7 +126,10 @@ func newTrackingEventsMessageCmd() *cobra.Command { return &cobra.Command{ Use: "message ", Short: "Show open and click totals and the newest 100 interactions for one message", - Args: cobra.ExactArgs(1), + Long: longHelp("Show open and click totals, clicks per link, and the newest 100 interactions for one message.", + trackingNote, messageIDNote), + Example: ` nylas deliverability tracking-events message ""`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { activity, err := client.GetTrackingMessageActivity(ctx, args[0]) From 7c562a59b3770be650feffc0ef559901782fe7ff Mon Sep 17 00:00:00 2001 From: Jess Huynh Date: Mon, 2 Nov 2026 15:47:57 -0500 Subject: [PATCH 8/8] [TW-8105] Fix --json --format quiet output and make YAML keys match JSON - isQuiet now uses the shared output-format resolution (--quiet, then --json, then --format), so --format quiet --json prints the JSON envelope instead of a bare array of rows. - Deliverability output types get yaml tags matching their json tags, and embedded structs are inlined, so --format yaml has the same keys and nesting as --json and the API (was eventtype, bouncedhard, nested sendcounts). Co-Authored-By: Claude Opus 5.5 --- .../cli/deliverability/deliverability_test.go | 18 ++ internal/cli/deliverability/helpers.go | 6 +- internal/domain/deliverability_activity.go | 194 +++++++++--------- internal/domain/deliverability_alerts.go | 18 +- internal/domain/deliverability_metrics.go | 172 ++++++++-------- internal/domain/deliverability_yaml_test.go | 88 ++++++++ 6 files changed, 301 insertions(+), 195 deletions(-) create mode 100644 internal/domain/deliverability_yaml_test.go diff --git a/internal/cli/deliverability/deliverability_test.go b/internal/cli/deliverability/deliverability_test.go index 9f8a823..e359dc8 100644 --- a/internal/cli/deliverability/deliverability_test.go +++ b/internal/cli/deliverability/deliverability_test.go @@ -456,3 +456,21 @@ func TestAlertFlagHelp(t *testing.T) { } assert.Contains(t, del.Flags().Lookup("yes").Usage, "required") } + +func TestSendEventsList_JSONBeatsFormatQuiet(t *testing.T) { + // The shape must follow the CLI-wide precedence (--quiet, then --json, then --format), + // or a script asking for JSON gets a bare array with no next_cursor. + out, _, err := runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "2026-10-29", "--format", "quiet", "--json") + require.NoError(t, err) + var resp struct { + Data []map[string]any `json:"data"` + NextCursor string `json:"next_cursor"` + } + require.NoError(t, json.Unmarshal([]byte(out), &resp), out) + assert.Len(t, resp.Data, 2) + assert.Equal(t, "tok-2", resp.NextCursor) + + out, _, err = runAgainstFakeAPI(t, http.StatusOK, sendEventsPage, "send-events", "list", "--start", "2026-10-29", "--quiet", "--json") + require.NoError(t, err) + assert.Equal(t, "aaa\nbbb\n", out) +} diff --git a/internal/cli/deliverability/helpers.go b/internal/cli/deliverability/helpers.go index 0887914..6e06bb8 100644 --- a/internal/cli/deliverability/helpers.go +++ b/internal/cli/deliverability/helpers.go @@ -9,6 +9,7 @@ import ( "time" "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/ports" "github.com/spf13/cobra" ) @@ -162,10 +163,9 @@ func writeStructuredPage(cmd *cobra.Command, resp, rows any, nextCursor, pageFla return done, err } +// isQuiet uses the shared format resolution (--quiet, then --json, then --format) so it agrees with the writer. func isQuiet(cmd *cobra.Command) bool { - quiet, _ := cmd.Flags().GetBool("quiet") - format, _ := cmd.Flags().GetString("format") - return quiet || format == "quiet" + return common.GetOutputOptions(cmd, nil).Format == ports.FormatQuiet } // writeStructured writes v as JSON/YAML/quiet and reports whether it did. diff --git a/internal/domain/deliverability_activity.go b/internal/domain/deliverability_activity.go index 52b5155..9ae2714 100644 --- a/internal/domain/deliverability_activity.go +++ b/internal/domain/deliverability_activity.go @@ -42,36 +42,36 @@ type TrackingEventListParams struct { // SendEventDetail carries provider (SES) detail for a send event. type SendEventDetail struct { - SMTPResponse string `json:"smtp_response,omitempty"` - ProcessingTimeMs int64 `json:"processing_time_ms,omitempty"` - ReportingMTA string `json:"reporting_mta,omitempty"` - RemoteMTAIP string `json:"remote_mta_ip,omitempty"` - BounceType string `json:"bounce_type,omitempty"` - BounceSubtype string `json:"bounce_subtype,omitempty"` - Status string `json:"status,omitempty"` - Action string `json:"action,omitempty"` - DiagnosticCode string `json:"diagnostic_code,omitempty"` - FeedbackType string `json:"feedback_type,omitempty"` - ComplaintSubtype string `json:"complaint_subtype,omitempty"` + SMTPResponse string `yaml:"smtp_response,omitempty" json:"smtp_response,omitempty"` + ProcessingTimeMs int64 `yaml:"processing_time_ms,omitempty" json:"processing_time_ms,omitempty"` + ReportingMTA string `yaml:"reporting_mta,omitempty" json:"reporting_mta,omitempty"` + RemoteMTAIP string `yaml:"remote_mta_ip,omitempty" json:"remote_mta_ip,omitempty"` + BounceType string `yaml:"bounce_type,omitempty" json:"bounce_type,omitempty"` + BounceSubtype string `yaml:"bounce_subtype,omitempty" json:"bounce_subtype,omitempty"` + Status string `yaml:"status,omitempty" json:"status,omitempty"` + Action string `yaml:"action,omitempty" json:"action,omitempty"` + DiagnosticCode string `yaml:"diagnostic_code,omitempty" json:"diagnostic_code,omitempty"` + FeedbackType string `yaml:"feedback_type,omitempty" json:"feedback_type,omitempty"` + ComplaintSubtype string `yaml:"complaint_subtype,omitempty" json:"complaint_subtype,omitempty"` } // SendEvent is one row of the send activity feed. type SendEvent struct { - ID string `json:"id"` - EventType string `json:"event_type"` - BounceClass string `json:"bounce_class,omitempty"` - Timestamp int64 `json:"timestamp"` - ApplicationID string `json:"application_id"` - GrantID string `json:"grant_id"` - MessageID string `json:"message_id"` - ThreadID string `json:"thread_id"` - From string `json:"from"` - SendingDomain string `json:"sending_domain"` - Recipient string `json:"recipient"` - RecipientDomain string `json:"recipient_domain"` - Subject *string `json:"subject,omitempty"` - Reason string `json:"reason"` - Detail *SendEventDetail `json:"detail,omitempty"` + ID string `yaml:"id" json:"id"` + EventType string `yaml:"event_type" json:"event_type"` + BounceClass string `yaml:"bounce_class,omitempty" json:"bounce_class,omitempty"` + Timestamp int64 `yaml:"timestamp" json:"timestamp"` + ApplicationID string `yaml:"application_id" json:"application_id"` + GrantID string `yaml:"grant_id" json:"grant_id"` + MessageID string `yaml:"message_id" json:"message_id"` + ThreadID string `yaml:"thread_id" json:"thread_id"` + From string `yaml:"from" json:"from"` + SendingDomain string `yaml:"sending_domain" json:"sending_domain"` + Recipient string `yaml:"recipient" json:"recipient"` + RecipientDomain string `yaml:"recipient_domain" json:"recipient_domain"` + Subject *string `yaml:"subject,omitempty" json:"subject,omitempty"` + Reason string `yaml:"reason" json:"reason"` + Detail *SendEventDetail `yaml:"detail,omitempty" json:"detail,omitempty"` } // QuietField returns the event ID for quiet output. @@ -79,66 +79,66 @@ func (e SendEvent) QuietField() string { return e.ID } // SendEventListResponse is one page of the send activity feed. type SendEventListResponse struct { - Data []SendEvent `json:"data"` - NextCursor string `json:"next_cursor,omitempty"` - RequestID string `json:"request_id,omitempty"` + Data []SendEvent `yaml:"data" json:"data"` + NextCursor string `yaml:"next_cursor,omitempty" json:"next_cursor,omitempty"` + RequestID string `yaml:"request_id,omitempty" json:"request_id,omitempty"` } // SendMessageEnvelope describes the message in a per-message send view. type SendMessageEnvelope struct { - MessageID string `json:"message_id"` - ThreadID string `json:"thread_id"` - GrantID string `json:"grant_id"` - ApplicationID string `json:"application_id"` - From string `json:"from"` - SendingDomain string `json:"sending_domain"` - Subject *string `json:"subject,omitempty"` - SentAt int64 `json:"sent_at"` - LastEventAt int64 `json:"last_event_at"` + MessageID string `yaml:"message_id" json:"message_id"` + ThreadID string `yaml:"thread_id" json:"thread_id"` + GrantID string `yaml:"grant_id" json:"grant_id"` + ApplicationID string `yaml:"application_id" json:"application_id"` + From string `yaml:"from" json:"from"` + SendingDomain string `yaml:"sending_domain" json:"sending_domain"` + Subject *string `yaml:"subject,omitempty" json:"subject,omitempty"` + SentAt int64 `yaml:"sent_at" json:"sent_at"` + LastEventAt int64 `yaml:"last_event_at" json:"last_event_at"` } // SendTimelineEvent is one event in a recipient's timeline. type SendTimelineEvent struct { - ID string `json:"id"` - EventType string `json:"event_type"` - Timestamp int64 `json:"timestamp"` - BounceClass string `json:"bounce_class,omitempty"` - Reason string `json:"reason"` - Detail *SendEventDetail `json:"detail,omitempty"` + ID string `yaml:"id" json:"id"` + EventType string `yaml:"event_type" json:"event_type"` + Timestamp int64 `yaml:"timestamp" json:"timestamp"` + BounceClass string `yaml:"bounce_class,omitempty" json:"bounce_class,omitempty"` + Reason string `yaml:"reason" json:"reason"` + Detail *SendEventDetail `yaml:"detail,omitempty" json:"detail,omitempty"` } // SendMessageRecipient is one recipient's status and timeline. type SendMessageRecipient struct { - Recipient string `json:"recipient"` - RecipientDomain string `json:"recipient_domain"` - CurrentStatus string `json:"current_status"` - BounceClass string `json:"bounce_class,omitempty"` - Events []SendTimelineEvent `json:"events"` + Recipient string `yaml:"recipient" json:"recipient"` + RecipientDomain string `yaml:"recipient_domain" json:"recipient_domain"` + CurrentStatus string `yaml:"current_status" json:"current_status"` + BounceClass string `yaml:"bounce_class,omitempty" json:"bounce_class,omitempty"` + Events []SendTimelineEvent `yaml:"events" json:"events"` } // SendMessageActivity is the response of GET /v3/activity/send/messages/{message_id}. type SendMessageActivity struct { - Message SendMessageEnvelope `json:"message"` - Recipients []SendMessageRecipient `json:"recipients"` + Message SendMessageEnvelope `yaml:"message" json:"message"` + Recipients []SendMessageRecipient `yaml:"recipients" json:"recipients"` } // TrackingEvent is one row of the tracking activity feed. type TrackingEvent struct { - ID string `json:"id"` - EventType string `json:"event_type"` - Timestamp int64 `json:"timestamp"` - ApplicationID string `json:"application_id"` - GrantID string `json:"grant_id"` - MessageID string `json:"message_id"` - ThreadID string `json:"thread_id"` - From string `json:"from"` - SendingDomain string `json:"sending_domain"` - Label string `json:"label"` - IsFirst bool `json:"is_first"` - URL *string `json:"url,omitempty"` - LinkIndex *int64 `json:"link_index,omitempty"` - IP string `json:"ip"` - UserAgent string `json:"user_agent"` + ID string `yaml:"id" json:"id"` + EventType string `yaml:"event_type" json:"event_type"` + Timestamp int64 `yaml:"timestamp" json:"timestamp"` + ApplicationID string `yaml:"application_id" json:"application_id"` + GrantID string `yaml:"grant_id" json:"grant_id"` + MessageID string `yaml:"message_id" json:"message_id"` + ThreadID string `yaml:"thread_id" json:"thread_id"` + From string `yaml:"from" json:"from"` + SendingDomain string `yaml:"sending_domain" json:"sending_domain"` + Label string `yaml:"label" json:"label"` + IsFirst bool `yaml:"is_first" json:"is_first"` + URL *string `yaml:"url,omitempty" json:"url,omitempty"` + LinkIndex *int64 `yaml:"link_index,omitempty" json:"link_index,omitempty"` + IP string `yaml:"ip" json:"ip"` + UserAgent string `yaml:"user_agent" json:"user_agent"` } // QuietField returns the event ID for quiet output. @@ -146,59 +146,59 @@ func (e TrackingEvent) QuietField() string { return e.ID } // TrackingEventListResponse is one page of the tracking activity feed. type TrackingEventListResponse struct { - Data []TrackingEvent `json:"data"` - NextCursor string `json:"next_cursor,omitempty"` - RequestID string `json:"request_id,omitempty"` + Data []TrackingEvent `yaml:"data" json:"data"` + NextCursor string `yaml:"next_cursor,omitempty" json:"next_cursor,omitempty"` + RequestID string `yaml:"request_id,omitempty" json:"request_id,omitempty"` } // TrackingFlags reports which tracking was enabled for a message. type TrackingFlags struct { - Opens bool `json:"opens"` - Links bool `json:"links"` + Opens bool `yaml:"opens" json:"opens"` + Links bool `yaml:"links" json:"links"` } // TrackingTotals counts interactions; FirstAt and LastAt are nil when Total is 0. type TrackingTotals struct { - Total int64 `json:"total"` - FirstAt *int64 `json:"first_at"` - LastAt *int64 `json:"last_at"` + Total int64 `yaml:"total" json:"total"` + FirstAt *int64 `yaml:"first_at" json:"first_at"` + LastAt *int64 `yaml:"last_at" json:"last_at"` } // TrackingLinkClicks counts clicks on one tracked link. type TrackingLinkClicks struct { - LinkIndex int64 `json:"link_index"` - URL string `json:"url"` - Clicks int64 `json:"clicks"` + LinkIndex int64 `yaml:"link_index" json:"link_index"` + URL string `yaml:"url" json:"url"` + Clicks int64 `yaml:"clicks" json:"clicks"` } // TrackingClickTotals counts clicks overall and per link. type TrackingClickTotals struct { - TrackingTotals - Links []TrackingLinkClicks `json:"links"` + TrackingTotals `yaml:",inline"` + Links []TrackingLinkClicks `yaml:"links" json:"links"` } // TrackingInteraction is one open or click in a per-message tracking view. type TrackingInteraction struct { - ID string `json:"id"` - EventType string `json:"event_type"` - Timestamp int64 `json:"timestamp"` - IsFirst bool `json:"is_first"` - URL *string `json:"url,omitempty"` - LinkIndex *int64 `json:"link_index,omitempty"` - IP string `json:"ip"` - UserAgent string `json:"user_agent"` + ID string `yaml:"id" json:"id"` + EventType string `yaml:"event_type" json:"event_type"` + Timestamp int64 `yaml:"timestamp" json:"timestamp"` + IsFirst bool `yaml:"is_first" json:"is_first"` + URL *string `yaml:"url,omitempty" json:"url,omitempty"` + LinkIndex *int64 `yaml:"link_index,omitempty" json:"link_index,omitempty"` + IP string `yaml:"ip" json:"ip"` + UserAgent string `yaml:"user_agent" json:"user_agent"` } // TrackingMessageActivity is the response of GET /v3/activity/tracking/messages/{message_id}. type TrackingMessageActivity struct { - MessageID string `json:"message_id"` - ThreadID string `json:"thread_id"` - GrantID string `json:"grant_id"` - From string `json:"from"` - SendingDomain string `json:"sending_domain"` - Label string `json:"label"` - Tracking TrackingFlags `json:"tracking"` - Opens TrackingTotals `json:"opens"` - Clicks TrackingClickTotals `json:"clicks"` - Events []TrackingInteraction `json:"events"` + MessageID string `yaml:"message_id" json:"message_id"` + ThreadID string `yaml:"thread_id" json:"thread_id"` + GrantID string `yaml:"grant_id" json:"grant_id"` + From string `yaml:"from" json:"from"` + SendingDomain string `yaml:"sending_domain" json:"sending_domain"` + Label string `yaml:"label" json:"label"` + Tracking TrackingFlags `yaml:"tracking" json:"tracking"` + Opens TrackingTotals `yaml:"opens" json:"opens"` + Clicks TrackingClickTotals `yaml:"clicks" json:"clicks"` + Events []TrackingInteraction `yaml:"events" json:"events"` } diff --git a/internal/domain/deliverability_alerts.go b/internal/domain/deliverability_alerts.go index c8ba86f..d84b269 100644 --- a/internal/domain/deliverability_alerts.go +++ b/internal/domain/deliverability_alerts.go @@ -7,15 +7,15 @@ var SendAlertMetrics = []string{"bounce_rate", "complaint_rate", "delivery_rate" // SendAlertRule is a send alert rule. Direction is "below" for delivery_rate and "above" otherwise. type SendAlertRule struct { - ID string `json:"id"` - ApplicationID string `json:"application_id"` - Metric string `json:"metric"` - Direction string `json:"direction"` - Threshold float64 `json:"threshold"` - WindowHours int64 `json:"window_hours"` - MinVolume int64 `json:"min_volume"` - CreatedAt int64 `json:"created_at"` - UpdatedAt int64 `json:"updated_at"` + ID string `yaml:"id" json:"id"` + ApplicationID string `yaml:"application_id" json:"application_id"` + Metric string `yaml:"metric" json:"metric"` + Direction string `yaml:"direction" json:"direction"` + Threshold float64 `yaml:"threshold" json:"threshold"` + WindowHours int64 `yaml:"window_hours" json:"window_hours"` + MinVolume int64 `yaml:"min_volume" json:"min_volume"` + CreatedAt int64 `yaml:"created_at" json:"created_at"` + UpdatedAt int64 `yaml:"updated_at" json:"updated_at"` } // QuietField returns the rule ID for quiet output. diff --git a/internal/domain/deliverability_metrics.go b/internal/domain/deliverability_metrics.go index 31e6509..1042f84 100644 --- a/internal/domain/deliverability_metrics.go +++ b/internal/domain/deliverability_metrics.go @@ -22,167 +22,167 @@ type MetricsParams struct { // MetricsWindow is an inclusive UTC date range. type MetricsWindow struct { - Start string `json:"start"` - End string `json:"end"` + Start string `yaml:"start" json:"start"` + End string `yaml:"end" json:"end"` } // SendCounts are send outcome counts. type SendCounts struct { - Sent int64 `json:"sent"` - Delivered int64 `json:"delivered"` - BouncedHard int64 `json:"bounced_hard"` - BouncedSoft int64 `json:"bounced_soft"` - BouncedUndetermined int64 `json:"bounced_undetermined"` - Rejected int64 `json:"rejected"` - Complaints int64 `json:"complaints"` + Sent int64 `yaml:"sent" json:"sent"` + Delivered int64 `yaml:"delivered" json:"delivered"` + BouncedHard int64 `yaml:"bounced_hard" json:"bounced_hard"` + BouncedSoft int64 `yaml:"bounced_soft" json:"bounced_soft"` + BouncedUndetermined int64 `yaml:"bounced_undetermined" json:"bounced_undetermined"` + Rejected int64 `yaml:"rejected" json:"rejected"` + Complaints int64 `yaml:"complaints" json:"complaints"` } // RateTile is a percentage with its change against the prior period. Nil means no data. type RateTile struct { - Value *float64 `json:"value"` - DeltaPP *float64 `json:"delta_pp"` - PriorValue *float64 `json:"prior_value"` + Value *float64 `yaml:"value" json:"value"` + DeltaPP *float64 `yaml:"delta_pp" json:"delta_pp"` + PriorValue *float64 `yaml:"prior_value" json:"prior_value"` } // GradedRateTile is a RateTile with a health status: ok, warn, crit or nil. type GradedRateTile struct { - RateTile - Status *string `json:"status"` + RateTile `yaml:",inline"` + Status *string `yaml:"status" json:"status"` } // SendHealthEvidence is the data behind a health finding. type SendHealthEvidence struct { - Metric string `json:"metric"` - Value float64 `json:"value"` - Threshold float64 `json:"threshold"` - Dimension string `json:"dimension"` - DimensionValue string `json:"dimension_value"` - ShareOfExcess *float64 `json:"share_of_excess,omitempty"` - Day *string `json:"day,omitempty"` - BaselineValue *float64 `json:"baseline_value,omitempty"` - Totals SendCounts `json:"totals"` - Window MetricsWindow `json:"window"` + Metric string `yaml:"metric" json:"metric"` + Value float64 `yaml:"value" json:"value"` + Threshold float64 `yaml:"threshold" json:"threshold"` + Dimension string `yaml:"dimension" json:"dimension"` + DimensionValue string `yaml:"dimension_value" json:"dimension_value"` + ShareOfExcess *float64 `yaml:"share_of_excess,omitempty" json:"share_of_excess,omitempty"` + Day *string `yaml:"day,omitempty" json:"day,omitempty"` + BaselineValue *float64 `yaml:"baseline_value,omitempty" json:"baseline_value,omitempty"` + Totals SendCounts `yaml:"totals" json:"totals"` + Window MetricsWindow `yaml:"window" json:"window"` } // SendHealthFinding explains an at_risk or critical health state. type SendHealthFinding struct { - Rule string `json:"rule"` - Severity string `json:"severity"` - Title string `json:"title"` - Evidence SendHealthEvidence `json:"evidence"` - Recommendation string `json:"recommendation"` - LogsFilter map[string]any `json:"logs_filter"` + Rule string `yaml:"rule" json:"rule"` + Severity string `yaml:"severity" json:"severity"` + Title string `yaml:"title" json:"title"` + Evidence SendHealthEvidence `yaml:"evidence" json:"evidence"` + Recommendation string `yaml:"recommendation" json:"recommendation"` + LogsFilter map[string]any `yaml:"logs_filter" json:"logs_filter"` } // SendHealth grades the last 7 days, whatever window was requested. type SendHealth struct { - State string `json:"state"` - Window MetricsWindow `json:"window"` - MinAssessVolume int64 `json:"min_assess_volume"` - Findings []SendHealthFinding `json:"findings"` + State string `yaml:"state" json:"state"` + Window MetricsWindow `yaml:"window" json:"window"` + MinAssessVolume int64 `yaml:"min_assess_volume" json:"min_assess_volume"` + Findings []SendHealthFinding `yaml:"findings" json:"findings"` } // SendRateTiles are the three graded send rates. type SendRateTiles struct { - DeliveryRate GradedRateTile `json:"delivery_rate"` - BounceRate GradedRateTile `json:"bounce_rate"` - ComplaintRate GradedRateTile `json:"complaint_rate"` + DeliveryRate GradedRateTile `yaml:"delivery_rate" json:"delivery_rate"` + BounceRate GradedRateTile `yaml:"bounce_rate" json:"bounce_rate"` + ComplaintRate GradedRateTile `yaml:"complaint_rate" json:"complaint_rate"` } // SendMetricsSummary is the response of GET /v3/metrics/send/summary. type SendMetricsSummary struct { - Health SendHealth `json:"health"` - Totals SendCounts `json:"totals"` - Metrics SendRateTiles `json:"metrics"` - PriorPeriod *MetricsWindow `json:"prior_period"` + Health SendHealth `yaml:"health" json:"health"` + Totals SendCounts `yaml:"totals" json:"totals"` + Metrics SendRateTiles `yaml:"metrics" json:"metrics"` + PriorPeriod *MetricsWindow `yaml:"prior_period" json:"prior_period"` } // SendMetricsBucket is one timeseries bucket of send counts. type SendMetricsBucket struct { - Start string `json:"start"` - End string `json:"end"` - SendCounts - BounceRate *float64 `json:"bounce_rate"` - ComplaintRate *float64 `json:"complaint_rate"` + Start string `yaml:"start" json:"start"` + End string `yaml:"end" json:"end"` + SendCounts `yaml:",inline"` + BounceRate *float64 `yaml:"bounce_rate" json:"bounce_rate"` + ComplaintRate *float64 `yaml:"complaint_rate" json:"complaint_rate"` } // SendMetricsTimeseries is the response of GET /v3/metrics/send/timeseries. type SendMetricsTimeseries struct { - Granularity string `json:"granularity"` - Buckets []SendMetricsBucket `json:"buckets"` + Granularity string `yaml:"granularity" json:"granularity"` + Buckets []SendMetricsBucket `yaml:"buckets" json:"buckets"` } // SendMetricsRow is one breakdown row; Key is "(others)" when IsOthers is true. type SendMetricsRow struct { - Key string `json:"key"` - Sent int64 `json:"sent"` - Delivered int64 `json:"delivered"` - BouncedHard int64 `json:"bounced_hard"` - Complaints int64 `json:"complaints"` - DeliveryRate *float64 `json:"delivery_rate"` - BounceRate *float64 `json:"bounce_rate"` - ComplaintRate *float64 `json:"complaint_rate"` - IsOthers bool `json:"is_others"` + Key string `yaml:"key" json:"key"` + Sent int64 `yaml:"sent" json:"sent"` + Delivered int64 `yaml:"delivered" json:"delivered"` + BouncedHard int64 `yaml:"bounced_hard" json:"bounced_hard"` + Complaints int64 `yaml:"complaints" json:"complaints"` + DeliveryRate *float64 `yaml:"delivery_rate" json:"delivery_rate"` + BounceRate *float64 `yaml:"bounce_rate" json:"bounce_rate"` + ComplaintRate *float64 `yaml:"complaint_rate" json:"complaint_rate"` + IsOthers bool `yaml:"is_others" json:"is_others"` } // SendMetricsBreakdown is the response of GET /v3/metrics/send. Window is nil when // a recipient_domain breakdown falls entirely outside the last 90 days. type SendMetricsBreakdown struct { - GroupBy string `json:"group_by"` - Window *MetricsWindow `json:"window"` - Rows []SendMetricsRow `json:"rows"` + GroupBy string `yaml:"group_by" json:"group_by"` + Window *MetricsWindow `yaml:"window" json:"window"` + Rows []SendMetricsRow `yaml:"rows" json:"rows"` } // EngagementCounts are tracking counts; Opened and Clicked count first interactions. type EngagementCounts struct { - TrackedOpens int64 `json:"tracked_opens"` - TrackedLinks int64 `json:"tracked_links"` - Opened int64 `json:"opened"` - Clicked int64 `json:"clicked"` - OpensTotal int64 `json:"opens_total"` - ClicksTotal int64 `json:"clicks_total"` + TrackedOpens int64 `yaml:"tracked_opens" json:"tracked_opens"` + TrackedLinks int64 `yaml:"tracked_links" json:"tracked_links"` + Opened int64 `yaml:"opened" json:"opened"` + Clicked int64 `yaml:"clicked" json:"clicked"` + OpensTotal int64 `yaml:"opens_total" json:"opens_total"` + ClicksTotal int64 `yaml:"clicks_total" json:"clicks_total"` } // EngagementRateTiles are the open and click rate tiles. type EngagementRateTiles struct { - OpenRate RateTile `json:"open_rate"` - ClickRate RateTile `json:"click_rate"` + OpenRate RateTile `yaml:"open_rate" json:"open_rate"` + ClickRate RateTile `yaml:"click_rate" json:"click_rate"` } // TrackingMetricsSummary is the response of GET /v3/metrics/tracking/summary. type TrackingMetricsSummary struct { - Totals EngagementCounts `json:"totals"` - Metrics EngagementRateTiles `json:"metrics"` - PriorPeriod *MetricsWindow `json:"prior_period"` + Totals EngagementCounts `yaml:"totals" json:"totals"` + Metrics EngagementRateTiles `yaml:"metrics" json:"metrics"` + PriorPeriod *MetricsWindow `yaml:"prior_period" json:"prior_period"` } // TrackingMetricsBucket is one timeseries bucket of engagement counts. type TrackingMetricsBucket struct { - Start string `json:"start"` - End string `json:"end"` - EngagementCounts - OpenRate *float64 `json:"open_rate"` - ClickRate *float64 `json:"click_rate"` + Start string `yaml:"start" json:"start"` + End string `yaml:"end" json:"end"` + EngagementCounts `yaml:",inline"` + OpenRate *float64 `yaml:"open_rate" json:"open_rate"` + ClickRate *float64 `yaml:"click_rate" json:"click_rate"` } // TrackingMetricsTimeseries is the response of GET /v3/metrics/tracking/timeseries. type TrackingMetricsTimeseries struct { - Granularity string `json:"granularity"` - Buckets []TrackingMetricsBucket `json:"buckets"` + Granularity string `yaml:"granularity" json:"granularity"` + Buckets []TrackingMetricsBucket `yaml:"buckets" json:"buckets"` } // TrackingMetricsRow is one breakdown row; Key is "(others)" when IsOthers is true. type TrackingMetricsRow struct { - Key string `json:"key"` - EngagementCounts - OpenRate *float64 `json:"open_rate"` - ClickRate *float64 `json:"click_rate"` - IsOthers bool `json:"is_others"` + Key string `yaml:"key" json:"key"` + EngagementCounts `yaml:",inline"` + OpenRate *float64 `yaml:"open_rate" json:"open_rate"` + ClickRate *float64 `yaml:"click_rate" json:"click_rate"` + IsOthers bool `yaml:"is_others" json:"is_others"` } // TrackingMetricsBreakdown is the response of GET /v3/metrics/tracking. type TrackingMetricsBreakdown struct { - GroupBy string `json:"group_by"` - Window *MetricsWindow `json:"window"` - Rows []TrackingMetricsRow `json:"rows"` + GroupBy string `yaml:"group_by" json:"group_by"` + Window *MetricsWindow `yaml:"window" json:"window"` + Rows []TrackingMetricsRow `yaml:"rows" json:"rows"` } diff --git a/internal/domain/deliverability_yaml_test.go b/internal/domain/deliverability_yaml_test.go new file mode 100644 index 0000000..ee8e6b3 --- /dev/null +++ b/internal/domain/deliverability_yaml_test.go @@ -0,0 +1,88 @@ +package domain + +import ( + "encoding/json" + "testing" + + "github.com/stretchr/testify/require" + "gopkg.in/yaml.v3" +) + +// TestDeliverabilityYAMLMatchesJSON pins that --format yaml has the same keys and nesting as --json +// (and the API): a missing yaml tag lowercases the Go name, and a missing inline nests embedded structs. +func TestDeliverabilityYAMLMatchesJSON(t *testing.T) { + f := func(v float64) *float64 { return &v } + s := func(v string) *string { return &v } + i := func(v int64) *int64 { return &v } + window := MetricsWindow{Start: "2026-10-27", End: "2026-11-02"} + counts := SendCounts{Sent: 400, Delivered: 340, BouncedHard: 50, BouncedSoft: 5, BouncedUndetermined: 1, Rejected: 2, Complaints: 3} + engagement := EngagementCounts{TrackedOpens: 9, TrackedLinks: 6, Opened: 4, Clicked: 2, OpensTotal: 8, ClicksTotal: 3} + tile := GradedRateTile{RateTile: RateTile{Value: f(12.5), DeltaPP: f(4), PriorValue: f(8.5)}, Status: s("crit")} + event := SendEvent{ID: "e1", EventType: "bounced", BounceClass: "hard", Timestamp: 1, ApplicationID: "a", GrantID: "g", + MessageID: "m", ThreadID: "th", From: "f@x.com", SendingDomain: "x.com", Recipient: "r@y.com", RecipientDomain: "y.com", + Subject: s("Hi"), Reason: "General (5.1.1)", Detail: &SendEventDetail{SMTPResponse: "550", ProcessingTimeMs: 9, + ReportingMTA: "mta", RemoteMTAIP: "1.2.3.4", BounceType: "Permanent", BounceSubtype: "General", Status: "5.1.1", + Action: "failed", DiagnosticCode: "smtp; 550", FeedbackType: "abuse", ComplaintSubtype: "x"}} + tracking := TrackingEvent{ID: "t1", EventType: "link_clicked", Timestamp: 2, ApplicationID: "a", GrantID: "g", MessageID: "m", + ThreadID: "th", From: "f@x.com", SendingDomain: "x.com", Label: "l", IsFirst: true, URL: s("https://x.com"), + LinkIndex: i(0), IP: "1.2.3.4", UserAgent: "ua"} + + values := map[string]any{ + "send list": SendEventListResponse{Data: []SendEvent{event}, NextCursor: "tok", RequestID: "req"}, + "send event": event, + "send message": SendMessageActivity{ + Message: SendMessageEnvelope{MessageID: "m", ThreadID: "th", GrantID: "g", ApplicationID: "a", From: "f@x.com", + SendingDomain: "x.com", Subject: s("Hi"), SentAt: 1, LastEventAt: 2}, + Recipients: []SendMessageRecipient{{Recipient: "r@y.com", RecipientDomain: "y.com", CurrentStatus: "bounced", + BounceClass: "hard", Events: []SendTimelineEvent{{ID: "e1", EventType: "bounced", Timestamp: 1, + BounceClass: "hard", Reason: "r", Detail: event.Detail}}}}, + }, + "tracking list": TrackingEventListResponse{Data: []TrackingEvent{tracking}, NextCursor: "tok", RequestID: "req"}, + "tracking message": TrackingMessageActivity{MessageID: "m", ThreadID: "th", GrantID: "g", From: "f@x.com", + SendingDomain: "x.com", Label: "l", Tracking: TrackingFlags{Opens: true, Links: true}, + Opens: TrackingTotals{Total: 2, FirstAt: i(1), LastAt: i(2)}, + Clicks: TrackingClickTotals{TrackingTotals: TrackingTotals{Total: 1, FirstAt: i(1), LastAt: i(1)}, Links: []TrackingLinkClicks{{LinkIndex: 0, URL: "https://x.com", Clicks: 1}}}, + Events: []TrackingInteraction{{ID: "t1", EventType: "opened", Timestamp: 1, IsFirst: true, URL: s("u"), LinkIndex: i(0), IP: "ip", UserAgent: "ua"}}}, + "send summary": SendMetricsSummary{ + Health: SendHealth{State: "critical", Window: window, MinAssessVolume: 100, Findings: []SendHealthFinding{{ + Rule: "concentration", Severity: "high", Title: "t", Recommendation: "r", LogsFilter: map[string]any{"sending_domain": "x.com"}, + Evidence: SendHealthEvidence{Metric: "bounce_rate", Value: 12.5, Threshold: 10, Dimension: "recipient_domain", + DimensionValue: "y.com", ShareOfExcess: f(0.5), Day: s("2026-10-30"), BaselineValue: f(2), Totals: counts, Window: window}}}}, + Totals: counts, + Metrics: SendRateTiles{DeliveryRate: tile, BounceRate: tile, ComplaintRate: GradedRateTile{}}, + PriorPeriod: &window, + }, + "send timeseries": SendMetricsTimeseries{Granularity: "day", Buckets: []SendMetricsBucket{{Start: "a", End: "b", + SendCounts: counts, BounceRate: f(1), ComplaintRate: nil}}}, + "send breakdown": SendMetricsBreakdown{GroupBy: "recipient_domain", Window: nil, Rows: []SendMetricsRow{{Key: "k", + Sent: 1, Delivered: 1, BouncedHard: 0, Complaints: 0, DeliveryRate: f(100), BounceRate: f(0), ComplaintRate: nil, IsOthers: true}}}, + "tracking summary": TrackingMetricsSummary{Totals: engagement, Metrics: EngagementRateTiles{ + OpenRate: RateTile{Value: f(44.4)}, ClickRate: RateTile{}}, PriorPeriod: nil}, + "tracking timeseries": TrackingMetricsTimeseries{Granularity: "week", Buckets: []TrackingMetricsBucket{{Start: "a", End: "b", + EngagementCounts: engagement, OpenRate: f(44.4), ClickRate: nil}}}, + "tracking breakdown": TrackingMetricsBreakdown{GroupBy: "agent_account", Window: &window, Rows: []TrackingMetricsRow{{Key: "k", + EngagementCounts: engagement, OpenRate: f(44.4), ClickRate: f(33.3), IsOthers: false}}}, + "alert rule": SendAlertRule{ID: "r", ApplicationID: "a", Metric: "bounce_rate", Direction: "above", Threshold: 5, + WindowHours: 1, MinVolume: 50, CreatedAt: 1, UpdatedAt: 2}, + } + + for name, v := range values { + t.Run(name, func(t *testing.T) { + jsonBytes, err := json.Marshal(v) + require.NoError(t, err) + var fromJSON any + require.NoError(t, json.Unmarshal(jsonBytes, &fromJSON)) + + yamlBytes, err := yaml.Marshal(v) + require.NoError(t, err) + var fromYAML any + require.NoError(t, yaml.Unmarshal(yamlBytes, &fromYAML)) + viaYAML, err := json.Marshal(fromYAML) + require.NoError(t, err) + var fromYAMLAsJSON any + require.NoError(t, json.Unmarshal(viaYAML, &fromYAMLAsJSON)) + + require.Equal(t, fromJSON, fromYAMLAsJSON, "YAML:\n%s", yamlBytes) + }) + } +}