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..f971962 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 +``` + +**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` + +--- + ## 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..17248a7 --- /dev/null +++ b/docs/commands/deliverability.md @@ -0,0 +1,115 @@ +# 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` | + +**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`. + +--- + +## Time windows + +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[: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. + +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`. + +--- + +## 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, 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. + +**`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..297e7be --- /dev/null +++ b/internal/adapters/nylas/deliverability_activity.go @@ -0,0 +1,121 @@ +package nylas + +import ( + "context" + "net/url" + + "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 { + 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_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..34c07c1 --- /dev/null +++ b/internal/adapters/nylas/deliverability_metrics.go @@ -0,0 +1,71 @@ +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 +} + +// metricsWindowQuery adds the window params every metrics route takes. +func metricsWindowQuery(params *domain.MetricsParams) *QueryBuilder { + 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 { + p := orEmptyMetricsParams(params) + return metricsWindowQuery(p).Add("granularity", p.Granularity).BuildURL(base) +} + +func metricsBreakdownURL(base string, params *domain.MetricsParams) string { + 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 params +} 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..21d0e41 --- /dev/null +++ b/internal/adapters/nylas/demo_deliverability.go @@ -0,0 +1,180 @@ +package nylas + +import ( + "cmp" + "context" + "slices" + "time" + + "github.com/nylas/cli/internal/domain" +) + +const ( + demoDeliverabilityApp = "demo-app-id" + demoDeliverabilityDomain = "mail.example.com" + demoDeliverabilityFrom = "agent@mail.example.com" + demoDeliverabilityMsgID = "" + demoSendEventID = "5f2c7a4e9b1d3c8f0a6e2d4b7c9f1a3e5d7b9c2f4a6e8d0b1c3f5a7e9d2b4c6f" + demoAcceptedEventID = "e7f9b1d3a5c70829416b8d0f2a4c6e8b1d3f5a7c9e2b4d6f8a0c3e5b7d9f1a2c" + demoBobAcceptedEventID = "b8d0f2a4c6e81a3c5e7092b4d6f8a1c3e5b7d9f0a2c4e6b8d1f3a5c7e9b0d2f4" + demoBouncedEventID = "c4e6a8b0d2f41638507a9cbe1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f" + demoTrackingEventID = "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90" + demoSendAlertRuleID = "3d6f8a1c-2b4e-4c7d-9f0a-1b2c3d4e5f60" +) + +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 { + 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 := 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) { + 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) { + events := demoSendEvents(time.Now().Unix()) + for i := range events { + if events[i].ID == eventID { + return &events[i], nil + } + } + fallback := events[0] + fallback.ID = eventID + return &fallback, nil +} + +func (d *DemoClient) GetSendMessageActivity(ctx context.Context, messageID string) (*domain.SendMessageActivity, error) { + events := demoSendEvents(time.Now().Unix()) + 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 activity, 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/demo_test.go b/internal/adapters/nylas/demo_test.go index 88f8e6a..b7d3275 100644 --- a/internal/adapters/nylas/demo_test.go +++ b/internal/adapters/nylas/demo_test.go @@ -414,3 +414,60 @@ 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 { + 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 { + 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) + } + } + } + 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/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..37d31e9 --- /dev/null +++ b/internal/cli/deliverability/deliverability.go @@ -0,0 +1,91 @@ +// Package deliverability implements `nylas deliverability`: send and tracking +// activity, send and tracking metrics, and send alert rules. +package deliverability + +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 { + 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. + +` + scopeNote, + } + + 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", + Long: longHelp("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", + Long: longHelp("Open and click activity and engagement metrics.", trackingNote), + } + 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: 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.`, "Rules are evaluated for those messages only."), + } + 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..e359dc8 --- /dev/null +++ b/internal/cli/deliverability/deliverability_test.go @@ -0,0 +1,476 @@ +package deliverability + +import ( + "bytes" + "encoding/json" + "io" + "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" +) + +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() + 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) { + 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) + + // 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, stderr, err := testutil.ExecuteSubCommand(NewDeliverabilityCmd(), args...) + return stdout + colorOut.String(), stderr, 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: --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) + } +} + +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: "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}, + {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. + {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) + 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) { + // 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) + 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") +} + +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. + 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) + // 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]) +} + +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_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) { + // 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) +} + +// 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") +} + +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 new file mode 100644 index 0000000..6e06bb8 --- /dev/null +++ b/internal/cli/deliverability/helpers.go @@ -0,0 +1,177 @@ +package deliverability + +import ( + "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" + +// 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}$`) + // 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})?$`) +) + +// 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. +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), 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.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[: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 { + ts = day.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 { + return 0, false, invalid + } + 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 == "" { + 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 +} + +// 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).UTC().Format(displayTimeLayout) + " UTC" +} + +// 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) +} + +// nextCursorNote prints the next page token; pageFlags, when set, are window flags the next page must repeat. +func nextCursorNote(w io.Writer, nextCursor, pageFlags string) { + if nextCursor == "" { + return + } + if pageFlags == "" { + _, _ = fmt.Fprintf(w, "\nNext page token: %s\n", nextCursor) + return + } + _, _ = 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. +func writeStructuredList(cmd *cobra.Command, resp, rows any) (bool, error) { + if isQuiet(cmd) { + return true, common.GetOutputWriter(cmd).WriteList(rows, nil) + } + return writeStructured(cmd, resp) +} + +// 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 != "" { + nextCursorNote(cmd.ErrOrStderr(), nextCursor, pageFlags) + } + 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 { + return common.GetOutputOptions(cmd, nil).Format == ports.FormatQuiet +} + +// 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..6da87d4 --- /dev/null +++ b/internal/cli/deliverability/metrics.go @@ -0,0 +1,172 @@ +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, 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 { + if err := validateMetricsDate("start", params.Start); err != nil { + return err + } + if err := validateMetricsDate("end", params.End); err != nil { + return err + } + _, 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)") + 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", + 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) +} + +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)")) +} + +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..730b969 --- /dev/null +++ b/internal/cli/deliverability/send_alerts.go @@ -0,0 +1,227 @@ +package deliverability + +import ( + "context" + "encoding/json" + "fmt" + "strings" + + "github.com/nylas/cli/internal/cli/common" + "github.com/nylas/cli/internal/domain" + "github.com/nylas/cli/internal/ports" + "github.com/spf13/cobra" +) + +const ruleIDNote = "Use a rule ID from `send-alerts list`." + +type alertRuleFlags struct { + metric string + threshold string + windowHours int64 + minVolume int64 +} + +// 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)"+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. +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") { + threshold := strings.TrimSpace(f.threshold) + if !thresholdPattern.MatchString(threshold) { + 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 + } + 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", + 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) { + rules, err := client.ListSendAlertRules(ctx) + if err != nil { + return struct{}{}, common.WrapListError("send alert rules", err) + } + if done, err := writeStructuredList(cmd, rules, rules); done { + 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 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 struct{}{}, nil + }) + return err + }, + } +} + +func newSendAlertsShowCmd() *cobra.Command { + return &cobra.Command{ + 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]) + if err != nil { + return struct{}{}, common.WrapGetError("send alert rule", err) + } + return struct{}{}, writeRule(cmd, rule) + }) + return err + }, + } +} + +func newSendAlertsCreateCmd() *cobra.Command { + var flags alertRuleFlags + 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, + RunE: func(cmd *cobra.Command, _ []string) error { + req, err := buildAlertRuleRequest(cmd, &flags) + if err != nil { + return err + } + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + rule, err := client.CreateSendAlertRule(ctx, req) + if err != nil { + return struct{}{}, common.WrapCreateError("send alert rule", err) + } + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Created send alert rule %s", rule.ID) + } + return struct{}{}, writeRule(cmd, rule) + }) + return err + }, + } + addAlertRuleFlags(cmd, &flags, true) + _ = 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", + 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 { + 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") + } + _, err = common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + rule, err := client.UpdateSendAlertRule(ctx, args[0], req) + if err != nil { + return struct{}{}, common.WrapUpdateError("send alert rule", err) + } + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Updated send alert rule %s", rule.ID) + } + return struct{}{}, writeRule(cmd, rule) + }) + return err + }, + } + addAlertRuleFlags(cmd, &flags, false) + return cmd +} + +func newSendAlertsDeleteCmd() *cobra.Command { + var yes bool + cmd := &cobra.Command{ + 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 { + if !yes { + return common.NewUserError("deletion requires confirmation", "Re-run with --yes to delete the rule") + } + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + if err := client.DeleteSendAlertRule(ctx, args[0]); err != nil { + return struct{}{}, common.WrapDeleteError("send alert rule", err) + } + if !common.IsStructuredOutput(cmd) { + common.PrintSuccess("Deleted send alert rule %s", args[0]) + } + return struct{}{}, nil + }) + return err + }, + } + common.AddYesFlag(cmd, &yes) + cmd.Flags().Lookup("yes").Usage = "Confirm the deletion (required; there is no prompt)" + 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..97e02b6 --- /dev/null +++ b/internal/cli/deliverability/send_events.go @@ -0,0 +1,248 @@ +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" +) + +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. + pageFlags string +} + +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]" 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) + common.AddPageTokenFlag(cmd, pageToken) +} + +// 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, endRelative, err := parseActivityTime("end", f.end, now, true) + 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) + 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 + + 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`, + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + var err error + 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, window.pageFlags) + }) + return err + }, + } + + 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, pageFlags string) error { + resp, err := client.ListSendEvents(ctx, params) + if err != nil { + return common.WrapListError("send events", err) + } + if done, err := writeStructuredPage(cmd, resp, resp.Data, resp.NextCursor, pageFlags); 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.OutOrStdout(), resp.NextCursor, pageFlags) + return nil +} + +func newSendEventsShowCmd() *cobra.Command { + return &cobra.Command{ + Use: "show ", + Short: "Show one send event with its provider detail", + 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 + } + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + event, err := client.GetSendEvent(ctx, args[0]) + if err != nil { + return struct{}{}, common.WrapGetError("send event", err) + } + if done, err := writeStructured(cmd, event); done { + return struct{}{}, err + } + printSendEvent(cmd, event) + return struct{}{}, nil + }) + return err + }, + } +} + +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", + 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]) + if err != nil { + return struct{}{}, common.WrapGetError("send activity for message", err) + } + if done, err := writeStructured(cmd, activity); done { + return struct{}{}, err + } + printSendMessageActivity(cmd, activity) + return struct{}{}, nil + }) + return err + }, + } +} + +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..4a25caa --- /dev/null +++ b/internal/cli/deliverability/tracking_events.go @@ -0,0 +1,208 @@ +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)", + 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, + RunE: func(cmd *cobra.Command, _ []string) error { + var err error + 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, window.pageFlags) + }) + return err + }, + } + + 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, pageFlags string) error { + resp, err := client.ListTrackingEvents(ctx, params) + if err != nil { + return common.WrapListError("tracking events", err) + } + if done, err := writeStructuredPage(cmd, resp, resp.Data, resp.NextCursor, pageFlags); 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.OutOrStdout(), resp.NextCursor, pageFlags) + return nil +} + +func newTrackingEventsShowCmd() *cobra.Command { + return &cobra.Command{ + Use: "show ", + Short: "Show one open or link click", + 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 + } + _, err := common.WithClientNoGrant(func(ctx context.Context, client ports.NylasClient) (struct{}, error) { + event, err := client.GetTrackingEvent(ctx, args[0]) + if err != nil { + return struct{}{}, common.WrapGetError("tracking event", err) + } + if done, err := writeStructured(cmd, event); done { + return struct{}{}, err + } + printTrackingEvent(cmd, event) + return struct{}{}, nil + }) + return err + }, + } +} + +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", + 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]) + if err != nil { + return struct{}{}, common.WrapGetError("tracking activity for message", err) + } + if done, err := writeStructured(cmd, activity); done { + return struct{}{}, err + } + printTrackingMessageActivity(cmd, activity) + return struct{}{}, nil + }) + return err + }, + } +} + +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..9ae2714 --- /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 `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 `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. +func (e SendEvent) QuietField() string { return e.ID } + +// SendEventListResponse is one page of the send activity feed. +type SendEventListResponse struct { + 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 `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 `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 `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 `yaml:"message" json:"message"` + Recipients []SendMessageRecipient `yaml:"recipients" json:"recipients"` +} + +// TrackingEvent is one row of the tracking activity feed. +type TrackingEvent struct { + 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. +func (e TrackingEvent) QuietField() string { return e.ID } + +// TrackingEventListResponse is one page of the tracking activity feed. +type TrackingEventListResponse struct { + 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 `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 `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 `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 `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 `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 `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 new file mode 100644 index 0000000..d84b269 --- /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 `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. +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..1042f84 --- /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 `yaml:"start" json:"start"` + End string `yaml:"end" json:"end"` +} + +// SendCounts are send outcome counts. +type SendCounts struct { + 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 `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 `yaml:",inline"` + Status *string `yaml:"status" json:"status"` +} + +// SendHealthEvidence is the data behind a health finding. +type SendHealthEvidence struct { + 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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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 `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) + }) + } +} 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)