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

  • Contact Exports: create exports with configurable filters, check export status, and obtain download URLs.
  • Client surface expanded to expose the Contact Exports API for straightforward access.

• Documentation

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

• Tests

  • Added tests covering Contact Exports workflows and client access/error cases.

[coderabbitai]

Walkthrough

Adds a Contact Exports feature: new types, API resource and wrapper, MailtrapClient getter, unit tests, an example script, and README updates to create and fetch contact export jobs and download URLs.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "Contact Exports" entries and a "### Contact Exports API" section linking the example.
Examples examples/contact-exports/everything.ts	New TypeScript example: builds filters, creates a contact export, polls/gets status and download URL, logs errors.
Types src/types/api/contact-exports.ts	New exported interfaces: ContactExportResponse, CreateContactExportFilter, CreateContactExportParams.
API Resource src/lib/api/resources/ContactExports.ts	New exported ContactExportsApi class with constructor(client, accountId), create(params) and get(exportId) targeting /api/accounts/{accountId}/contacts/exports.
API Wrapper src/lib/api/ContactExports.ts	New ContactExportsBaseAPI wrapper that binds ContactExportsApi methods (create, get) for consumer use.
Client Integration src/lib/MailtrapClient.ts	Added public getter contactExports that validates accountId presence 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 (validates accountId)
    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

• Focus review on:
  • src/lib/api/resources/ContactExports.ts — URL construction and HTTP payloads.
  • src/types/api/contact-exports.ts — operator literal set and union types.
  • src/lib/MailtrapClient.ts and src/lib/api/ContactExports.ts — accountId validation and method binding.
  • Tests (src/__tests__/**) — axios mock/interceptor correctness and assertions.

Suggested reviewers

• IgorDobryn
• VladimirTaytor
• mklocek

Poem

🐇 I hopped through types and tiny routes,
Brought exports out from nested doubts.
Filters set just right,
Downloads in sight —
A carrot file to celebrate our bouts! 🥕

Pre-merge checks and finishing touches

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Contact exports' is vague and generic, lacking specific detail about the nature of the change.	Enhance the title to be more descriptive, e.g., 'Add Contact Exports API support'.
Linked Issues check	❓ Inconclusive	Linked issue #75 title 'Get all Contacts' creates ambiguity about alignment with Contact Exports API implementation.	Clarify whether issue #75 specifically requested Contact Exports or if scope was reinterpreted.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description includes all required sections with comprehensive details about implemented features and testing.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the Contact Exports API feature with no unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 9d85c00 and 3e90cfa.

📒 Files selected for processing (2)

• README.md (2 hunks)
• src/lib/MailtrapClient.ts (2 hunks)

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

• README.md
• src/lib/MailtrapClient.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.}