Contact exports

[narekhovhannisyan]

Motivation

Add support for Contact Exports API to enable exporting contacts based on filters. This allows users to export contacts from Mailtrap using various filter criteria such as list IDs, subscription status, and other contact fields.

Fixes #75

Changes

• Added Contact Exports API implementation (src/lib/api/resources/ContactExports.ts)
• Added Contact Exports base API class (src/lib/api/ContactExports.ts)
• Added TypeScript types for contact exports (src/types/api/contact-exports.ts)
• Added contactExports getter to MailtrapClient
• Created example demonstrating contact exports usage (examples/contact-exports/everything.ts)
• Added comprehensive unit tests for Contact Exports API (src/__tests__/lib/api/resources/ContactExports.test.ts)
• Added unit tests for MailtrapClient contactExports getter (src/__tests__/lib/mailtrap-client.test.ts)
• Updated README.md with Contact Exports API documentation

How to test

• Run npm test -- ContactExports.test.ts to verify all Contact Exports API tests pass
• Run npm test -- mailtrap-client.test.ts --testNamePattern="contactExports" to verify MailtrapClient getter tests pass
• Test the example: update examples/contact-exports/everything.ts with valid credentials and run npx ts-node examples/contact-exports/everything.ts
• Verify Contact Exports can be created with filters (list_id, subscription_status)
• Verify Contact Export can be retrieved by ID and status/URL are returned correctly
• Check that error handling works for invalid filters and missing account IDs

Summary by CodeRabbit

• New Features

  • Added Contact Exports: create exports with configurable filters (e.g., list, subscription status) and retrieve export status and download URLs.

• Documentation

  • README updated with Contact Exports section, API reference, and an example walkthrough demonstrating export creation and retrieval.

[coderabbitai]

Walkthrough

Adds a Contact Exports feature: types, API resource, wrapper, client getter, tests, example script, and README documentation to create and fetch contact export jobs and their download URLs.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "Contact Exports" bullet and a "### Contact Exports API" section linking to the example.
Examples examples/contact-exports/everything.ts	New TypeScript example demonstrating creating a contact export, polling/getting status, retrieving download URL, and error handling.
Type Definitions src/types/api/contact-exports.ts	New types: ContactExportResponse, CreateContactExportFilter, CreateContactExportParams.
API Resource src/lib/api/resources/ContactExports.ts	New ContactExportsApi class with constructor(client, accountId), create(params) and get(exportId) methods targeting /api/accounts/{accountId}/contacts/exports endpoints.
API Wrapper src/lib/api/ContactExports.ts	New ContactExportsBaseAPI wrapper binding ContactExportsApi methods (create, get) for higher-level use.
Client Integration src/lib/MailtrapClient.ts	Added public getter contactExports that validates accountId and returns ContactExportsBaseAPI.
Unit Tests (API) src/__tests__/lib/api/resources/ContactExports.test.ts	Tests for ContactExportsApi create/get flows and error cases (422, 404) using axios-mock-adapter and response interceptor.
Unit Tests (Client) src/__tests__/lib/mailtrap-client.test.ts	Tests for MailtrapClient.contactExports getter: error when accountId missing and returns ContactExportsBaseAPI when present.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant User
    participant Client as MailtrapClient
    participant Wrapper as ContactExportsBaseAPI
    participant Resource as ContactExportsApi
    participant API as HTTP Endpoint

    User->>Client: access contactExports
    Client->>Wrapper: instantiate (accountId validated)
    Client-->>User: ContactExportsBaseAPI

    User->>Wrapper: create(filters)
    Wrapper->>Resource: create(params)
    Resource->>API: POST /api/accounts/{accountId}/contacts/exports
    API-->>Resource: ContactExportResponse
    Resource-->>Wrapper: response
    Wrapper-->>User: response

    alt fetch status/download
        User->>Wrapper: get(exportId)
        Wrapper->>Resource: get(exportId)
        Resource->>API: GET /api/accounts/{accountId}/contacts/exports/{exportId}
        API-->>Resource: ContactExportResponse (may include url)
        Resource-->>Wrapper: response
        Wrapper-->>User: response with url
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay special attention to:
  • src/lib/api/resources/ContactExports.ts — endpoint construction, request payloads, and error handling.
  • src/types/api/contact-exports.ts — operator literal correctness and type coverage.
  • src/lib/MailtrapClient.ts and src/lib/api/ContactExports.ts — accountId validation and correct method binding/this context.
  • Tests in src/__tests__/... — axios mock setup and interceptor interactions.

Suggested reviewers

• VladimirTaytor
• IgorDobryn
• mklocek

Poem

🐇 I nibbled code through day and night,
Filters stitched and endpoints tight,
Exports humming free,
URLs for me —
A carrot download gleams in light! 🥕✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #75 requests support for retrieving all contacts when the API is ready. However, this PR implements a Contact Exports API with filtering capabilities, which is a different feature not explicitly described in the issue.	Clarify the relationship between this PR and issue #75, or verify if #75 should reference contact exports rather than contact retrieval.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Contact exports' is directly related to the main feature introduced—a Contact Exports API. However, it lacks specificity about what aspect of contact exports is being implemented.
Description check	✅ Passed	The PR description is comprehensive and well-structured, including motivation, complete list of changes, and detailed testing instructions aligned with the template structure.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the Contact Exports API feature and its integration. No unrelated or extraneous changes were identified in the provided scope.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch contact-exports-api

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between af1dd71 and 9d85c00.

📒 Files selected for processing (1)

• examples/contact-exports/everything.ts (1 hunks)

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

• examples/contact-exports/everything.ts

---

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.}