Relevant source files

The following files were used as context for generating this wiki page: - [src/common/interfaces/index.ts](https://github.com/resend/resend-node/blob/main/src/common/interfaces/index.ts) - [src/common/interfaces/get-option.interface.ts](https://github.com/resend/resend-node/blob/main/src/common/interfaces/get-option.interface.ts) - [src/common/interfaces/post-option.interface.ts](https://github.com/resend/resend-node/blob/main/src/common/interfaces/post-option.interface.ts) - [src/common/interfaces/require-at-least-one.ts](https://github.com/resend/resend-node/blob/main/src/common/interfaces/require-at-least-one.ts) - [src/resend.ts](https://github.com/resend/resend-node/blob/main/src/resend.ts) - [src/common/utils/parse-template-to-api-options.ts](https://github.com/resend/resend-node/blob/main/src/common/utils/parse-template-to-api-options.ts) - [src/common/utils/get-pagination-query-properties.ts](https://github.com/resend/resend-node/blob/main/src/common/utils/get-pagination-query-properties.ts)

# Common Interfaces & Utilities Common Interfaces & Utilities form the foundational layer of the Resend Node.js SDK. This module provides the standardized TypeScript types and helper functions used across all API resource modules (such as Emails, Templates, and Contacts) to ensure consistent request handling, error management, and data transformation. By centralizing HTTP method options, pagination logic, and payload parsing, the SDK maintains a uniform interface for the `Resend` client class. This structure allows developers to interact with various API endpoints using consistent patterns for headers, idempotency, and query parameters. ## Core HTTP Interfaces The SDK defines specialized interfaces for different HTTP methods to control what options are available during API calls. These interfaces extend a base configuration to support custom headers and specific requirements like idempotency. ### Request Options Structure The following table summarizes the primary request option interfaces used by the internal fetch mechanism: | Interface | Purpose | Key Properties | | :--- | :--- | :--- | | `GetOptions` | Options for GET requests | `headers` | | `PostOptions` | Options for POST requests | `headers`, `query` | | `PutOptions` | Options for PUT requests | `headers` | | `PatchOptions` | Options for PATCH requests | `headers` | | `IdempotentRequest` | Support for idempotent operations | `idempotencyKey` | Sources: [src/common/interfaces/index.ts](), [src/common/interfaces/get-option.interface.ts](), [src/common/interfaces/post-option.interface.ts](), [src/common/interfaces/idempotent-request.interface.ts](), [src/resend.ts:161-165]() ### Data Flow for API Requests The `Resend` class utilizes these interfaces to construct final fetch requests. It merges global headers (like Authorization) with call-specific options. ```mermaid graph TD A[Client Call] --> B{Method Type} B -->|POST| C[PostOptions + IdempotentRequest] B -->|GET| D[GetOptions] C --> E[Merge Headers] D --> E E --> F[fetchRequest] F --> G[API Endpoint] ``` The diagram shows how method-specific options are merged with standard headers before being dispatched by the internal fetch handler. Sources: [src/resend.ts:159-215]() ## Utility Types The SDK includes TypeScript utilities to enforce strict data requirements at compile time, reducing runtime validation errors. ### RequireAtLeastOne A complex utility type used to ensure that an object contains at least one of the specified keys. This is particularly useful for API payloads where multiple optional identifiers are accepted, but at least one must be provided (e.g., providing either `html` or `react` when creating a template). ```typescript export type RequireAtLeastOne = Pick< T, Exclude > & { [K in Keys]-?: Required> & Partial>>; }[Keys]; ``` Sources: [src/common/interfaces/require-at-least-one.ts:1-8](), [src/templates/interfaces/create-template-options.interface.ts:7-10]() ## Pagination and Query Utilities Standardized pagination is handled through a consistent interface and utility functions that transform internal options into URL query strings. ### Pagination Logic The `PaginationOptions` interface provides a unified way to handle cursor-based navigation across different resource lists such as API keys, templates, and webhooks. | Property | Type | Description | | :--- | :--- | :--- | | `limit` | `number` | The number of items to return | | `before` | `string` | A cursor for use in backward pagination | | `after` | `string` | A cursor for use in forward pagination | Sources: [src/common/interfaces/pagination-options.interface.ts](), [src/templates/templates.ts:98-102]() ### Query String Construction Utilities like `getPaginationQueryProperties` and `buildPaginationQuery` take pagination objects and convert them into formatted query parameters. ```mermaid flowchart TD Start[PaginationOptions Object] --> CheckLimit{limit exists?} CheckLimit -->|Yes| AddLimit[Append limit=N] CheckLimit -->|No| CheckBefore AddLimit --> CheckBefore{before exists?} CheckBefore -->|Yes| AddBefore[Append before=UUID] CheckBefore -->|No| CheckAfter AddBefore --> CheckAfter{after exists?} CheckAfter -->|Yes| AddAfter[Append after=UUID] AddAfter --> Return[Return ?query_string] ``` This flowchart illustrates the logic used to transform internal pagination state into API-compatible query strings. Sources: [src/common/utils/get-pagination-query-properties.ts](), [src/common/utils/build-pagination-query.ts]() ## Data Transformation Utilities The SDK performs automatic transformation of payloads to ensure compatibility between JavaScript naming conventions (camelCase) and API expectations (snake_case). ### parseTemplateToApiOptions This utility processes template creation and update payloads. It performs two critical tasks: 1. **Field Mapping:** Converts fields like `replyTo` to `reply_to` and `fallbackValue` to `fallback_value` within variables. 2. **React Exclusion:** Explicitly removes the `react` property from the final API payload, as React components are rendered to HTML strings before transmission. Sources: [src/common/utils/parse-template-to-api-options.ts](), [src/common/utils/parse-template-to-api-options.spec.ts:100-115]() ### parseEmailToApiOptions Similar to template parsing, this utility prepares email objects for the `/emails` endpoint. It handles the transformation of `scheduledAt` to `scheduled_at` and ensures that if a `template` object is provided, conflicting `html` or `text` fields are handled correctly. Sources: [src/common/utils/parse-email-to-api-options.ts](), [src/common/utils/parse-email-to-api-options.spec.ts:25-45]() ## Conclusion The Common Interfaces & Utilities module provides the essential infrastructure that powers the Resend SDK. By defining strict types for HTTP options and providing robust utilities for pagination and payload transformation, the module ensures that the SDK remains maintainable and type-safe while abstracting the complexities of direct API communication.