Contacts api #64
Contacts api #64
Conversation
…, bulk, and sandbox emails in batch
…ne/template structures
… in batch sending
…ejs into contacts-api
…using MailtrapClient
…actData type and structure payloads
…ionality into a single example
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the """ WalkthroughThis update introduces batch email sending and contact management features to the codebase. It adds new example scripts demonstrating batch sending and contact operations, extends the MailtrapClient API with batchSend method and contacts/contactLists getters, implements new API resource classes, updates type definitions, enhances buffer encoding flexibility, and adds comprehensive tests for these new capabilities. Documentation is updated accordingly. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant MailtrapClient
participant API
User->>MailtrapClient: batchSend(request)
MailtrapClient->>API: POST /api/batch (with encoded mail batch)
API-->>MailtrapClient: BatchSendResponse
MailtrapClient-->>User: Promise<BatchSendResponse>
sequenceDiagram
participant User
participant MailtrapClient
participant ContactsApi
participant ContactListsApi
participant API
User->>MailtrapClient: contacts.create(data)
MailtrapClient->>ContactsApi: create(data)
ContactsApi->>API: POST /accounts/{id}/contacts
API-->>ContactsApi: Contact created
ContactsApi-->>MailtrapClient: Contact response
MailtrapClient-->>User: Promise<Contact>
User->>MailtrapClient: contactLists.list()
MailtrapClient->>ContactListsApi: list()
ContactListsApi->>API: GET /accounts/{id}/contact_lists
API-->>ContactListsApi: List of contact lists
ContactListsApi-->>MailtrapClient: List response
MailtrapClient-->>User: Promise<List>
Poem
""" 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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (6)
src/lib/api/resources/contacts/ContactLists.ts (1)
8-24: ContactListsApi implementation looks good but could be enhancedThe ContactListsApi class has a clean implementation for listing contact lists. However, there are a few enhancements to consider:
- The account ID is optional in the constructor but the URL construction doesn't handle the case when it's undefined.
- There's no type definition for the response structure.
- The API doesn't support pagination which might be needed for accounts with many contact lists.
Consider adding these improvements:
import { AxiosInstance } from "axios"; import CONFIG from "../../../../config"; + import { ContactListsResponse } from "../../../../../types/mailtrap"; const { CLIENT_SETTINGS } = CONFIG; const { GENERAL_ENDPOINT } = CLIENT_SETTINGS; export default class ContactListsApi { private client: AxiosInstance; private contactListsURL: string; constructor(client: AxiosInstance, accountId?: number) { this.client = client; + if (!accountId) { + throw new Error("Account ID is required for ContactListsApi"); + } this.contactListsURL = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/lists`; } /** * Lists all contact lists for the account. + * @returns Promise with contact lists data */ - public async list() { - return this.client.get(this.contactListsURL); + public async list(params?: { page?: number; per_page?: number }) { + return this.client.get<ContactListsResponse>(this.contactListsURL, { params }); } }src/lib/api/resources/contacts/Contacts.ts (1)
21-23: Add return type annotations for better code clarityAdding explicit return type annotations to the async methods would improve code clarity and provide better TypeScript type checking.
- public async create(data: ContactData) { + public async create(data: ContactData): Promise<AxiosResponse> { return this.client.post(this.contactsURL, { contact: data }); } - public async update(id: number, data: ContactData) { + public async update(id: number, data: ContactData): Promise<AxiosResponse> { const url = `${this.contactsURL}/${id}`; return this.client.patch(url, { contact: data }); } - public async delete(id: number) { + public async delete(id: number): Promise<AxiosResponse> { const url = `${this.contactsURL}/${id}`; return this.client.delete(url); }Don't forget to also import the AxiosResponse type:
- import { AxiosInstance } from "axios"; + import { AxiosInstance, AxiosResponse } from "axios";Also applies to: 28-31, 36-39
src/lib/MailtrapClient.ts (1)
155-179: Minor clean-ups insidebatchSend
preparedRequestsstill serialises properties that areundefined; removing them trims the payload and matches classic Mailtrap examples.- const preparedRequests = request.requests.map((req) => ({ - to: req.to, - cc: req.cc, - bcc: req.bcc, - custom_variables: req.custom_variables, - })); + const preparedRequests = request.requests.map( + ({ to, cc, bcc, custom_variables }) => + Object.fromEntries( + Object.entries({ to, cc, bcc, custom_variables }).filter( + ([, v]) => v !== undefined + ) + ) + );
- A short JSDoc block describing the supported shapes (
InlineBatchSendBase | TemplateBatchSendBase) would help IDEs and consumers.src/types/mailtrap.ts (1)
79-83:BaseAddressduplicatesAddress– keep a single source of truth
BaseAddressand the earlier-declaredAddressshare the exact shape. Re-useAddressinstead of introducing a parallel type to avoid drift.-interface BaseAddress { - email: string; - name?: string; -} +type BaseAddress = Address;src/__tests__/lib/mailtrap-client.test.ts (2)
331-675: Isolate Axios mocks between test suitesThe
AxiosMockAdapterinstance is created only inside thesend()suite.
batch sendingtests run inside that suite (✓) but latercontactsandcontact listssuites rely on the samemockwithout their ownbeforeAll/afterEach, risking leftover interceptors if additional suites are appended in the future.A minimal fix is to move the adapter initialisation & reset one level up:
describe("lib/mailtrap-client: ", () => { - let mock: AxiosMockAdapter; + let mock: AxiosMockAdapter; + + beforeAll(() => { + mock = new AxiosMockAdapter(axios); + }); + + afterEach(() => { + mock.reset(); + });…and remove the nested
beforeAll / afterEachblocks.
This guarantees every test starts with a clean slate.
733-871: Expand coverage & negative cases for Contacts / Lists APIsNice positive-path assertions! Two quick wins:
- Add a test that accessing
client.contacts/client.contactListswithout anaccountIdthrowsMailtrapErroronce you implement the guard recommended above.- Verify that
fieldsandlist_idsround-trip correctly when present in responses, ensuring JSON serialisation remains symmetric.Would you like help drafting these extra tests?
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (15)
README.md(2 hunks)examples/batch/bulk.ts(1 hunks)examples/batch/sandbox.ts(1 hunks)examples/batch/template.ts(1 hunks)examples/batch/transactional.ts(1 hunks)examples/contacts/contact-lists.ts(1 hunks)examples/contacts/everything.ts(1 hunks)examples/testing/send-mail.ts(1 hunks)src/__tests__/lib/mailtrap-client.test.ts(3 hunks)src/lib/MailtrapClient.ts(3 hunks)src/lib/api/Contacts.ts(1 hunks)src/lib/api/resources/contacts/ContactLists.ts(1 hunks)src/lib/api/resources/contacts/Contacts.ts(1 hunks)src/lib/mail-buffer-encoder.ts(1 hunks)src/types/mailtrap.ts(1 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (5)
src/lib/mail-buffer-encoder.ts (1)
src/types/mailtrap.ts (1)
src/lib/api/Contacts.ts (2)
src/lib/api/resources/contacts/Contacts.ts (1)
ContactsApi(8-40)src/lib/api/resources/contacts/ContactLists.ts (1)
ContactListsApi(8-24)
src/lib/api/resources/contacts/Contacts.ts (1)
src/types/mailtrap.ts (1)
ContactData(121-125)
src/__tests__/lib/mailtrap-client.test.ts (1)
src/lib/MailtrapError.ts (1)
MailtrapError(1-1)
src/lib/MailtrapClient.ts (4)
src/lib/api/resources/contacts/Contacts.ts (1)
ContactsApi(8-40)src/lib/api/resources/contacts/ContactLists.ts (1)
ContactListsApi(8-24)src/types/mailtrap.ts (2)
BatchSendRequest(105-113)BatchSendResponse(74-77)src/lib/mail-buffer-encoder.ts (1)
encodeMailBuffers(8-33)
🪛 LanguageTool
README.md
[grammar] ~61-~61: You’ve repeated a verb. Did you mean to only write one of them?
Context: ...s](examples/general/permissions.ts) - Contacts - [Contact Lists](examples/contacts/contact-lists....
(REPEATED_VERBS)
[grammar] ~74-~74: Possible verb agreement error. Did you mean “sends”? (Some collective nouns can be treated as both singular and plural, so ‘Send’ is not always incorrect.)
Context: ...ails](examples/batch/send-batch.ts) - [Send a batch of transactional emails](exampl...
(COLLECTIVE_NOUN_VERB_AGREEMENT_VBP)
🪛 markdownlint-cli2 (0.17.2)
README.md
61-61: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
62-62: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
73-73: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
74-74: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
75-75: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
76-76: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
🔇 Additional comments (10)
examples/testing/send-mail.ts (1)
7-7: Documentation enhancement looks good!Adding a more specific link to the Demo Domain setup section is helpful for users following this example. This improves the documentation quality.
examples/contacts/contact-lists.ts (1)
1-20: Well-structured example for the new contactLists APIThis example effectively demonstrates how to use the newly added contactLists API, providing a clear pattern for users to follow. The code showcases:
- Proper initialization of the client with token and accountId
- Direct access to the contactLists getter
- Appropriate error handling
This example aligns well with the PR objective of integrating contact lists APIs into the Mailtrap client as direct getters.
README.md (2)
61-62: Documentation updates for new contact APIs look goodAdding references to the new contact-related examples aligns with the PR objective of integrating contacts and contact lists APIs into the Mailtrap client.
🧰 Tools
🪛 LanguageTool
[grammar] ~61-~61: You’ve repeated a verb. Did you mean to only write one of them?
Context: ...s](examples/general/permissions.ts) - Contacts - [Contact Lists](examples/contacts/contact-lists....(REPEATED_VERBS)
🪛 markdownlint-cli2 (0.17.2)
61-61: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
62-62: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
71-77: New Batch Sending API section enhances documentationThis new section with examples for batch sending provides valuable user guidance. While batch sending isn't mentioned in the PR objectives, it complements the contacts API integration by providing comprehensive documentation.
🧰 Tools
🪛 LanguageTool
[grammar] ~74-~74: Possible verb agreement error. Did you mean “sends”? (Some collective nouns can be treated as both singular and plural, so ‘Send’ is not always incorrect.)
Context: ...ails](examples/batch/send-batch.ts) - [Send a batch of transactional emails](exampl...(COLLECTIVE_NOUN_VERB_AGREEMENT_VBP)
🪛 markdownlint-cli2 (0.17.2)
73-73: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
74-74: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
75-75: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
76-76: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
src/lib/mail-buffer-encoder.ts (1)
8-8: Good improvement to function signature flexibilityChanging from
Partial<Mail>allows the function to handle objects with any subset ofThe implementation correctly maintains its behavior while supporting this more flexible type.
examples/batch/bulk.ts (1)
1-40: Well-structured batch email example with proper error handlingThis example clearly demonstrates how to use the batch sending API for multiple recipients with custom variables. The code structure follows best practices with promise chaining and proper error handling.
examples/batch/template.ts (1)
1-39: Clear template-based batch sending exampleThe example effectively demonstrates how to use the template-based batch sending capability with different template variables for each recipient. The code is well-structured and follows consistent patterns with other examples.
examples/contacts/everything.ts (1)
1-37: Overall good example demonstrating contact lifecycle managementThis example effectively shows the complete contact lifecycle including creation, updating, and deletion. The code is well-structured with appropriate error handling.
Also applies to: 41-44
examples/batch/transactional.ts (1)
1-37: Well-structured example demonstrating batch transactional email sendingThis example clearly demonstrates how to use the batch sending API with a well-organized structure including base email configuration, multiple recipient requests with custom variables, and proper promise handling.
examples/batch/sandbox.ts (1)
1-42: Well-implemented sandbox mode exampleThis example correctly demonstrates how to configure the client for sandbox mode with a test inbox ID and structure a batch send request with custom variables. The code follows good practices for promise handling and clearly shows the configuration differences compared to standard transactional sending.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
README.md (2)
61-62: Remove leading space before list items under "General API"
The list markers for the new "Contacts" and "Contact Lists" entries are indented and trigger markdownlint MD007. They should be aligned at the margin.- - [Contacts](examples/contacts/everything.ts) + - [Contacts](examples/contacts/everything.ts) - - [Contact Lists](examples/contacts/contact-lists.ts) + - [Contact Lists](examples/contacts/contact-lists.ts)🧰 Tools
🪛 LanguageTool
[grammar] ~61-~61: You’ve repeated a verb. Did you mean to only write one of them?
Context: ...s](examples/general/permissions.ts) - Contacts - [Contact Lists](examples/contacts/contact-lists....(REPEATED_VERBS)
🪛 markdownlint-cli2 (0.17.2)
61-61: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
62-62: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
73-76: Remove leading space before list items under "Batch Sending API"
The new batch sending example entries are indented and trigger markdownlint MD007. Align the list markers at the root margin for consistency.- - [Send a batch of emails](examples/batch/send-batch.ts) + - [Send a batch of emails](examples/batch/send-batch.ts) - - [Send a batch of transactional emails](examples/batch/transactional-batch.ts) + - [Send a batch of transactional emails](examples/batch/transactional-batch.ts) - - [Send a batch of bulk emails](examples/batch/bulk-batch.ts) + - [Send a batch of bulk emails](examples/batch/bulk-batch.ts) - - [Send a batch of sandbox emails](examples/batch/sandbox-batch.ts) + - [Send a batch of sandbox emails](examples/batch/sandbox-batch.ts)🧰 Tools
🪛 LanguageTool
[grammar] ~74-~74: Possible verb agreement error. Did you mean “sends”? (Some collective nouns can be treated as both singular and plural, so ‘Send’ is not always incorrect.)
Context: ...ails](examples/batch/send-batch.ts) - [Send a batch of transactional emails](exampl...(COLLECTIVE_NOUN_VERB_AGREEMENT_VBP)
🪛 markdownlint-cli2 (0.17.2)
73-73: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
74-74: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
75-75: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
76-76: Unordered list indentation
Expected: 0; Actual: 1(MD007, ul-indent)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (3)
README.md(2 hunks)src/lib/api/Contacts.ts(1 hunks)src/types/mailtrap.ts(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- src/types/mailtrap.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- src/lib/api/Contacts.ts
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~61-~61: You’ve repeated a verb. Did you mean to only write one of them?
Context: ...s](examples/general/permissions.ts) - Contacts - [Contact Lists](examples/contacts/contact-lists....
(REPEATED_VERBS)
[grammar] ~74-~74: Possible verb agreement error. Did you mean “sends”? (Some collective nouns can be treated as both singular and plural, so ‘Send’ is not always incorrect.)
Context: ...ails](examples/batch/send-batch.ts) - [Send a batch of transactional emails](exampl...
(COLLECTIVE_NOUN_VERB_AGREEMENT_VBP)
🪛 markdownlint-cli2 (0.17.2)
README.md
61-61: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
62-62: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
73-73: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
74-74: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
75-75: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
76-76: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
Contacts API Integration
Motivation
The contacts and contact lists APIs were not properly integrated into the Mailtrap client. We needed to add these APIs as direct getters on the
MailtrapClientclass to maintain consistency with the API design and provide easy access to contact management functionality.Changes
contactsandcontactListsgetters toMailtrapClientclassgeneralAPIHow to test
yarn testSummary by CodeRabbit
New Features
Documentation
Tests
Style