@upyo/sendgrid 0.1.0-dev.13

package/dist/index.d.cts

@@ -0,0 +1,320 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for SendGrid transport connection settings.
+ *
+ * This interface defines all available options for configuring a SendGrid
+ * API connection including authentication, HTTP options, and tracking settings.
+ *
+ * @example
+ * ```typescript
+ * const config: SendGridConfig = {
+ *   apiKey: 'your-api-key',
+ *   timeout: 30000,
+ *   retries: 3,
+ *   tracking: true
+ * };
+ * ```
+ */
+interface SendGridConfig {
+  /**
+   * Your SendGrid API key.
+   *
+   * You can find your API key in the SendGrid Control Panel under Settings > API Keys.
+   * It should start with 'SG.' for v3 API keys.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the SendGrid API.
+   *
+   * @default "https://api.sendgrid.com/v3"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether to enable click tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly clickTracking?: boolean;
+  /**
+   * Whether to enable open tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly openTracking?: boolean;
+  /**
+   * Whether to enable subscription tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly subscriptionTracking?: boolean;
+  /**
+   * Whether to enable Google Analytics tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly googleAnalytics?: boolean;
+}
+/**
+ * Resolved SendGrid configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the SendGrid transport implementation.
+ */
+type ResolvedSendGridConfig = Required<SendGridConfig>;
+/**
+ * Creates a resolved SendGrid configuration by applying default values to optional fields.
+ *
+ * This function takes a partial SendGrid configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ *
+ * @param config - The SendGrid configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ *
+ * @example
+ * ```typescript
+ * const resolved = createSendGridConfig({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // resolved.baseUrl will be 'https://api.sendgrid.com/v3' (default)
+ * // resolved.timeout will be 30000 (default)
+ * // resolved.retries will be 3 (default)
+ * ```
+ */
+declare function createSendGridConfig(config: SendGridConfig): ResolvedSendGridConfig;
+//#endregion
+//#region src/http-client.d.ts
+/**
+ * Response from SendGrid API for sending messages.
+ */
+interface SendGridResponse {
+  /**
+   * HTTP status code returned by SendGrid.
+   */
+  readonly statusCode?: number;
+  /**
+   * Response body from SendGrid (usually empty on success).
+   */
+  readonly body?: string;
+  /**
+   * Response headers from SendGrid.
+   */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * Error response from SendGrid API.
+ */
+
+/**
+ * HTTP client wrapper for SendGrid API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for SendGrid API calls.
+ */
+declare class SendGridHttpClient {
+  config: ResolvedSendGridConfig;
+  constructor(config: ResolvedSendGridConfig);
+  /**
+   * Sends a message via SendGrid API.
+   *
+   * @param messageData The JSON data to send to SendGrid.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the SendGrid response.
+   */
+  sendMessage(messageData: Record<string, unknown>, signal?: AbortSignal): Promise<SendGridResponse>;
+  /**
+   * Makes an HTTP request to SendGrid API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   */
+  makeRequest(url: string, options: RequestInit): Promise<SendGridResponse>;
+  /**
+   * Makes a fetch request with SendGrid authentication.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the fetch response.
+   */
+  fetchWithAuth(url: string, options: RequestInit): Promise<Response>;
+  /**
+   * Converts Headers object to a plain Record.
+   *
+   * @param headers The Headers object to convert.
+   * @returns A plain object with header key-value pairs.
+   */
+  headersToRecord(headers: Headers): Record<string, string>;
+}
+/**
+ * Custom error class for SendGrid API errors.
+ */
+declare class SendGridApiError extends Error {
+  readonly statusCode?: number;
+  readonly errors?: {
+    readonly message: string;
+    readonly field?: string;
+    readonly help?: string;
+  }[];
+  constructor(message: string, statusCode?: number, errors?: Array<{
+    message: string;
+    field?: string;
+    help?: string;
+  }>);
+}
+//#endregion
+//#region src/sendgrid-transport.d.ts
+/**
+ * SendGrid transport implementation for sending emails via SendGrid API.
+ *
+ * This transport provides efficient email delivery using SendGrid's v3 HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SendGridTransport } from '@upyo/sendgrid';
+ *
+ * const transport = new SendGridTransport({
+ *   apiKey: 'your-sendgrid-api-key',
+ *   clickTracking: true,
+ *   openTracking: true
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * console.log('Message sent:', receipt.messageId);
+ * ```
+ */
+declare class SendGridTransport implements Transport {
+  config: ReturnType<typeof createSendGridConfig>;
+  httpClient: SendGridHttpClient;
+  /**
+   * Creates a new SendGrid transport instance.
+   *
+   * @param config SendGrid configuration including API key and options.
+   */
+  constructor(config: SendGridConfig);
+  /**
+   * Sends a single email message via SendGrid API.
+   *
+   * This method converts the message to SendGrid format, makes an HTTP request
+   * to the SendGrid API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple email messages efficiently via SendGrid API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to SendGrid.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Extracts or generates a message ID from the SendGrid response.
+   *
+   * SendGrid doesn't return a message ID in the response body for successful sends,
+   * so we generate a synthetic ID based on timestamp and some response data.
+   *
+   * @param response The SendGrid API response.
+   * @returns A message ID string.
+   */
+  private extractMessageId;
+}
+//#endregion
+export { SendGridApiError, SendGridConfig, SendGridTransport, createSendGridConfig };

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for SendGrid transport connection settings.
+ *
+ * This interface defines all available options for configuring a SendGrid
+ * API connection including authentication, HTTP options, and tracking settings.
+ *
+ * @example
+ * ```typescript
+ * const config: SendGridConfig = {
+ *   apiKey: 'your-api-key',
+ *   timeout: 30000,
+ *   retries: 3,
+ *   tracking: true
+ * };
+ * ```
+ */
+interface SendGridConfig {
+  /**
+   * Your SendGrid API key.
+   *
+   * You can find your API key in the SendGrid Control Panel under Settings > API Keys.
+   * It should start with 'SG.' for v3 API keys.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the SendGrid API.
+   *
+   * @default "https://api.sendgrid.com/v3"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether to enable click tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly clickTracking?: boolean;
+  /**
+   * Whether to enable open tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly openTracking?: boolean;
+  /**
+   * Whether to enable subscription tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly subscriptionTracking?: boolean;
+  /**
+   * Whether to enable Google Analytics tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly googleAnalytics?: boolean;
+}
+/**
+ * Resolved SendGrid configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the SendGrid transport implementation.
+ */
+type ResolvedSendGridConfig = Required<SendGridConfig>;
+/**
+ * Creates a resolved SendGrid configuration by applying default values to optional fields.
+ *
+ * This function takes a partial SendGrid configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ *
+ * @param config - The SendGrid configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ *
+ * @example
+ * ```typescript
+ * const resolved = createSendGridConfig({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // resolved.baseUrl will be 'https://api.sendgrid.com/v3' (default)
+ * // resolved.timeout will be 30000 (default)
+ * // resolved.retries will be 3 (default)
+ * ```
+ */
+declare function createSendGridConfig(config: SendGridConfig): ResolvedSendGridConfig;
+//#endregion
+//#region src/http-client.d.ts
+/**
+ * Response from SendGrid API for sending messages.
+ */
+interface SendGridResponse {
+  /**
+   * HTTP status code returned by SendGrid.
+   */
+  readonly statusCode?: number;
+  /**
+   * Response body from SendGrid (usually empty on success).
+   */
+  readonly body?: string;
+  /**
+   * Response headers from SendGrid.
+   */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * Error response from SendGrid API.
+ */
+
+/**
+ * HTTP client wrapper for SendGrid API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for SendGrid API calls.
+ */
+declare class SendGridHttpClient {
+  config: ResolvedSendGridConfig;
+  constructor(config: ResolvedSendGridConfig);
+  /**
+   * Sends a message via SendGrid API.
+   *
+   * @param messageData The JSON data to send to SendGrid.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the SendGrid response.
+   */
+  sendMessage(messageData: Record<string, unknown>, signal?: AbortSignal): Promise<SendGridResponse>;
+  /**
+   * Makes an HTTP request to SendGrid API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   */
+  makeRequest(url: string, options: RequestInit): Promise<SendGridResponse>;
+  /**
+   * Makes a fetch request with SendGrid authentication.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the fetch response.
+   */
+  fetchWithAuth(url: string, options: RequestInit): Promise<Response>;
+  /**
+   * Converts Headers object to a plain Record.
+   *
+   * @param headers The Headers object to convert.
+   * @returns A plain object with header key-value pairs.
+   */
+  headersToRecord(headers: Headers): Record<string, string>;
+}
+/**
+ * Custom error class for SendGrid API errors.
+ */
+declare class SendGridApiError extends Error {
+  readonly statusCode?: number;
+  readonly errors?: {
+    readonly message: string;
+    readonly field?: string;
+    readonly help?: string;
+  }[];
+  constructor(message: string, statusCode?: number, errors?: Array<{
+    message: string;
+    field?: string;
+    help?: string;
+  }>);
+}
+//#endregion
+//#region src/sendgrid-transport.d.ts
+/**
+ * SendGrid transport implementation for sending emails via SendGrid API.
+ *
+ * This transport provides efficient email delivery using SendGrid's v3 HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SendGridTransport } from '@upyo/sendgrid';
+ *
+ * const transport = new SendGridTransport({
+ *   apiKey: 'your-sendgrid-api-key',
+ *   clickTracking: true,
+ *   openTracking: true
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * console.log('Message sent:', receipt.messageId);
+ * ```
+ */
+declare class SendGridTransport implements Transport {
+  config: ReturnType<typeof createSendGridConfig>;
+  httpClient: SendGridHttpClient;
+  /**
+   * Creates a new SendGrid transport instance.
+   *
+   * @param config SendGrid configuration including API key and options.
+   */
+  constructor(config: SendGridConfig);
+  /**
+   * Sends a single email message via SendGrid API.
+   *
+   * This method converts the message to SendGrid format, makes an HTTP request
+   * to the SendGrid API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple email messages efficiently via SendGrid API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to SendGrid.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Extracts or generates a message ID from the SendGrid response.
+   *
+   * SendGrid doesn't return a message ID in the response body for successful sends,
+   * so we generate a synthetic ID based on timestamp and some response data.
+   *
+   * @param response The SendGrid API response.
+   * @returns A message ID string.
+   */
+  private extractMessageId;
+}
+//#endregion
+export { SendGridApiError, SendGridConfig, SendGridTransport, createSendGridConfig };