Release v4.5.0 - Add Stats API

[piobeny]

Motivation

• Bump version to 4.5.0

Changes

• Bump version to 4.5.0
• Release Stats API

How to test

N/A

Examples

Summary by CodeRabbit

• New Features

  • Added Statistics API to fetch and group sending statistics by domain, category, email service provider, and date; supports date-range and array filters.

• Tests

  • Added comprehensive test suite covering all stats endpoints and error handling.

• Examples

  • Added an example demonstrating usage of the new statistics endpoints.

• Chores

  • Bumped package version to 4.5.0 and updated changelog formatting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e274a425-898b-4952-96b2-2bb99ca1556c

📥 Commits

Reviewing files that changed from the base of the PR and between 9b6f082 and 9bd5fd6.

📒 Files selected for processing (8)

• CHANGELOG.md
• examples/general/stats.ts
• package.json
• src/__tests__/lib/api/resources/Stats.test.ts
• src/index.ts
• src/lib/api/General.ts
• src/lib/api/resources/Stats.ts
• src/types/api/stats.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• src/tests/lib/api/resources/Stats.test.ts
• src/types/api/stats.ts
• examples/general/stats.ts
• package.json

---

📝 Walkthrough

Walkthrough

Adds a new StatsApi resource with five endpoints (get, byDomain, byCategory, byEmailServiceProvider, byDate), TypeScript types, tests, an example, a General API getter, and bumps package to 4.5.0; exposes stats types from the public index.

Changes

Cohort / File(s)	Summary
API Resource src/lib/api/resources/Stats.ts	New StatsApi class implementing get, byDomain, byCategory, byEmailServiceProvider, byDate; builds query params (including array params), performs requests, maps grouped responses to {name, value, stats} and validates group keys.
Types src/types/api/stats.ts	Adds SendingStats, SendingStatGroup, and StatsFilterParams type definitions for stats payloads and filters.
General Integration src/lib/api/General.ts	Adds lazy singleton stats() getter that instantiates StatsApi with the current accountId.
Public Exports src/index.ts	Re-exports stats types via export * from "./types/api/stats".
Tests src/__tests__/lib/api/resources/Stats.test.ts	Comprehensive tests for all methods, response mapping, array param serialization, interceptors, and error handling (401/404).
Examples examples/general/stats.ts	New example demonstrating all StatsApi endpoints and usage patterns with placeholder config.
Version & Changelog package.json, CHANGELOG.md	Version bumped to 4.5.0 and changelog entry added for StatsApi; minor changelog formatting fix.

Sequence Diagram

sequenceDiagram
    participant Client as User Code
    participant MailtrapClient as MailtrapClient
    participant StatsApi as StatsApi
    participant Axios as Axios
    participant Backend as Backend API

    Client->>MailtrapClient: client.stats.get(params)
    MailtrapClient->>StatsApi: initialize (lazy)
    MailtrapClient->>StatsApi: get(params)
    StatsApi->>StatsApi: buildQueryParams(params)
    StatsApi->>Axios: GET /stats?start_date=...&filters[]
    Axios->>Backend: HTTP GET
    Backend-->>Axios: JSON response
    Axios->>StatsApi: response.data
    StatsApi-->>Client: SendingStats

    alt grouped (byDomain/byCategory/byEmailServiceProvider/byDate)
        Client->>MailtrapClient: client.stats.byDomain(params)
        MailtrapClient->>StatsApi: byDomain(params)
        StatsApi->>Axios: GET /stats/grouping/:group?...
        Backend-->>Axios: JSON array
        StatsApi->>StatsApi: map to SendingStatGroup[]
        StatsApi-->>Client: SendingStatGroup[]
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

feature request

Suggested reviewers

• mklocek
• VladimirTaytor
• leonid-shevtsov

Poem

🐰 I dug a burrow in the code, so neat,
I fetched five endpoints with tiny feet,
Domains and dates in tidy rows,
Filters hopped in, and tests arose,
StatsApi blooms — a carrot of sweet! 🥕📊

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers motivation and changes but lacks required sections: 'How to test' only says 'N/A' and 'Images and GIFs' section is missing entirely from the template.	Provide proper testing instructions explaining how to verify the new Stats API functionality with examples, and indicate whether before/after images are applicable or explain why they're not needed.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Release v4.5.0 - Add Stats API' clearly summarizes the main change: releasing version 4.5.0 with a new Stats API feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch release-v4.5.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CHANGELOG.md`:
- Around line 1-2: Update the release header "## [4.5.0] - 2025-03-06" in
CHANGELOG.md to the correct 2026 release date (replace "2025-03-06" with the
actual 2026 date for the 4.5.0 release) so the chronology with "## [4.4.0] -
2025-12-08" is correct.

In `@src/lib/api/resources/Stats.ts`:
- Around line 100-121: The buildQueryParams method is manually appending "[]" to
array parameter keys (e.g., "sending_domain_ids[]") which causes
double-bracketed query strings when Axios serializes arrays; update
Stats.buildQueryParams (accepting StatsFilterParams) to use plain keys
("sending_domain_ids", "sending_streams", "categories",
"email_service_providers") without the "[]" suffix so axios.get(..., { params:
buildQueryParams(...) }) will serialize arrays correctly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d342a8a2-ed69-490b-9da4-f213fcbf0fa8

📥 Commits

Reviewing files that changed from the base of the PR and between 484d833 and 9b6f082.

📒 Files selected for processing (8)

• CHANGELOG.md
• examples/general/stats.ts
• package.json
• src/__tests__/lib/api/resources/Stats.test.ts
• src/index.ts
• src/lib/api/General.ts
• src/lib/api/resources/Stats.ts
• src/types/api/stats.ts